Repository navigation
feat(fsdev): serve an app's pages beside the Lab (FIX-1770 PR-A) - #2735
Conversation
fsdev dev --app <package|dir> serves an app's built pages at the root of the port beside /api/flows, and moves the DevTool to a port of its own over the same runtime, handing each page its address as the fsdev-devtool-url meta. --host binds loopback by default; a non-loopback host runs the fsdev serve guard (--allow-unauthenticated overrides), refuses a config that hands its page a bearer, and leaves the anonymous debug surface closed. @flow-state-dev/node serve() gains pageMeta and a Connect-style pageHandler (after a real file and a dedicated route, before the SPA fallback); createPageHtmlTransform is the one HTML writer both use. A source check holds the layer line: the hook modules import no Workforce or Shift Manager module and name none of their concepts. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018KBgKPRLfqjmV2LS88Eg9S
|
The latest updates on your projects. Learn more about Vercel for GitHub. 3 Skipped Deployments
|
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
Bugbot couldn't run - usage limit reachedBugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit. A user or team admin can review and increase usage limits in the Cursor dashboard. (requestId: c961deed-c641-4789-80d3-d24a724ed01c) |
Second look + architecture pass (read-only review)Reviewed against the approved direction (D1–D3 not re-argued). Findings ranked; only the first two are worth acting on before merge. 1. Shutdown can hang on a rejected close —
|
There was a problem hiding this comment.
Problem
Outside users and in-repo Shift Manager developers need one fsdev dev process that serves an app's pages on the main port, keeps /api/flows same-origin, and still gives the DevTool a URL the app shell can read — without fsdev learning Workforce vocabulary.
Verdict
Approve. D1 (fsdev owns the hook; node gets generic pageMeta + pageHandler) is the right split, and PR-A stays intentionally narrower than the epic (no Vite/watch yet). The extra surface area is mostly tests, spec, and the dual-listener orchestration that falls out of the DevTool needing / for its own assets.
I would not chase a proxy-based or single-serve() design in this PR: same-origin API + DevTool on its own origin is a product constraint, not accidental complexity.
What looks appropriately simple
dev-app.tsas a small resolver (getAssetPath()contract, path-vs-package heuristic) — right size for S3.createPageHtmlTransformreusing existinginsertBeforeHeadClose/injectDevtoolConfig— one HTML injection path for static pages and future Vite middleware (PR-B).executeDevCommandreturningDevServer+ programmaticpageMeta— sets up S8/S9 without another bespokestart.mts.- Layer-boundary test intent (no Workforce imports in the hook) — good guardrail for tenet 4.
Simplify follow-ups (non-blocking)
-
executeDevCommandsize (~280 lines orchestration). Consider extractingstartDevListeners({ serveApp, appPages, devtoolAssets, host, port, pageMeta, … }) → { url, devtoolUrl, close }so the command stays flag parsing + runtime resolution + error mapping. Pure readability; behavior can stay identical. -
Duplicate
getAssetPath()package loading —dev-app.tspackageAssetPathandresolveDevToolAssets()indev.tsshare the samecreateRequire→ dynamic import →getAssetPath()shape (DevTool keeps monorepo fallbacks). A sharedresolvePackageAssetDir(name, cwd, { fallbacks? })inpackages/cli/src/would shrink the diff and keep PR-C's Shift Manager wrap simpler. -
HTML head passes — when both
pageMetaand loopbackdevtoolConfigapply,createPageHtmlTransformrunsinsertBeforeHeadClosetwice (meta, theninjectDevtoolConfig). Merging into one tag string before a single insert is a small hot-path win on largeindex.htmlshells; optional unless profiling says otherwise. -
Layer-boundary word scan —
FORBIDDEN_WORDmatches common English (teams,shifts, …) on every line, including comments. That already pressures awkward wording inserve.ts. Tightening to import lines only (keep the planted-word case in the self-test) would preserve the signal with less brittleness. -
Tiny DRY — port parsing (
/^\d+$/+ range) is duplicated withserve.ts;urlHostduplicates Shift Manager'sstart.mts. Fine to defer until S8 deletesstart.mts, but a one-liner innodeorfsdevwould stop a third copy.
Alternatives considered (and why I'd stay on this PR)
| Alternative | Why I wouldn't swap mid-PR-A |
|---|---|
http-proxy / Vite server.proxy for /api |
Fights the stated same-origin contract; Vite proxy stays for "Vite-only" until S6 middleware mode. |
@hono/node-server/serve-static instead of hand-rolled static read |
Still need HTML transform + strict route order (static → dedicated → pageHandler → SPA). Refactor is wider than PR-A's slice. |
Cheerio/parse5 for </head> injection |
Matches existing regex injection; dependency doesn't buy much for dev-local HTML. |
Collapse dual serve() into subpath-hosted DevTool |
Contradicts DevTool asset layout unless DevTool gains a configurable base URL (out of scope). |
Skipped (needs later PR or product call)
- Thin second listener that proxies only
/api/*to the primary port (one runtime, less duplicate Hono stack) — worth revisiting only if dual-server memory/startup hurts. - Replacing hand-rolled static serving wholesale — wait until HTML-hook requirements are stable post PR-B.
Verification
Ran pnpm --filter @flow-state-dev/fsdev test (311 passed) and pnpm --filter @flow-state-dev/node test including serve.test.ts (60 passed).
Sent by Cursor Automation: Review For Best Approach
There was a problem hiding this comment.
Code Snob — too small to rewrite (7f892f67).
I read packages/cli/src/commands/dev.ts, packages/cli/src/dev-app.ts, packages/node/src/serve.ts, packages/node/src/page-html.ts, packages/node/src/devtool-config-injection.ts, and the new tests in packages/cli/test/dev-app.test.ts, packages/node/test/serve.test.ts, and packages/cli/test/layer-boundary.test.ts.
A rewrite would not shrink this contract. createPageHtmlTransform and pageHandler are the page options the next PR calls; runPageHandler is the Connect adapter (finish, close, next). Folding page-html.ts into the injection module deletes a file header and leaves the same function. dev-app.ts is one failure branch per message the tests assert. The second serve() and DevServer.close are the two-port shutdown. The port check and network guard already match fsdev serve; a shared helper would be a new module for those lines. The layer scan is the source check the plan names.
No POC.
Sent by Cursor Automation: Code Snob
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 7f892f67d7
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…ol address, drain both servers before disposing (FIX-1770) Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018KBgKPRLfqjmV2LS88Eg9S


The problem
People outside this repository cannot run Shift Manager. It starts only from a checkout, through a start script that copies its pages and writes the DevTool address into them. Any other app that must sit beside a Lab must copy that script.
What this does
This is PR 1 of 3 in a stack (spec D3). It adds the generic part: fsdev can serve the pages of any app beside the Lab. Shift Manager does not change in this PR.
This PR builds the bottom layer of the "after" side: fsdev's app hook and the two
nodeoptions.--watchcomes in PR-B. The published command comes in PR-C.fsdev dev --app <package|dir>serves the app's built pages at the root of the port. The API stays at/api/flowson the same origin. The DevTool moves to its own port over the same runtime. Each page gets the DevTool address as<meta name="fsdev-devtool-url">. If the DevTool is not installed, the app starts, the command says why, and the page gets no address.fsdev dev --hostbinds127.0.0.1by default. A non-loopback host runs thefsdev serveguard (--allow-unauthenticatedoverrides it). It refuses a config that gives its page a bearer token. It keeps the anonymous debug surface closed.serve()in@flow-state-dev/nodegetspageMeta(meta tags in every HTML page, on any host) andpageHandler(a Connect-style handler that runs after a real file and a dedicated route, before the SPA fallback).createPageHtmlTransformis the one function that writes HTML for both.What's asked of you
Nothing. This PR implements the approved direction. D1–D3 were settled at the spec gate. The engineering calls are below the fold.
Parts worth reviewing closely
For the code reviewer.
runPageHandlerinpackages/node/src/serve.ts. It runs a Connect handler on the raw Node request inside Hono. Then it returnsRESPONSE_ALREADY_SENT. It resolves onfinish/closeor onnext(). Nothing in PR-A uses it yet. Its first real user is Vite in PR-B, so that is where an edge case will show. This is my weakest spot.executeDevCommand. Twoserve()handles share one FlowState. They close together, and disposal is idempotent. The command now returns aDevServerhandle (before, it returnedvoid). A second signal during shutdown is still ignored.--host. It is now refused, because the discovered router has no auth to check. The spec did not name this case.Links: Implements FIX-1770 (PR-A of 3) · spec
specs/issues/FIX-1770/onmain· spec review #2734 · goal check: none in this PR (VG runs in PR-C, per PLAN) · merges before PR-B.How to review this
Engineering calls
pageMeta,pageHandler, andcreatePageHtmlTransform(exported) for "one injection path". If wrong: a rename before PR-C publishes.--portis strict for allfsdev devruns:12abcand80.5are refused, exit 3, the same asfsdev serve. Before,parseInttruncated them. The banner prints the bound port, so--port 0shows the real port. If wrong: someone who typed a bad port gets an error instead of a silent wrong port.--hostwithout a config is refused (exit 3). If wrong: one more case needs a config.FSDEV_DEBUG_ENDPOINTSandFSDEV_DEBUG_ALLOW_ANONYMOUS_LOCAL, and alsoFSDEV_TRACING_LEVEL. If wrong: less trace detail on a network bind.http://127.0.0.1:PORT/). The banner keepslocalhostfor the default bind. On a wildcard bind (0.0.0.0) the meta says0.0.0.0, asstart.mtsdoes today. PR-C can refine this.--apppackage resolution usescreateRequirefrom the working directory, so the package'sexportsneeds adefault(orrequire) condition, as every package in this repo has.pageMetaHTML is servedno-store, the same as the bearer HTML, because the DevTool address changes per run.DOCS.md. Nodocs-writer/docs-editorsub-agent was available in that session.Verification
pnpm typecheck(whole repo, incl. boundary validators): exit 0.pnpm --filter @flow-state-dev/node test: 60 passed.pnpm --filter @flow-state-dev/fsdev test: 311 passed.labs/shift-managertest/start.test.ts: 10 passed.tsx src/bin.ts dev --config … --app <dir> --port 4911 --no-openserved the page and/api/flows. The DevTool was not built, so the command said so. SIGINT printed "Shutting down..." and the process exited.Red states, captured before each implementation:
pageMetatests failed ("expected … to contain<meta name=…"). The byte-identical test has no before-state. Blast radius: making the transform always present failed exactly that test and the existing non-loopback no-store test, and nothing else (52 others passed).pageHandlertests failed. The two ordering tests ("never sees a file/API/health/non-GET" and "dedicated route wins during cold start") had no before-state. Blast radius: moving the handler ahead of the file and dedicated checks failed exactly those two and the fallback test, and nothing else (57 passed).DevTool assets not found, and no refusals). BR-14 blast radius: removing the loopback gate on the debug defaults failed only the "debug surface closed" test. Forcing the defaults off failed only the two loopback debug tests.import { hireWorkforce } from "@flow-state-dev/workforce"indev.ts, and changing serve.ts back to "worker runtime", failed exactly those two files' checks and the self-test, and nothing else. The committed self-test also flags a planted import and a planted word.Files
packages/node/src/page-html.ts(new):createPageHtmlTransform.serve.ts:pageMeta,pageHandler,PageHandler.devtool-config-injection.ts: sharedinsertBeforeHeadClose.packages/cli/src/dev-app.ts(new):--appresolution.commands/dev.ts:--app,--host,--allow-unauthenticated, programmaticpageMeta,DevServerhandle,DEVTOOL_URL_META.node/test/serve.test.ts,cli/test/dev-app.test.ts,cli/test/layer-boundary.test.ts, fixturedevtool-bearer.apps/docs/docs/api/cli.md(rows and "Serving an app beside your flows" without--watch),configuration/runtime.md(debug defaults are loopback-only),packages/cli/README.md,packages/node/README.md.patchfor@flow-state-dev/fsdevand@flow-state-dev/node.🤖 Generated with Claude Code
https://claude.ai/code/session_018KBgKPRLfqjmV2LS88Eg9S
Generated by Claude Code
Note
Medium Risk
Changes dev-server binding, authentication guards, and HTML injection paths that can expose credentials or debug surfaces; behavior is heavily tested but dual-server shutdown and
pageHandlerintegration are new surface area.Overview
Adds a generic dev hook so any app's built pages can sit beside the flow API on one origin, without app-specific scripts in fsdev.
fsdev devgains--app <package|dir>(resolves a directory orgetAssetPath()package): the app is served at the port root with/api/flowsunchanged; the DevTool moves to a second port on the same runtime and its URL is injected asfsdev-devtool-urlmeta (DevTool optional when--appis set).executeDevCommandnow returns aDevServerhandle withclose();--portrejects non-integer values.--hostand--allow-unauthenticatedalign non-loopback binds withfsdev serve: auth is checked, configs with devtool bearer tokens are refused, discovery-only mode without a config is refused on network hosts, and privileged debug env defaults apply only on loopback.@flow-state-dev/nodeserve()addspageMeta, a Connect-stylepageHandler(after static files and dedicated routes, before SPA fallback), and exportedcreatePageHtmlTransformfor one HTML injection path (meta on any host; devtool config loopback-only).Reviewed by Cursor Bugbot for commit 7f892f6. Configure here.