feat: deliver and qualify the official HTTP catalog registry

[lloydrichards]

Deliver the official HTTP catalog to the CLI and Recipe Builder, then prove that the deployed assets and shipped clients work together. This is the parent issue for the five implementation tasks and owns the final release checks.

Product decisions

• Serve the current catalog at https://stack-effect.lloydrichards.dev/registry/v1/catalog.json. /v1/ versions the JSON protocol, not individual content releases.
• Allow additions and template fixes while preserving published IDs and the v1 interpreter capability set. Output can change between commands or sessions as content changes.
• Keep catalog payloads, catalog semver, version pins, and catalog lockfiles out of project repositories. Older configs use the official source internally.
• Attempt current data on every catalog-dependent command and new builder session. During an outage, use a validated compatible cache with a warning. Without usable data, fail clearly. Invalid documents and unsupported capabilities are errors, not reasons to serve stale content.
• Keep one loaded catalog throughout each operation. Preserve the existing Selection, Blueprint, Plan, Apply, and Finalize responsibilities.
• Publish a JSON Schema for stack.effect.json at https://stack-effect.lloydrichards.dev/schemas/v1/stack.effect.schema.json. New configs get optional $schema editor metadata. The CLI still validates with its installed domain schema.
• Deliver the official source first. Community design design: define community HTTP catalog sources #276 is a separate follow-up and does not block this milestone.

Child deliverables

Issue	Deliverable
#249	Explicit catalog composition, validation, and injection through all consumers.
#271	The JSON format, shared HTTP loader, cache interface, and failure rules.
#272	Generated catalog and config-schema assets, plus verified docs hosting.
#273	CLI integration and a user-level filesystem cache.
#274	Recipe Builder integration, browser persistence, and visible cache state.

#249 precedes #271. After #271, publication and client adapters can proceed separately. #272 owns the shared StackConfig declaration needed by both client integrations. Native blockers record completion dependencies, not a ban on independent preparatory work.

Deliver the release evidence

Use one controlled catalog document to compare real CLI and browser generation. Cover representative Node, Bun, and Deno configurations, shared JSX contributions, incremental add, and runtime exclusions. Show that a later operation can use a changed compatible document without replacing an in-flight catalog.

Exercise a registry outage with and without usable cached data. Confirm that invalid documents and unsupported capabilities still fail. Child issues own focused loader and adapter tests; reuse that evidence rather than duplicating each test here.

Inspect the published CLI and worker builds for bundled catalog templates. Confirm that repository authoring scripts still use local definitions. Reuse #272's deployed endpoint evidence and repeat it if a later deployment changes the relevant behavior.

Record compressed response size, request and parse time without a cache, and CLI and worker bundle changes. Do not turn unmeasured performance targets into release requirements.

Done when

• All five child deliverables are complete, with links to their implementation and validation evidence.
• The same catalog and inputs produce matching Blueprint and generated file results through the CLI and browser workflows.
• End-to-end tests demonstrate cache fallback, failure without a usable cache, invalid-document refusal, and a compatible content update.
• Production artifacts exclude authoring templates, and generated projects contain no catalog payload or version pin.
• Real endpoints supply JSON, conditional-request behavior, required CORS headers, and genuine 404 responses before dependent clients ship.
• User documentation, agent guidance, and affected generated CLI reference pages describe the new behavior. Update OKF to distinguish implemented behavior from the accepted decision.
• The release record includes endpoint readiness, rollback instructions, and the measurements described here.

Dependencies and exclusions

Blocked by #272, #273, and #274. #249 and #271 are also child prerequisites through that chain. Keep #180 and #181 as coordination work, not whole-refactor blockers. #250 is already closed. Generated workspace artifacts in #252 and compiled profiles in #254 remain separate.

Do not add runtime architecture, a catalog version archive, VFS transport, or community features here. Route defects found during these checks to the owning child issue. Follow the normal deployment and release process.

Validate

Run bun format, bun lint, bun run type-check, affected bun run test --filter=<workspace> commands, and production builds. Never use bun test. Run host smoke tests in temporary repositories and remove them with trap ... EXIT. Report local tests, clean-checkout checks, and deployed checks separately.

[pullfrog]

No duplicate found: #271 covers the shared loader, #272 publication, and #273/#274 the two client integrations; this issue is the distinct cross-consumer release gate. The current CatalogService still builds from local registries, and both apps/cli/src/services.ts and the Recipe Builder worker provide that bundled layer, so qualification should follow those integrations rather than treat today's behavior as HTTP evidence.

Suggested qualification sequence after #272–#274 land:

