feat(extension): app shelf + engine proxy on the amicode service (fork-cutover static and proxy slice, #822)

[aarontrowbridge]

Implements #822 — the fork-cutover static + proxy slice: the extension-host amicode service gains an app shelf (static serving of the built app-bundle dist) and a reverse proxy to the spawned engine, with precedence exact /amicode/ routes → static hit → engine proxy*, and auth accepting both the service's per-boot mint and the engine token.

Acceptance Criteria

• GET / on the service origin serves the app dist's index document; asset requests get correct content types; unmatched GETs fall back to the SPA index; path traversal is refused — test/amicode_service_app_shelf.test.ts (6 tests, incl. raw-socket traversal carriers refused 403, API-style GETs never handed the SPA doc)
• Non-amicode, non-static requests proxy to the engine upstream with method, headers, and body preserved; SSE (/event) streams unbuffered through the proxy — test/amicode_service_engine_proxy.test.ts (mock engine records method/headers/body verbatim; SSE chunks arrive ≥180ms apart — progressive, not buffered) + the live probe's real-engine /session + /event
• The route precedence is asserted: an exact /amicode/* route never shadows behind the proxy, and a static asset hit never reaches the proxy — test/amicode_service_engine_proxy.test.ts "precedence: …" (the mock engine must never see an /amicode/* or /assets hit)
• Auth: a request bearing the engine token is accepted on /amicode/* routes (alongside the service's own mint); proxied engine requests carry the engine token unchanged — accept-both test incl. the unknown-mint-still-401 case; the passthrough test asserts the client's Authorization rides upstream unchanged
• With no dist present and no override set, the shelf serves an honest needs-setup placeholder (never a silent 404-as-app) — needs-setup test (placeholder names the build + override fixes; /amicode/* unaffected) and the live probe asserts a live dist never serves the marker
• The boot proof (env-gated, CI-skipped) boots the real service against the real spawned engine + built dist and asserts: app document from the service origin, an engine API call through the proxy, an SSE connect through the proxy, and one /amicode/* route — end-to-end from the service origin — scripts/amicode_service_boot_probe.mjs esbuild-bundles the REAL service source (no transcribed logic), spawns the vendored engine (password-armed), serves the REAL built dist. Ran it for real: PASS on all four (real build:app output: 4,713-pkg bun install, 13.8s vite build; vendored 1.18.10 engine). CI lane added; it self-skips with the reason printed until the dist-build chore (chore(ci): wire the app-bundle dist build into CI + the release pipeline (the #822 packaging stub's follow-up) #825) lands.

Slices

• app_shelf.ts — static serving: origin doc, content types, SPA fallback (GET + accepts HTML only), traversal refusal, needs-setup placeholder
• engine_proxy.ts — transparent reverse proxy (method/headers/body passthrough, RFC 7230 hop-by-hop strip, SSE unbuffered), honest 503 when the upstream is not bound; never-throwing
• auth accepts the engine token (server.ts authorized() checks both mints, constant-time per mint; Basic is the only carrier the service itself validates — ?auth_token= is the ENGINE's carrier, which the proxy passes through unchanged)
• wiring: startAmicodeService learns the engine upstream (LATE-BOUND URL getter + engine password — the engine restarts on solver-mode switches while the service deliberately does not) + the app dist root; extension.ts boot call-site; the dev-override setting amicode.appBundleDir
• packaging: build:app script (materialize → bun install → vite build → stage to dist/app — verified for real end-to-end); rides the VSIX via the existing dist/ packaging (the fetch:opencode precedent). The CI-time bun build is NOT wired in this slice — the ci.yml boot-proof lane is the honest self-skipping stub, follow-up chore chore(ci): wire the app-bundle dist build into CI + the release pipeline (the #822 packaging stub's follow-up) #825
• env-gated live boot proof script (scripts/amicode_service_boot_probe.mjs, the telaio_app_probe precedent) + its real-service entry src/amicode_service_boot_probe.ts

Honest notes

• The service stays vscode-free; the shelf/proxy never throw; a shelf failure degrades to the placeholder, never kills the /amicode/* route table (asserted).
• Out of scope per the issue: the origin flip, any overlay/app source change, the vendored pin flip.
• chore(ci): wire the app-bundle dist build into CI + the release pipeline (the #822 packaging stub's follow-up) #825 (chore) carries the CI + release wiring of the full dist build (bun on the runner, boot-proof lane flipped to real, packaging-manifest assertion of the app document).

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Team

Run ID: 386cfdd3-137a-4730-bfb9-8eb2150064de

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}