Repository navigation
feat(fsdev): fsdev dev --watch, and an app's pages from source through Vite (FIX-1770 PR-B) - #2740
Conversation
…h Vite (FIX-1770 PR-B) fsdev dev --watch re-runs its own entry as a child under node --watch, the one watch authority. The parent fixes the ports once (--port 0 included), opens the browser when the first child is up, and keeps running when a child fails. A child reports its config folder's files to node --watch before the config loads, and a preload drops every node_modules path, so a Lab change restarts it and a page, data or dependency file does not. Each child stamps its pages with a boot id meta and serves a stream the page script reconnects to, so an open page, built ones included, reloads when the next child is up. Loopback only. Under --watch, an --app package that also exports getSourceRoot() is served from that folder through the Vite its own install resolves, in middleware mode on the same port, its index through the same page transform as built pages; otherwise the built pages are served, and the command says why. @flow-state-dev/node serve() and createPageHtmlTransform gain pageScript, an inline script written after the page meta. executeDevCommand now reads as parse options, resolve the runtime, start the listeners. 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: 20e5ce15-f6f9-48ea-be2c-9b706b3c3442) |
Second look + architecture pass (read-only, from the diff at 83c48a7; I did not run the suites)Overall the approach holds up. The 1.
|
There was a problem hiding this comment.
Simplify review (FIX-1770 PR-B)
Verdict: approve. The feature set (stable port across restarts, Lab-only triggers, built-page reload, optional app source on the same origin as /api/flows) forces more moving parts than a plain fsdev dev, but the split here is mostly the minimum honest design—not accidental sprawl.
Did the approach go too far?
I looked for a materially smaller design that still hits the spec (BR-19–22 in FIX-1770):
| Alternative | Why it doesn’t really simplify |
|---|---|
Chokidar/nodemon instead of node --watch |
Adds a dependency and reimplements restart orchestration; you’d still need the parent for fixed ports, the preload filter, reportLabFiles, and the reload channel for built HTML. |
Spawn vite CLI on another port + proxy |
Two origins (or a proxy layer), harder DevTool meta / API same-origin story, more process supervision. Vite middleware mode on the existing serve() server is the usual integrated pattern—and you already use it in a thin ~100-line module. |
| Defer Vite to “run vite yourself” | Smaller PR, but pushes integration cost to every app author and fights the --app + one URL goal from PR-A. |
| LiveReload/BrowserSync for reload | Another dependency; still wouldn’t cover “new child, same port, built static tree” without custom boot-id semantics you already encoded once. |
What would have been simpler product scope: ship --watch without source/Vite first, then add getSourceRoot() in a follow-up. That’s a sequencing tradeoff, not evidence this implementation is over-engineered for the combined scope.
What looks clean
- Module boundaries:
dev-watch-preloadmust stay isolated for--import;dev-watch/dev-vite/dev-appresponsibilities are clear;serve()/page-htmlextensions from PR-A are reused instead of duplicating HTML injection in the CLI. - Platform primitive:
node --watch+ IPCwatch:require/ filteredwatch:importis the right “established” choice versus a home-grown watcher for server restart. - Tests: Real child-process coverage (including Vite and reload
EventSource) matches the risk; ~45s in that file is acceptable for what it pins.
Optional follow-ups (non-blocking)
See inline notes on resolveViteEntry (Node resolution vs hand-parsed exports) and reportLabFiles (sync tree walk at child boot—fine today; revisit if config trees get huge).
Checks: pnpm --filter @flow-state-dev/fsdev test — 334 passed (including dev-watch.test.ts).
No changeset concern from this review; fragments already present.
Sent by Cursor Automation: Review For Best Approach
There was a problem hiding this comment.
Code Snob — already tight (83c48a714). No POC.
I read packages/cli/src/dev-watch.ts, dev-watch-preload.ts, dev-vite.ts, dev-app.ts, commands/dev.ts, packages/node/src/page-html.ts, serve.ts, and the new cases in packages/cli/test/dev-watch.test.ts, dev-app.test.ts, and packages/node/test/serve.test.ts.
A rewrite would not shrink this contract.
- The preload imports nothing, so it cannot share the config-folder walk. The walk skips
node_modulesso it does not send that tree; the preload drops paths Node already reported. Different reports. chainPageHandlersis the one composition: the DevTool server gets the reload handler alone, the app chains Vite after it. Inlining deletes the function and leaves both call sites.createVitePageswaits because the handler is registered beforeattach. A waiter list is the same length, and the failure path gets worse.resolveViteEntrywalks the app'snode_modulesand picks theimportexport.require.resolveis shorter and selects therequirecondition. That is the recorded NODE_PATH fix.callExportis already the sharedgetAssetPath/getSourceRootcall.startListenersis the split PR-A asked for. The twoserve()calls still differ onstaticDir, page meta (the DevTool URL),disposeOnClose, and the Vite chain.- The parent's IPv6 bracket and
urlHostare one expression. Sharing them adds an import. - The two stream tests pin different failures (the handler holds the body, the client drops it).
pageScript'sstaticDirmatches the per-describe fixture already in that file.
The module headers restate the files. Deleting them does not shrink the contract. I did not reopen pageScript, the node --watch IPC, re-running process.argv[1], the fixed DevTool port, reporting files before the config loads, the script's own reconnect, or the 1s drain. Those are already recorded.
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: 83c48a7143
ℹ️ 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".
…cal and new files (FIX-1770 PR-B) - A missing --config or --dotenv file now fails in the parent with the config error. Before, the child failed before it reported a file, and node --watch waited with nothing to restart it on. - A watch child reports the .env.local files fsdev loaded, so a save to one restarts it. - A file created under the config's folder after a child started asks the parent to start the watcher over on the same ports, since node --watch only knows the files it was told about. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018KBgKPRLfqjmV2LS88Eg9S
…es (FIX-1770 PR-B) node --watch can drop a SIGTERM that lands while it is restarting its child. Before this fix, a file created during a save left the supervisor waiting on a watcher that never exited, and every later new file was ignored. The supervisor now sends SIGTERM again until the watcher exits. A directory is also watched before it is read, so a file created between the two is still seen. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018KBgKPRLfqjmV2LS88Eg9S
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: 62fb52f5-75f5-425a-aa14-e1d4fcfa4425) |