1. Serve a fixed exported document through a controlled HTTP fixture. Drive real CLI command wiring and the browser worker/session against those same bytes; compare Selection/Blueprint, generated file paths and contents, and config output for representative Bun, Node, and Deno recipes, shared JSX contributions, incremental add, and runtime exclusions. Replacing the fixture with a compatible revision must affect a new operation, never an in-flight one.
2. Exercise warm-cache outage and cold-cache failure in both clients, plus invalid 200, unknown protocol/capability, and genuine 404 refusal even with a warm cache. Check CLI stderr versus structured stdout and the builder's persistent stale notice/retry. Keep focused loader/cache assertions in feat: load the HTTP catalog with validated cache fallback #271 rather than duplicating its unit matrix.
3. In a clean checkout, run scoped CLI/docs tests, bun format, bun lint, bun run type-check, and temporary-repo host smoke tests with trap cleanup. Inspect the packaged CLI and built worker dependency graph for authoring templates; confirm generated repositories contain neither payload nor pin and root authoring scripts still use local definitions.
4. Record local, clean-checkout, and deployed evidence separately: live catalog/schema JSON, MIME/cache/validator/CORS behavior and registry 404, cold request/parse timings, compressed size, and CLI/worker bundle deltas. Update docs/CLI reference and the accepted architecture decision, and do not release dependent clients until feat: publish the official catalog and StackConfig JSON Schema #272's production publication is verified via the normal deployment process. Route any defects back to their owning issue.

  ^{｜ Implement a fix ➔ ｜ View workflow run ｜ via Pullfrog ｜ Using GPT Sol ｜ 𝕏}

[lloydrichards]

Parent qualification is in draft PR #284. The five implementation PRs are #278 (composition), #280 (protocol/loader), #281 (publication), #282 (CLI), and #283 (Recipe Builder). All five have passing CI; #284 CI is running. The stack remains unmerged.

Local evidence: one controlled official JSON document produces matching Blueprint and generated file results in the CLI engine and browser worker for Bun, Node, and Deno. Browser tests also cover a changed compatible document across sessions, cached fallback after reload, refusal of invalid content or cold-cache outage, stale preview rejection, and unsupported Deno modules. CLI tests cover a changed compatible document across commands. #282's green E2E matrix covers init and incremental add. Repository checks (bun format, bun lint, bun run type-check, bun run okf:check), scoped CLI/docs tests, and production builds pass on the stacked workspace. The local generated-project install step was limited by sandbox EPERM; the corresponding CI E2E passed.

Built artifact inspection: official catalog JSON is 353,514 bytes, or 63,358 bytes with gzip level 9; schema JSON is 3,060 bytes, or 462 bytes gzip. The current minified CLI bundle is 8,223,474 bytes (1,943,766 gzip), and Recipe Builder worker is 7,322,825 bytes (1,649,910 gzip). The worker has no inspected catalog authoring/template markers; local authoring continues to use @repo/catalog/authoring. Exact before/after bundle deltas and deployed request-plus-parse timing remain unmeasured, so neither is a release claim. Generated project config has a schema link, not a catalog payload or version pin.

Release blocker: on 2026-09-27, both official URLs (https://stack-effect.lloydrichards.dev/registry/v1/catalog.json and https://stack-effect.lloydrichards.dev/schemas/v1/stack.effect.schema.json) still returned HTTP 404 with text/html. The current PR preview redirects to Vercel SSO. Thus JSON delivery, ETag/304, CORS, genuine missing-path 404, and no-cache request/parse timing are not yet verified on a public deployment. Run the checks in apps/docs/REGISTRY-DEPLOYMENT.md after publication is merged and deployed, before releasing the dependent clients. Roll back a bad catalog or schema by redeploying the previous known-good Vercel production deployment, verifying both asset URLs, then fixing source and redeploying.

[lloydrichards]

Qualification update on the latest PR stack:

• PR test(registry): qualify CLI and browser catalog parity #284 now runs the actual CLI create command against a controlled catalog for Bun, Node, and Deno, then compares generated files with Recipe Builder previews. It also runs CLI create followed by add and compares files contributed by the added target.
• A revised catalog changes generated file content, so the tests check that a current browser session stays stable and the next session and CLI command use the new content.
• PR feat(docs): load registry in Recipe Builder #283 fixes Pullfrog's cached Retry finding and an invalid shared link that previously left a misleading loading notice. PR feat(catalog): load and validate HTTP catalogs #280's template syntax finding was fixed and accepted by Pullfrog re-review.
• Local formatting, lint, type checks, OKF checks, scoped CLI/docs tests, and builds passed before the latest push. New clean-checkout CI and Pullfrog reviews are running; those results are separate from local checks.
• The public catalog and schema endpoints previously returned HTTP 404, and the preview required Vercel SSO. This is still unverified deployed behavior. Keep feat: publish the official catalog and StackConfig JSON Schema #272, feat: load the official registry in CLI commands #273, feat: load the official registry in Recipe Builder #274, and feat: deliver and qualify the official HTTP catalog registry #275 open until public endpoint checks pass.

[lloydrichards]

Latest qualification result: clean-checkout CI passed on PRs #282, #283, and #284, including the CLI init/add and generated-project matrix jobs. Pullfrog re-reviewed the current #283 and #284 heads and accepted the fixes to its reported findings. The local GitButler working tree is clean.

The deployed release check is still open: both https://stack-effect.lloydrichards.dev/registry/v1/catalog.json and https://stack-effect.lloydrichards.dev/schemas/v1/stack.effect.schema.json returned HTTP 404 in the latest public check. Keep #272, #273, #274, and #275 open until the publication PR is deployed and its HTTP behavior is verified.