CLI: manifest command; defineSettings({ contributed: false }) for sections an extension only reads

[kkdev92]

Summary

vscode-ext-kit manifest <entry> brings the manifest check to the command line. It compares the plan an extension compiles at import time with its package.json — the same comparison assertManifestMatches makes in a test — and reports every disagreement at once, as text or JSON, exiting 1 when there is one.

npx vscode-ext-kit manifest ./out/extension.js            # every disagreement with package.json
npx vscode-ext-kit manifest ./out/extension.js --apply    # add the commands and settings it is missing

--apply adds what the manifest is missing and the source can supply: commands and settings, complete in everything mechanical (id, type, default, enum, scope) and with placeholder titles and descriptions marked TODO, so generated text cannot quietly become user-facing documentation. What a person has to decide is reported and left alone: a view needs a container the declaration does not name, a drifted default has two candidates, and an entry only the manifest has may be there on purpose. The file is written back in its own indentation.

A gap the command found: defineSettings({ contributed: false })

Running the command against a real extension turned up one disagreement that was not a mistake in the manifest. The extension declares editor.tabSize — VS Code's setting — so it can read it through the same typed accessor as its own settings. Nothing in the declaration said the section was not the extension's to contribute, so the check asked package.json for it, and --apply would have added it.

defineSettings now takes contributed: false for a section the extension only reads. describePlan carries the answer (SettingsSectionDescription.contributed), and diffManifest, assertManifestMatches and the command line leave such a section out of the comparison. The default is true, so existing declarations mean what they always did.

This is a small addition to the public API rather than a CLI-only workaround, because whether a section is the extension's is a fact only the declaration knows.

What changed

• bin/vscode-ext-kit.mjs: the manifest subcommand (--manifest, --format text|json, --apply); --format is now validated per command; the usage text covers both commands.
• defineSettings: contributed?: boolean (default true), carried on the definition and in the plan.
• describePlan: SettingsSectionDescription.contributed.
• diffManifest / assertManifestMatches: skip settings groups declared with contributed: false.
• verify:package: runs manifest from the installed tarball, the first check that resolves the package's ./testing entry through a real install.
• Docs: README "Command Line", the guide's settings sample (with an editor section declared as read-only) and its plan section, CHANGELOG.

Verification

• npm run quality: 1080 tests, TypeDoc clean.
• npm run verify:package: both CLI commands work from the installed package.
• Against a real extension (47 commands, 10 settings, 3 views): the command reported exactly the editor.tabSize case; with contributed: false on that declaration and a rebuild, manifest ok: 47 command(s), 10 setting(s), 3 view(s) agree. The extension's own typecheck, 236 unit and 35 integration tests pass against the tarball.

🤖 Generated with Claude Code