Epic: First-class editor support for Registry Stack project authoring

[jeremi]

Outcome

Registry Stack project YAML has first-class editing support in VS Code and Zed, beginning with a schema-driven 1.0 demo baseline and growing into one shared semantic language server. The editor packages remain thin and do not duplicate the project compiler, security rules, or released Rhai/CEL surface.

Release plan

1.0: useful demo baseline

• Ship schema-driven VS Code and Zed editing for project YAML #394

The 1.0 scope uses the five existing project-authoring JSON Schemas with the editors' normal YAML language servers. It delivers validation, completion, hover documentation, and outlining without waiting for custom semantic tooling.

1.2: shared semantic tooling

• Expose versioned editor metadata and structured project diagnostics #396
• Preserve source spans in project authoring YAML parsing #401
• Implement the Registry Stack project language server MVP #393
• Publish the Registry Stack extension for VS Code #395
• Publish the Registry Stack extension for Zed #397
• Add safe rename, references, and embedded Rhai/CEL editor assistance #398

Dependency order

#394 schema-driven baseline (1.0)

#396 structured diagnostics and editor metadata
#401 span-preserving authoring YAML parsing
  -> #393 shared Registry Stack language server
       -> #395 VS Code extension
       -> #397 Zed extension
       -> #398 references, safe rename, and embedded Rhai/CEL assistance

#396 and #401 can proceed in parallel; #393 depends on both. The VS Code and Zed packaging issues can proceed in parallel once the shared language-server contract and MVP are stable.

Design constraints

• Use the exact schemas, diagnostics, and expression metadata from the selected Registry Stack or registryctl release.
• Do not bind editor behavior to a mutable branch or silently mix incompatible versions.
• Preserve normal YAML editing and avoid claiming unrelated YAML files.
• Keep the compiler's trust-boundary checks, bounded paths, and secret handling intact.
• Do not read secret values, execute project scripts, perform live tests, or make source-registry network requests as a side effect of editing.
• Share semantic behavior through LSP instead of implementing it separately in VS Code and Zed.
• Verify a clean developer journey in both editors, separately from protocol and security tests.

Success criteria

• A 1.0 demo project gets useful schema-driven editing in VS Code and Zed through a short deterministic setup.
• Cross-file paths and project-local references navigate correctly through the shared LSP.
• Invalid syntax and semantic references produce precise, structured diagnostics.
• Both editor integrations use the same language server and version compatibility contract.
• Published extension installation, binary discovery, troubleshooting, and release ownership are documented.
• Advanced rename and expression support never executes authored code or weakens project validation.

[jeremi]

Review pass on this epic and all subtickets (2026-07-17), verified against the current tree and the editor ecosystem. Per-ticket notes are on #394, #396, #393, #395, #397, #398. Cross-cutting outcomes:

1. New subticket Preserve source spans in project authoring YAML parsing #401: span-preserving authoring YAML parsing. Authored YAML is parsed with archived serde_yaml 0.9 and carries no source spans on parsed values, so precise diagnostic ranges (the core value of Implement the Registry Stack project language server MVP #393) had no owner. Implement the Registry Stack project language server MVP #393 now depends on Expose versioned editor metadata and structured project diagnostics #396 plus Preserve source spans in project authoring YAML parsing #401. Recommend keeping Preserve source spans in project authoring YAML parsing #401 out of 1.0: churning the authoring module during release hardening is the wrong moment.

2. Decide where the extensions live. The monorepo has no JS/extension owning area. Separate repositories versus a new editors/ area changes CI, DCO, and release wiring for Publish the Registry Stack extension for VS Code #395/Publish the Registry Stack extension for Zed #397; deciding once at the epic level avoids rework.

3. The version handshake needs an owner. The "no silent version mixing" constraint should land concretely in Expose versioned editor metadata and structured project diagnostics #396: the server announces contract version plus registryctl version at initialize, and clients check a compatibility range.

4. Cheap win once Implement the Registry Stack project language server MVP #393 exists: Neovim and Helix support is a one-page "attach any LSP client" doc; worth folding into Implement the Registry Stack project language server MVP #393's documentation AC.

5. Two acceptance criteria are not automatable as written (Implement the Registry Stack project language server MVP #393's "proves behavior through Zed language clients" and Publish the Registry Stack extension for Zed #397's tested-paths list): no headless Zed extension harness exists as of mid-2026. Reworded suggestions are on those tickets.

6. 1.0 scoping confirmed: Ship schema-driven VS Code and Zed editing for project YAML #394 is generator plus docs with no new runtime surface and fits 1.0; everything else stays 1.2.

[jeremi]

Decision recorded 2026-07-23: keep both editor integrations in the registry-stack monorepo.

• VS Code package: editors/vscode/
• Zed package: editors/zed/
• Keep the language server and authoritative compiler/security behavior in shared Rust code. The editor packages remain thin clients.
• Use the version handshake owned by Expose versioned editor metadata and structured project diagnostics #396 so clients reject incompatible language-server contracts instead of silently mixing releases.
• Package VS Code from its subdirectory. Publish Zed from the monorepo using the extension registry's supported subdirectory path; keep the required extension metadata and license at that path.
• Isolate marketplace publishing credentials from runtime code and preserve this epic's no-secret-read, no-script-execution, no-live-test, and no-source-registry-request constraints.
• The remaining semantic tooling and extension packaging stay in the 1.2 scope.

Separate repositories are not justified now. Reconsider extraction only if an extension later gains independent maintainers, contribution boundaries, or a materially different release cadence.

References: VS Code extension publishing, Zed extension development and publishing.