fix(core): improve extension-bundle discovery, error messages, and docs (#530, #534, #531)

[jimhoyd]

Summary

Three related fixes to the init --with / extension-bundle seam, sharing the same code paths in packages/core/src/extension-bundles.ts, init-with.ts and docs/EXTENSIONS.md.

#530 — no discovery path, unknown-name error didn't list valid options

• installBundle in packages/core/src/extension-bundles.ts now includes the valid catalog names (sorted) when a requested bundle isn't in the signed catalog:

  Extension bundle store is not in the signed catalog for extension-bundles@vX.Y.Z; valid names: admin, auth, ui

  (catalog.bundles, already in scope there, is the source.)

• Added urlcode extension-bundles list [--json]: prints the first-party bundle names this core release builds, with a one-line description each. This is a static, baked-in list (BUNDLE_CATALOG_NAMES in extension-bundles.ts, sourced from the same set scripts/prepare-extension-bundles.ts builds and the README workspace table), not a live network catalog fetch — a deliberate tradeoff to avoid a network dependency for a simple listing command, at the cost of it possibly being slightly stale relative to a specific --bundle-release's live catalog (documented in docs/EXTENSIONS.md). install/init --with still verify against the live signed catalog, which remains authoritative.

#534 — release-fetch failure gave a generic, unexplained error

installBundle's failed transport.release(release) call (used by both extension-bundles install and init --with's auto-resolved extension-bundles@v<core>) is now caught and enriched:

Could not fetch extension bundle release extension-bundles@v0.5.10. The extension-bundles release for a core version publishes on a separate workflow after the core release and can take a few minutes (commonly under ten) to appear; if this core version just released, wait and retry. To pin an explicit, already-published release instead, use --bundle-release <tag> (for example an earlier compatible extension-bundles@vX.Y.Z).

The workflow-automation question (wiring extension-bundles.yml into the core release pipeline) is a separate maintainer decision and was intentionally left untouched.

#531 — docs described the retired npm-resolution path as current

Rewrote the "Scaffolding with init --with" section of docs/EXTENSIONS.md:

• Removed the description of resolving @jimhoyd/urlcode-<name> via Node package resolution / installing a compatible package set first — --with has been bundle-only since fix: make urlcode init --with bundle-only, auto-resolving extension-bundles@v<core> #526.
• Corrected the documented ScaffoldRequest interface to match the authoritative type in packages/core/src/extensions.ts (added the missing distribution and acknowledgements fields), and rounded out the ScaffoldResult snippet (provides/requires/after/conflicts, acknowledged, routeNotes, hostBundleExports) which the surrounding prose already described but the code sample omitted.
• Replaced "a name that is not installed refuses with the npm install command" with the actual current refusal (not-in-catalog, listing valid names).
• Added a new "Discovering what's installable" subsection documenting urlcode extension-bundles list and its network-free/possibly-stale tradeoff.
• Documented the enriched release-fetch-failure wording from extension-bundles publish isn't wired to core release, so init --with can 404 with an unhelpful error in the gap #534.
• No CHANGELOG.md/MIGRATION.md exists in this repository (checked repo root and docs/), so no changelog entry was added; noting that here per the issue's ask.

Test plan

• npm run typecheck
• npm run check:code / npm run check:docs (regenerated llms-full.txt via npm run docs:llms, which was stale after the docs edit; no schema changed so docs:reference was a no-op check)
• npm test (777 tests, 776 pass / 1 pre-existing skip)
• npm run verify:workspaces (all six workspace packages, package audit, and test/workspace-scaffold.integration.ts, which exercises init --with end-to-end)
• New/updated tests: test/extension-bundles.test.ts (unknown-name catalog listing, enriched release-fetch-failure message including a check that an unrelated transport error is not rewritten, BUNDLE_CATALOG_NAMES coverage), test/cli.test.ts (extension-bundles list text/--json output and --help listing)

Closes #530
Closes #534
Closes #531

🤖 Generated with Claude Code