Skip to content

feat(fsdev): serve an app's pages beside the Lab (FIX-1770 PR-A) - #2735

Merged
jhoffner merged 2 commits into
mainfrom
claude/project-thread-ibr67c
Oct 4, 2026
Merged

jhoffner merged 2 commits into
mainfrom
claude/project-thread-ibr67c

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 4, 2026 •

Copy link
Copy Markdown
Collaborator

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.

Before: two terminals and a lab script, checkout only. After: one installed command over fsdev's app hook and node's serve()

This PR builds the bottom layer of the "after" side: fsdev's app hook and the two node options. --watch comes 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/flows on 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 --host binds 127.0.0.1 by default. A non-loopback host runs the fsdev serve guard (--allow-unauthenticated overrides it). It refuses a config that gives its page a bearer token. It keeps the anonymous debug surface closed.
  • serve() in @flow-state-dev/node gets pageMeta (meta tags in every HTML page, on any host) and pageHandler (a Connect-style handler that runs after a real file and a dedicated route, before the SPA fallback). createPageHtmlTransform is 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.

  1. runPageHandler in packages/node/src/serve.ts. It runs a Connect handler on the raw Node request inside Hono. Then it returns RESPONSE_ALREADY_SENT. It resolves on finish/close or on next(). 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.
  2. Shutdown in executeDevCommand. Two serve() handles share one FlowState. They close together, and disposal is idempotent. The command now returns a DevServer handle (before, it returned void). A second signal during shutdown is still ignored.
  3. Discovery path with a non-loopback --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/ on main · spec review #2734 · goal check: none in this PR (VG runs in PR-C, per PLAN) · merges before PR-B.

How to review this

How to review this. This implements an approved spec — the approach and the numbered decisions in its DECISIONS.md are already signed off by a human, so please review the code against that direction, not the direction itself. The canonical set is retained at specs/issues/<ISSUE-ID>/ on main; Linear links to it and the original merged spec PR, which keeps review history. Follow-up amendment PRs explain later direction changes. Current architecture docs remain the authority for shipped behavior (BP-037).

Most valuable here: correctness on the second path (the legacy shape, the null boundary, the concurrent case, the cancel path), anything deriving an auth or routing decision from caller-controllable input, and a behaviour the tests assert around rather than on.

Already settled upstream: the approach and every decision in the spec's DECISIONS.md (human-approved — if one is wrong, say so as a spec finding and it gets folded back; don't re-argue it inline), and the conventions in docs/contributing/best-practices.md.

