[KS] DX checks: dev loop, API docs coverage, templates, CLI, reproducible builds (#170, #171)

[sethwebster]

Refs #170, Refs #171

Developer-experience checks as gate audit steps, registered in e2e/checks/developer-experience.yaml and documented in docs/e2e-flows.md#developer-experience-audits. bun run e2e:audit --audit <name> runs one step. Audit steps now run one at a time, so build and timing steps don't overlap.

Step	Checks	What it does
api-docs	DX-DOCS-01..03	Checks that every public export has TSDoc and no any type, and that every subpath has a docs page. tests/api-docs-coverage.test.ts fails on any new gap. docs/api-undocumented.json lists the known gaps and can only shrink.
cli	DX-CLI-01..02	Runs the SDK's spark bin headless: help for every command, --version, and 12 misuses that must each exit 1 with a one-line message.
templates	DX-TPL-01..02, DX-REPRO-01..02	Packs the SDK, then runs spark create for the macOS, Windows and universal templates in a scratch dir (CI=1, no TTY, scratch SPARK_HOME) and type-checks them. Then two clean release builds of the macOS template, compared file by file. Everything under the scratch dir is unregistered from LaunchServices, and the dir is deleted.
dev-loop	DX-LOOP-01..04	Runs spark dev --clear for the Kitchen Sink and drives its dev build in driver mode (no window, no focus) on a free port. Covers cold start, Fast Refresh (hot update, no reload), JS edits needing no rebuild, a native config change requiring one, and the syntax-error overlay. DevTools has its own checks (#267).

CLI fixes the cli audit found:

• spark sdk, spark add and spark updates without a subcommand said "Unknown command". They now list the subcommands.
• spark --version was rejected. It now prints the version.
• spark dev --help outside an app exited 1 with a require stack. It now prints the options.

Budgets

The dev-loop budgets are for the reference MacBook Air (M1, 8 GB) but were not measured on it. They are 3x what this M4 Max (Mac16,5) measured, rounded up: cold start 45 s, Fast Refresh 2 s per edit, native change detection 5 s.

Verification (this M4 Max, macOS 27, Xcode 27.0)

• api-docs: DX-DOCS-02 passes. DX-DOCS-01 fails: 786 of 1324 exports have no TSDoc ([KS][DX] Document every public export and subpath (786 exports without TSDoc, 9 subpaths without a docs page) #458). DX-DOCS-03 fails: 9 subpaths have no docs page ([KS][DX] Document every public export and subpath (786 exports without TSDoc, 9 subpaths without a docs page) #458). Removing a doc comment fails the test, which I tried with ./app#quit.
• cli: both checks pass. Against the old CLI they fail on the three issues fixed here.
• templates (final run, 567 s): DX-TPL-01, DX-TPL-02, DX-REPRO-01 and DX-REPRO-02 pass.
  • The JS bundle is byte-identical across the two builds. 31 of 35 files are byte-identical.
  • Four files differ because of Apple's tools, and each is checked in a normalized form: main executable (GOT order, LC_UUID), Assets.car, MainMenu.nib, CodeResources ([KS][DX] Release builds: nondeterministic main executable link; spark build changes its own inputs #459).
  • Afterwards no LaunchServices record or scratch dir was left.
• dev-loop (run under ks-lock native):
  • DX-LOOP-01 passes: 10.8 s.
  • DX-LOOP-03 passes: JS edits kept the build compatible in the same process, and the native change was reported in 0.8 s.
  • DX-LOOP-02 fails: edits took 0.3 to 0.6 s but arrive as full reloads ([KS] Dev session: edits full-reload, isolated runtimes don't restart after reload, HMR crash #291).
  • DX-LOOP-04 fails: the LogBox SyntaxError overlay shows and closes, but the fix reloads ([KS] Dev session: edits full-reload, isolated runtimes don't restart after reload, HMR crash #291).
• bun run typecheck: passes.
• bun run e2e:lint: 0 problems.
• bun run test: 2 failures, both on the accepted list: node-runtime (asdf shim) and motion-native frames (display asleep).