feat(plan): describe a compiled plan as JSON

[kkdev92]

Summary

The framework knows exactly what an extension registers — compiling declarations before running them is the whole design — but that knowledge was locked inside an ApplicationPlan, which holds factories, handlers and token objects and cannot be printed, diffed or serialized.

describePlan(plan) projects it to JSON:

const description = describePlan(app.plan);

description.commands;   // [{ id: 'sample.refresh', title: 'Refresh', textEditor: false, validated: true, dependencies: { repository: 'projects.repository' }, moduleId: 'projects' }]
description.services;   // [{ token: 'projects.repository', lifetime: 'singleton', dependencies: { clock: 'projects.clock' }, moduleId: 'projects' }]
description.settings;   // [{ section: 'sample.projects', policy: 'lenient', values: [{ key: 'sample.projects.enabled', type: ['boolean'], default: true, scope: 'resource' }] }]

Module ids and host requirements, service tokens with their lifetimes and dependency edges, command ids and titles, settings keys and defaults, storage versions and migrations, watcher globs, view ids, raw registration ids — and nothing callable.

Why it is worth having

• Review. git diff on a large module shows that a file changed; this shows that the extension now registers a command it did not, or that a service gained a dependency. The output is deterministic and in declaration order, so committing it makes topology changes visible next to code changes.
• Tooling. The same document is what a package.json cross-check needs (ids, types, defaults, scopes) and what a dependency diagram needs (tokens and edges).
• Reading an unfamiliar codebase. It is the honest answer to "what does this extension actually register?", which is otherwise assembled by hand from every defineModule call.

Boundaries

• Nothing callable or opaque crosses: no factories, handlers, schemas, providers or token objects. A test walks the whole document and fails on any function.
• Secret keys appear — a declared key is metadata the extension's own source states in the clear. Secret values do not exist at plan time.
• Storage defaults are omitted; settings defaults are kept, because the manifest declares them and a cross-check needs to compare them.
• It is a projection, not a handle: nothing in it can be resolved, called or mutated.

Notes

The tokens the Application registers itself are now named once as FRAMEWORK_SERVICES, because preflight and this projection need the same list — preflight so a module injecting Notifications is not reported as depending on nothing, and the description so a reader of the graph can tell which tokens need no declaration.

Ownership is recovered by object identity rather than by reading a field: settings, storage, secrets and UI items carry no module id of their own, and the plan's flat lists hold the very objects the modules hold.

Verification

Additive; no existing type or signature changes. npm run quality (1056 tests) and npm run verify:package pass.

Fourteen new tests cover determinism, JSON round-tripping, the no-functions boundary, every declaration kind, both glob spellings, migration versions sorted independently of declaration order, and module attribution for the declarations that do not name their own module.

A published extension built on this package was run against this build with its own sources untouched: type-check, lint and 271 tests pass.

🤖 Generated with Claude Code