Engineering calls
  • Option names: pageMeta, pageHandler, and createPageHtmlTransform (exported) for "one injection path". If wrong: a rename before PR-C publishes.
  • --port is strict for all fsdev dev runs: 12abc and 80.5 are refused, exit 3, the same as fsdev serve. Before, parseInt truncated them. The banner prints the bound port, so --port 0 shows the real port. If wrong: someone who typed a bad port gets an error instead of a silent wrong port.
  • No-host discovery refusal: a non-loopback --host without a config is refused (exit 3). If wrong: one more case needs a config.
  • Debug env defaults skipped on a network bind: FSDEV_DEBUG_ENDPOINTS and FSDEV_DEBUG_ALLOW_ANONYMOUS_LOCAL, and also FSDEV_TRACING_LEVEL. If wrong: less trace detail on a network bind.
  • The DevTool URL in meta uses the literal bound host (for example http://127.0.0.1:PORT/). The banner keeps localhost for the default bind. On a wildcard bind (0.0.0.0) the meta says 0.0.0.0, as start.mts does today. PR-C can refine this.
  • --app package resolution uses createRequire from the working directory, so the package's exports needs a default (or require) condition, as every package in this repo has.
  • pageMeta HTML is served no-store, the same as the bearer HTML, because the DevTool address changes per run.
  • One serve.ts header word changed ("worker runtime" became "background-job runtime") so that the V4 source check passes on the hook modules.
  • Docs prose was written by the implementing agent from DOCS.md. No docs-writer/docs-editor sub-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-manager test/start.test.ts: 10 passed.
  • Real CLI smoke: tsx src/bin.ts dev --config … --app <dir> --port 4911 --no-open served 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:

  • V1 (S1): 4 of 5 pageMeta tests 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).
  • V1 (S2): 4 of 6 pageHandler tests 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).
  • V2/V3 (S3, S4): 21 of 23 failed before (the servers started but nothing was returned, 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.
  • V4: putting import { hireWorkforce } from "@flow-state-dev/workforce" in dev.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: shared insertBeforeHeadClose.
  • packages/cli/src/dev-app.ts (new): --app resolution. commands/dev.ts: --app, --host, --allow-unauthenticated, programmatic pageMeta, DevServer handle, DEVTOOL_URL_META.
  • Tests: node/test/serve.test.ts, cli/test/dev-app.test.ts, cli/test/layer-boundary.test.ts, fixture devtool-bearer.
  • Docs: 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.
  • Changesets: patch for @flow-state-dev/fsdev and @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 pageHandler integration 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 dev gains --app <package|dir> (resolves a directory or getAssetPath() package): the app is served at the port root with /api/flows unchanged; the DevTool moves to a second port on the same runtime and its URL is injected as fsdev-devtool-url meta (DevTool optional when --app is set). executeDevCommand now returns a DevServer handle with close(); --port rejects non-integer values.

--host and --allow-unauthenticated align non-loopback binds with fsdev 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/node serve() adds pageMeta, a Connect-style pageHandler (after static files and dedicated routes, before SPA fallback), and exported createPageHtmlTransform for one HTML injection path (meta on any host; devtool config loopback-only).

Reviewed by Cursor Bugbot for commit 7f892f6. Configure here.

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
@vercel

vercel Bot commented Oct 4, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Oct 4, 2026 9:31pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 4, 2026 9:31pm UTC
flow-state-dev-ui Ignored Ignored Preview Oct 4, 2026 9:31pm UTC

Request Review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 4, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-04T21:26:30.124781Z 7f892f6 PR opened
ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@linear-code

linear-code Bot commented Oct 4, 2026

Copy link
Copy Markdown

FIX-1770

@cursor

cursor Bot commented Oct 4, 2026

Copy link
Copy Markdown
Contributor

Bugbot couldn't run - usage limit reached

Bugbot 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)

jhoffner commented Oct 4, 2026

Copy link
Copy Markdown
Collaborator Author

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 — packages/cli/src/commands/dev.ts (onSignal)

void close().then(() => process.exit(EXIT_SUCCESS)) has no rejection path. If either handle.close() or devtoolHandle.close() rejects, closing stays a rejected promise, the SIGINT/SIGTERM handlers are never removed, a second signal is ignored (closing !== undefined), and the process neither exits nor retries. The old code had the same shape, but two servers sharing one FlowState makes a failed close more likely. Suggest .catch(report).finally(() => process.exit(...)) (exit non-zero on failure), and a test that a rejecting close still exits.

2. Port parsing is now duplicated verbatim — dev.ts:129 and serve.ts:75

The PR deliberately makes fsdev dev --port match fsdev serve, then copies the /^\d+$/ + range check instead of sharing it. This is the opportunity to extract one parsePort(input) into cli-options (or similar) and use it in both commands, so they can't drift again. Small, and it removes the thing the PR is trying to unify.

3. pageHandler / runPageHandler ships with no caller (restraint)

The PR itself says nothing uses it until PR-B and calls it the weakest spot. It adds public API (PageHandler, ServeOptions.pageHandler), a raw-IncomingMessage/RESPONSE_ALREADY_SENT bridge into Hono, and a new route ordering contract, all validated only by synthetic handlers. Leaner shape: land pageMeta, createPageHtmlTransform, and --app/--host here, and add pageHandler in PR-B beside the Vite integration that exercises client aborts, streamed responses and HMR upgrade-adjacent paths. If the stack must keep it here for D3 reasons, at least mark it experimental in the README until PR-B proves it. Not blocking.

4. executeDevCommand is accumulating responsibilities (~300 lines)

Port/host validation, app resolution, config-vs-discovery runtime, bind guard (bearer refusal + auth assertion + discovery refusal), DevTool asset fallback, two serve() calls, banner, shutdown. The two serve() calls repeat { host, basePath, devtoolConfig, handleSignals:false } and each has its own bind-failure cleanup. Worth a light refactor now, since PR-B adds --watch to the same function: pull the bind-guard block into assertDevBindAllowed(resolved, host, options) and the two-server start/close into one startDevServers(...) returning { url, devtoolUrl, close }. That also makes the DevServer handle the natural seam instead of an inline closure. Do this before PR-B, not as drive-by churn in this PR if it grows the diff.