When you edit a Lab's flows while
fsdev devis open, you must stop and start the process after each change. A page served from an app's source also needs a second terminal and a proxy.What this does
fsdev dev --watchrestarts the server on the same port when you save a file that the config loaded, a file in the config's folder, or an.env.localfile that fsdev loaded. It also restarts when a file is added to the config's folder. An open page then reloads. It does not restart for a page, data ornode_modulesfile. When a restart fails, the command waits for the next save. It binds loopback only. With--app, a package that exportsgetSourceRoot()is served from source through its own Vite, on the same port.<img src="https://raw.githubusercontent.com/fixpoint-labs/flow-state-dev/3ff093af9f79fdecd29808f281da74d21bd09824/specs/issues/FIX-1770/figures/what-changes.svg"· width="940" alt="Before: two terminals and a lab script, checkout only. After: one installed command over fsdev's app hook and node's serve()" />This PR adds the
--watchhalf of the picture. PR-C adds the Shift Manager half.What's asked of you
@flow-state-dev/nodegets a third page option,pageScriptnodegets only two generic page options. Without a third, a built page cannot reload by itself after a restart. The reload was added to the spec in round 1.pageScriptwrites an inline script into each HTML page, on any host. It contains nothing about dev tools.nodehas one more additive public option. Before 1.0, aminorrelease can remove it.The other decisions follow the approved spec.
Parts worth reviewing closely
For the code reviewer:
packages/cli/src/dev-watch.tsanddev-watch-preload.ts. A child sends its config folder's files tonode --watchas{"watch:require": [...]}. A preload removesnode_modulespaths from the reports that Node sends. Node does not document this IPC message. Is it acceptable to depend on it? If Node changes it, V5 fails. Nothing fails silently.startListenersincommands/dev.ts. The listen and teardown block moved here, as the PR-A review asked. Check that teardown order anddisposeOnCloseare the same as in PR-A.Part of FIX-1770, PR 2 of 3 (the order is in D3) · spec:
specs/issues/FIX-1770/onmain, reviewed in #2734 · PR-A: #2735 (merged) · goal check: runs in PR-C · this PR merges intomain.How to review this: altitude, what's in scope, what's deliberately unsettled
Engineering calls: decided along the way, no product sign-off needed
process.argv[1]with the same arguments. A wrapper command (PR-C'sshift-manager) therefore restarts as itself and keeps its own options, for example the page meta. If this is wrong, PR-C must give the child its own entry.WORKER.mdthat the config reads at import, and that breaks the load, then restarts the Lab when you fix it. If this is wrong, a broken tree file stops--watchuntil you save a module.EventSourcestopped after one refused connection. If this is wrong, a page can stay open on a dead server.node_moduleschain, not throughrequire.resolve. A pnpm bin shim puts its store onNODE_PATH, and in a test that found a Vite near fsdev. If this is wrong, an app with no Vite gets one that it did not install.shutdownGraceMs), and it ends its reload streams first. An open flow stream thus does not delay a restart by 10 s. If this is wrong, an in-flight request stops sooner during a restart.node --watchonly knows files that it was told about. The child therefore watches the folders it walked, and when an eligible file appears, it asks the parent to startnode --watchover on the same ports. If this is wrong, a new worker'sWORKER.mdneeds a save to some other file first.--configor--dotenvfile fails in the parent. A child that fails before it reports anything leavesnode --watchwith nothing to restart on.node_modules/.vite-temp, so thenode_modulesrule already covers it. A real Vite child in V5 proves this: it has no restart loop.Everything else: verification with red states, docs, files
Checks. Typecheck passes for
@flow-state-dev/fsdevand@flow-state-dev/node(turbo, with dependencies).validate-package-boundariespasses. The fullfsdevandnodevitest suites pass on the rebased head.V5, BR-15–BR-19, on a real child (
packages/cli/test/dev-watch.test.ts). The test runsnode --import tsx src/bin.ts dev --watch --port 0in a temporary Lab and saves real files. A new boot id meta counts as a restart.error: unknown option '--watch'. With the child picking its own port (mutation M7):no restart within 30000msWORKER.md)no restart within 30000msnode_modulesmodule that the Lab imported: no restartexpected [ …(3) ] to deeply equal [ Array(1) ].env.localfile that fsdev loadedno restart within 30000mstree/b/WORKER.mdafter start: restart, then its next save restarts againno restart within 30000ms--watchwith a missing--configor--dotenv: exit 3 with the config errorexpected 'still running' to be 3node --watch)no restart within 30000msEventSource, separate process)expected 'timeout' to be +0In Chromium (headless shell 147, run locally, not in CI): the page reloaded by itself after a module save, on one origin.
{"boot1":"f1df70d8…","boot2":"f4a0e26f…","navigations":["http://localhost:45857/","http://localhost:45857/"],"body":"built page"}. With a fakexdg-open, the browser opened once across three children.V6, BR-21 and BR-22 (
packages/cli/test/dev-app.test.ts, run as a watch child):/@vite/client,fsdev-devtool-url, the bearer config and the boot meta. A client route gets the same index. A module comes through Vite. The HMR socket opens on the same portexpected '…ops…' to contain 'from source'expected '…' to contain 'Vite doesn't resolve from'. This test also failed against the firstrequire.resolveversion, which found vitest's Vite onNODE_PATHgetSourceRoot()returns nothing, or there is no--watch: built pages--watchwith a non-loopback host: refused, exit 3 (BR-15)expected undefined to be an instance of CliErrorV4 (layer line).
dev-vite.ts,dev-watch.tsanddev-watch-preload.tsare added to the scan. 9 of 9 pass.node.
pageScripttests (red before:expected '…<head></head>…' to contain '<script>1;</script></head>'). Two characterization tests show thatrunPageHandlerholds a streaming response open and survives a client that drops the stream. Both passed on PR-A's code. They pin the behaviour that the reload stream and Vite depend on.Docs.
apps/docs/docs/api/cli.mdgets the--watchrow, a "Restarting as you edit" subsection, and thegetSourceRoot()paragraph from DOCS.md.packages/cli/README.mdgets the flag and an example.packages/node/README.mdgets thepageScriptrow. Changesets:patchfor@flow-state-dev/fsdevand@flow-state-dev/node.Files. New:
packages/cli/src/dev-watch.ts(supervisor, files sent from the config folder, reload signal),dev-watch-preload.ts(removesnode_modulesreports),dev-vite.ts(Vite middleware pages). Changed:commands/dev.ts(now reads as parse options → resolve runtime → start listeners),dev-app.ts(resolveApp,getSourceRoot(), Vite lookup),load-config.ts(exportslocateConfig),node/src/page-html.tsandserve.ts(pageScript).🤖 Generated with Claude Code
https://claude.ai/code/session_018KBgKPRLfqjmV2LS88Eg9S
Note
Medium Risk
Substantial dev-server orchestration relies on undocumented
node --watchIPC and child process supervision; impact is limited to loopback local dev, but regressions could break the primary edit-reload workflow.Overview
Adds
fsdev dev --watch(loopback only): a parent supervises the same CLI entry undernode --watch, keeps ports fixed across restarts, restarts when config-loaded modules, files under the config directory, or loaded.envfiles change, and auto-reloads open pages via boot-id meta, an SSE endpoint, and injectedpageScript. Failed starts wait for the next save; invalid--config/--dotenvfail in the parent before spawning.With
--app, packages exportinggetSourceRoot()can be served from source through the app’s own Vite (middleware on the same origin as/api/flows); otherwise built assets are used. New CLI modules implement watching (dev-watch, preload filter fornode_modulesreports), Vite integration (dev-vite), andresolveAppindev-app.executeDevCommandsplits into runtime resolution andstartListenersteardown.@flow-state-dev/nodegainspageScriptonserve()/createPageHtmlTransform(inline script after meta tags, with</escaping). Docs, changesets, and integration tests cover watch behavior and Vite fallback paths.Reviewed by Cursor Bugbot for commit 0a9b4ef. Configure here.