5. Smaller points (note for the implementer)

  • Wildcard bind meta: with --host 0.0.0.0 the fsdev-devtool-url is http://0.0.0.0:PORT/, which a browser on another machine can't reach (and some browsers block 0.0.0.0). Acknowledged for PR-C; if the meta is only meaningful on loopback anyway, consider omitting it on a non-loopback bind rather than writing a wrong address.
  • --app ambiguity: a bare name that is both a directory under cwd and an installed package resolves silently to the directory (existsSync(asPath) wins). Probably right, but print which one was chosen, or document the precedence in cli.md.
  • DevTool on a network bind: the second serve() binds the same host on a random port, so the full DevTool + API surface is network-exposed once per run. The guard covers auth, but a one-line note in the docs that --host exposes two ports would save a surprise.
  • runPageHandler: resolves true on close as well as finish, so a client abort before the handler responds returns RESPONSE_ALREADY_SENT correctly, but a handler that later calls next() after the abort is a no-op (listeners removed only in next). Fine today; worth a test with a handler that aborts mid-response when PR-B lands.

Architecture notes

  • The layer line (layer-boundary.test.ts) and the single HTML writer (createPageHtmlTransform) are good: one place for the loopback rule on the credential. No conflict with existing BPs found.
  • No changes proposed to docs/changesets beyond the above.

Generated by Claude Code

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.ts as a small resolver (getAssetPath() contract, path-vs-package heuristic) — right size for S3.
  • createPageHtmlTransform reusing existing insertBeforeHeadClose / injectDevtoolConfig — one HTML injection path for static pages and future Vite middleware (PR-B).
  • executeDevCommand returning DevServer + programmatic pageMeta — sets up S8/S9 without another bespoke start.mts.
  • Layer-boundary test intent (no Workforce imports in the hook) — good guardrail for tenet 4.

Simplify follow-ups (non-blocking)

  1. executeDevCommand size (~280 lines orchestration). Consider extracting startDevListeners({ 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.

  2. Duplicate getAssetPath() package loading — dev-app.ts packageAssetPath and resolveDevToolAssets() in dev.ts share the same createRequire → dynamic import → getAssetPath() shape (DevTool keeps monorepo fallbacks). A shared resolvePackageAssetDir(name, cwd, { fallbacks? }) in packages/cli/src/ would shrink the diff and keep PR-C's Shift Manager wrap simpler.

  3. HTML head passes — when both pageMeta and loopback devtoolConfig apply, createPageHtmlTransform runs insertBeforeHeadClose twice (meta, then injectDevtoolConfig). Merging into one tag string before a single insert is a small hot-path win on large index.html shells; optional unless profiling says otherwise.

  4. Layer-boundary word scan — FORBIDDEN_WORD matches common English (teams, shifts, …) on every line, including comments. That already pressures awkward wording in serve.ts. Tightening to import lines only (keep the planted-word case in the self-test) would preserve the signal with less brittleness.

  5. Tiny DRY — port parsing (/^\d+$/ + range) is duplicated with serve.ts; urlHost duplicates Shift Manager's start.mts. Fine to defer until S8 deletes start.mts, but a one-liner in node or fsdev would 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).

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread packages/cli/src/commands/dev.ts Resolved
Comment thread packages/cli/src/commands/dev.ts Resolved
Comment thread packages/cli/src/dev-app.ts Resolved
Comment thread packages/node/src/page-html.ts Resolved

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Open in Web View Automation 

Sent by Cursor Automation: Code Snob

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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".

Comment thread packages/cli/src/commands/dev.ts Resolved
Comment thread packages/cli/src/commands/dev.ts Resolved
Comment thread packages/cli/src/commands/dev.ts Resolved
…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
@jhoffner
jhoffner merged commit 4edb77c into main Oct 4, 2026
13 checks passed
@jhoffner
jhoffner deleted the claude/project-thread-ibr67c branch October 4, 2026 21:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants