Repository navigation
Publish Shift Manager as @flow-state-dev/shift-manager with a shift-manager command and --dev (FIX-1770 PR-C) - #2759
Conversation
|
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: 395873c1-a3a0-4bd2-be75-b53d5ab90e1f) |
jhoffner
left a comment
There was a problem hiding this comment.
Second-look + architecture pass on #2759. I read cli/bin.ts, scripts/checkout.mts, the dev.ts diff and package.json. I did not re-run the goals, and the 199-file move is mostly renames, so I did not review it line by line. Findings are in order of weight. The spec's decisions are not re-argued.
1. The 3 s shutdown ceiling is a hard process.exit, and the engine already has a drain budget for this (packages/cli/src/commands/dev.ts, withSignals).
createFlowStatetakesdispatchDrainTimeoutMs, a true ceiling on the drain, with a 30 s default (packages/engine/src/flowstate/types.ts:207,createFlowState.ts:120). The 30 s the PR body complains about is that default.- A watch child could pass a small value, around 2 s, when it builds its runtime.
dispose()would then stop waiting on its own, and the normal teardown would still run:closeStores, the Vite and DevTool closes, andhandle.close(). - The timer race skips all of that. At 3 s,
process.exitleaves the SQLite store un-closed, so WAL checkpointing is skipped. Any in-flight runs are left in whatever state a kill leaves them in. - The PR's answer to "is cutting off a run acceptable" is "yes, a kill does the same". The drain budget cuts off the same runs, but the stores are closed cleanly.
- Please check whether
resolveDevRuntimecan passdispatchDrainTimeoutMs(only whenreload !== undefined). If so, dropWATCH_SHUTDOWN_CEILING_MSand theceilingMsparameter onwithSignals. That puts the change in one place, the runtime's drain option, rather than a second shutdown path. - If it can't be passed for some reason, keep the ceiling, but run
closeStoresbefore it fires or say why the skipped close is safe. The PR body does not say which of these cases applies. - A restart that cuts off a run also needs a test of what state that run reads as in the store after the restart.
dev-watch.test.tsproves the restart is fast. It does not prove the cut-off run is recoverable. Per BP-035, that is the cancel path.
2. The --dev non-loopback refusal is not in bin.ts, and the PR body asks reviewers to check it there.
- The refusal lives in
executeDevCommand(dev.ts:178), which is the right place.bin.tsonly passeswatch: values.dev === true, so that part of the checklist is fine. - For the non-loopback case, nothing in
command.test.tsis named as covering theshift-manager --dev --host 0.0.0.0path. Does a shift-manager test assert it? A test inside fsdev proves the guard exists. It does not prove this command can't route around it, for example through--assetsorpageMeta. A one-line test would settle it.
3. package.json keeps main and exports pointing at ./cli/index.ts, and relies on publishConfig to override them.
- This works with pnpm and
npm publish. A plainnpm packand some other tools ignorepublishConfig.exports. - The PR already guards the build with
prepublishOnlyand has the packed-install fixture. Does the packed-install fixture assert the packedpackage.jsonhasexports.default === ./dist/index.js? If not, add that one assertion. It is the main place a published package breaks without a failing check.
4. --assets <dir> is a flag the spec's D2 removal list doesn't mention, and it duplicates fsdev's --app <dir>.
- The wrapper resolves it against
invokedFromand passes it asapp. That is a second spelling of an fsdev flag, and it lives on a command described as a thin wrapper. - It is probably needed for working on the pages. If so, say that in the
bin.tsheader. The header only lists the flag. If nothing needs it beyondcheckout.mts, drop it.
5. Two duplicated or undeclared things in bin.ts.
- The default port
4300is a literal inparseArgs. Is it also written in the docs or incheckout.mts? If the number appears in more than one place, name it once. shiftSchemere-reads and re-parsesprofiles/*.jsonon each call. That is fine as it stands, since it runs once. This is an observation, not a request.
6. The restructure is the right call, and the two-path split is worth keeping.
- A package for the published command with
scripts/checkout.mtsas the repo-only wrapper keepsbuild-inputsand the stale-build check out of the tarball. That is a clean seam. - The cost is that
--devre-runscheckout.mtswith pinned arguments, which means two argument parsers (checkout.mts'shas()andbin.ts'sparseArgs) both read the same flags. Parsing--dev=...or--assetsdifferently in the two will drift silently.checkout.mtsonly needs three booleans, so this is cheap to leave alone. Add a comment inbin.tsthatcheckout.mtsalso reads--dev,--assetsand--config, so the next flag added to one is added to the other.
Verification claims I could not check from here.
- V9: the three goals that failed on
maintoo, and the fix togoals/lib/shift-manager.mts. That is a separate fix that rides in this PR. If a separate PR for it is cheap, a failure onmainis easier to read when it is not bundled with a 199-file move. - The three leg controls (
optimistic-post,worker-session,no-org) that returned WRONG from an esbuild crash were not re-run. The PR is honest about it. They should be re-run on this head before merge, since a control that never ran cannot show the check can fail.
Nothing here blocks the direction. Item 1 is the one worth changing before merge.
Generated by Claude Code
There was a problem hiding this comment.
Verdict
The core approach is the right simplification. Deleting labs/shift-manager/bin/start.mts (~350 lines of bespoke serve(), scratch copies, and parallel DevTool wiring) and replacing it with a thin shift-manager bin on executeDevCommand + the fsdev --app hook is aligned with how DevTool already ships. I would not revert toward a second server stack in the app package.
What this PR adds beyond that win is mostly verification surface (install goal, packed-install fixture, publish guards, CLI module-file --app, watch shutdown ceiling). That is proportionate to “publish + prove tarball install,” though a few pieces duplicate logic that already exists elsewhere and will drift unless shared.
What went well (simplify lens)
- Single hosting path:
cli/bin.tsdelegates serving, bind guards, DevTool sidecar, and--devrestarts to fsdev — the complexity belongs in the platform, not Shift Manager. - Artifact split is clear:
dist-client/(pages) vsdist/(CLI) +prepublishOnly/check-pages.mjsmirrors devtool’s release discipline without re-implementing hosting. - Meta contract aligned:
connection.tsreadsfsdev-devtool-url(same as fsdev’spageMeta), which removes the oldshift-manager-devtoolone-off. - Net line count: large delete of
start.mtsand its tests; new code is mostly tests/goals/docs.
Where complexity crept in (optional follow-ups, not blockers)
| Area | Concern | Simpler direction |
|---|---|---|
| Install goal | it-runs-from-an-install/run.mts inlines release:build + per-package pnpm pack + npm install. scripts/packed-install/run.mjs already encodes publishable filtering (publishableDists) and the same loop. |
Reuse shared pack/install helpers; keep only anti-game + Playwright legs in the goal. Reduces drift vs CI packed-install. |
| Banner parsing | Regex on stderr (App: / Data: / DevTool:) appears in goals/lib/shift-manager.mts, test/command.test.ts, and scripts/packed-install/fixtures/shift-manager.mjs. |
Export a small parser from @flow-state-dev/fsdev next to the banner writer, or standardize on HTTP readiness when the port is known (the install goal already does this — good). |
| CLI errors | Local Refusal + duck-typed exitCode in bin.ts parallels fsdev’s internal CliError, which is not exported. |
If we expect more --app wrapper CLIs, exporting CliError (or a narrow config error) from fsdev is cleaner than N copies of Refusal. |
| Meta constant | DEVTOOL_META = "fsdev-devtool-url" in app code while fsdev exports DEVTOOL_URL_META. |
Import the exported constant in the SPA if the bundle graph allows it — avoids silent drift. |
| Checkout script | checkout.mts mutates process.argv then dynamic-imports bin.ts. |
Works, but exporting runShiftManager(argv) or spawning the bin explicitly would be easier to follow. Low priority; repo-only. |
| Docs | labs/README.md still lists labs/shift-manager and --team devteam; package lives under packages/shift-manager with --config / shift-manager CLI per user docs. |
One table-row update (in this PR or immediately after) so lab index matches reality. |
Uncertain (worth a quick check, not a merge gate): whether @flow-state-dev/devtool must stay a runtime dependency for published tarballs or can move to devDependencies once only the Vite bundle touches it — packed-install is the right place to validate.
Performance
No CLI hot-path regressions spotted. Removing per-start full dist tree copy is a real win. Remaining cost is in goals/CI (sequential pack, poll loops) — acceptable for those contexts.
Alternative approaches considered
- “Just document
fsdev dev --app @flow-state-dev/shift-manager” — viable for power users; the publishedshift-managerbin still earns its keep (default port, shift meta,INIT_CWD/chdir, checkoutstart/devscripts). - Keep custom
start.mts— would reintroduce the largest complexity; I’d reject that direction. - Third-party CLI framework — unnecessary; Node
parseArgs+ fsdev delegation is already minimal.
Approval: Direction is sound; merge-worthy with the follow-ups above as hygiene rather than architectural rework.
Sent by Cursor Automation: Review For Best Approach
There was a problem hiding this comment.
Code Snob — already tight on 347de9a1c. No POC.
I read packages/shift-manager/cli/bin.ts, cli/index.ts, scripts/checkout.mts, scripts/check-pages.mjs, packages/cli/src/dev-app.ts, the withSignals change in packages/cli/src/commands/dev.ts, test/command.test.ts, goals/lib/shift-manager.mts (servedAddresses), and goals/shift-manager/it-runs-from-an-install/run.mts.
bin.ts is what is left of the 349-line start script: the default port, the shift profile, and the missing-config message. The rest is executeDevCommand. Refusal is how one catch prints both that message and fsdev's CliError (CliError is not exported). fail() plus a second catch is longer.
checkout.mts is the repo-only stale-build check and the devteam pin. Folding its three-flag has() into bin.ts puts repository paths in the published command.
moduleFile is the file-versus-directory split so --app can be a module path from any directory. Inlining it repeats the stat. A classifier is the same length.
The 3s watch ceiling is one timer on the child. withSignals(supervisor) stays without it. Moving the timer into close() still needs the signal path. The drain-budget alternative changes how a restart shuts down; leaving that alone.
shift-manager-color-scheme is written in bin.ts and read in src/lib/color-scheme.ts. The page must not import the CLI. The App: / Data: banner parse sits in servedAddresses, command.test.ts, and the packed-install fixture. The fixture cannot import goals/, and exporting a parser from the package grows the surface. Each copy is a few lines.
check-pages.mjs and getAssetPath() check different moments. The install goal's pack loop is not packAll (that one also reads each tarball's manifest). The goal file header matches the other goal runs.
A rewrite does not shrink this contract.
Sent by Cursor Automation: Code Snob
…tch ceiling is an exit (FIX-1770 PR-C) Review on #2759: - command.test.ts: shift-manager --dev --host 0.0.0.0 refuses before it listens, with the package's pages and with --assets. - bin.ts header: what --assets is, and that checkout.mts reads --dev, --assets and --config from the same arguments. - dev.ts: why the --watch shutdown ceiling exits instead of shrinking the drain budget, and why the skipped store close is safe. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016AYpa2x1a2xPUDxGueDEZP
|
Answers to the second-look review, in its numbering. Changes are in d6b6203. The commit before it, 0d6625a, regenerated
The three esbuild-crashed leg controls are a goal run of over an hour that CI doesn't run. Whoever runs the closure goal before merge should re-run them on this head. Generated by Claude Code |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 347de9a1c6
ℹ️ 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".
|
I re-ran the closure goal's three leg controls that crashed in esbuild, on this head (78b8e27). The command was Each failure comes from the control's own change, not from setup. Examples: Generated by Claude Code |
…manager CLI and --dev (FIX-1770 PR-C) - packages/shift-manager is published as @flow-state-dev/shift-manager. It ships its built pages and a shift-manager command built on `fsdev dev --app`. `--dev` restarts the Lab on a save and reloads the page. The command replaces labs/shift-manager's start.mts. - fsdev: `--app` also takes a package's module-file path, `locateConfig` is exported, and a --watch restart no longer waits on runs that are still going (it exits after at most 3 s). - The packed-install check covers the new package. The goal goals/shift-manager/it-runs-from-an-install proves it from an npm install, with the controls no-page-config and no-watch. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018KBgKPRLfqjmV2LS88Eg9S
…cy split (FIX-1770 PR-C) CI's frozen install refused the lockfile: it still listed every shift-manager dependency under dependencies, while package.json keeps only devtool and fsdev there and moves the rest to devDependencies. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016AYpa2x1a2xPUDxGueDEZP
…tch ceiling is an exit (FIX-1770 PR-C) Review on #2759: - command.test.ts: shift-manager --dev --host 0.0.0.0 refuses before it listens, with the package's pages and with --assets. - bin.ts header: what --assets is, and that checkout.mts reads --dev, --assets and --config from the same arguments. - dev.ts: why the --watch shutdown ceiling exits instead of shrinking the drain budget, and why the skipped store close is safe. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016AYpa2x1a2xPUDxGueDEZP
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016AYpa2x1a2xPUDxGueDEZP
…p name the published package (FIX-1770 PR-C) Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016AYpa2x1a2xPUDxGueDEZP
78b8e27 to
3c60fa6
Compare
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: 7e4543fb-0f9f-446f-831b-925d40c1774d) |


Requested by Jake · project thread
Today, Shift Manager runs only from a checkout of this repository. You build the pages, then start
labs/shift-manager/bin/start.mts. Someone with their own Lab has no way to run it.What this does
Shift Manager is published as
@flow-state-dev/shift-manager. You install it in the project that holds your Lab and runnpx shift-manager --config ./fsdev.config.mts. The pages ship built, so nothing compiles.--devrestarts the Lab when you save one of its files, and the open page reloads. The command is a thin wrapper overfsdev dev --app, so the Lab's API, the pages and the DevTool are served the wayfsdev devserves them.This PR adds the Shift Manager half of the picture.
What's asked of you
The decisions follow the approved spec. As D2 says,
--team,--devtooland--devtool-assetsare removed. Thedevteamprofile stays in the repository, wherepnpm --filter @flow-state-dev/shift-manager devruns it.Parts worth reviewing closely
packages/shift-manager/cli/bin.ts. This is the whole command. It finds the config, then callsexecuteDevCommandwith--appset to its own module file. Check that--devpasses through only as--watch, and that a non-loopback--hostis refused under--dev.packages/cli/src/commands/dev.ts. The goal check found this. When runs are still going,dispose()waits up to 30 s for them. That held every--devrestart for that long. A watch child now exits after at most 3 s. Is cutting off a run that is still going acceptable for a dev restart? (It is a new process either way.)Part of FIX-1770, PR 3 of 3 (the order is in D3) · spec:
specs/issues/FIX-1770/onmain, reviewed in #2734 · PR-B: #2740 (merged) · PR-A: #2735 (merged).How to review this: altitude, what's in scope, what's deliberately unsettled
Engineering calls: decided along the way, no product sign-off needed
fsdev dev --appalso takes a package's module-file path. Shift Manager names itself by its own file, so the command works from any directory, even one where the package isn't resolvable. If this is wrong, the command only works where@flow-state-dev/shift-managerresolves from the current directory.--watchchild exits after at most 3 s on a restart (WATCH_SHUTDOWN_CEILING_MS). The goal check showed a held run delaying a restart past 20 s. Without--watch, shutdown is unchanged. If this is wrong, a long run held over a restart is cut off, which is what killing the process would do anyway.locateConfigis exported from@flow-state-dev/fsdev, so the command finds a config the same wayfsdev devdoes.labs/shift-managertopackages/shift-manager. It is published, and the packed-install check packs every package underpackages/.teams/,test/andsrc/stay out of the tarball.startanddevin the repository go throughscripts/checkout.mts.startbuilds the pages first when they're older than their source.devruns--dev, and from a checkout it serves the pages from source through Vite.Everything else: verification with red states, docs, files
Checks. Typecheck passes for
@flow-state-dev/fsdevand@flow-state-dev/shift-manager.validate-package-boundariespasses. Thefsdevsuite passes (27 files, 344 tests), withdev-watch.test.tsalso run under a 4-core CPU load. Theshift-managersuite passes (29 files, 345 tests, 1 skipped).goals/shift-manager/it-runs-from-an-install, plainPASS — 28 tarballs npm-installed into an empty project; … TEAMS draws the tree's 4 workers …; Open trace … opened the DevTool on the run's session …; saving …/auditor/WORKER.md … showed on the open Roster after 4.8 s, no reload by the checkGOAL_CONTROL=no-page-configFAIL — a:Open trace opens the Lab's session: the inspector's trace link is absent …; b:the change shows: 20 s after saving …WORKER.md …, the Roster still draws lab.auditor on auditGOAL_CONTROL=no-watchFAIL — b:the change shows: 20 s after saving …WORKER.md …, the Roster still draws lab.auditor on auditdist/bin.js,dist-client/index.htmlandprofiles/, and nosrc/,teams/ortest/pnpm pack: 0 files undersrc/,teams/ortest/prepublishOnlywithdist-client/moved away exits 1:refusing to publish without its build. missing: dist-client/index.htmlbin/start.mtsand noshift-manager-devtoolmetacommand.test.tsshift-manager.mjsfixture runs in CI's Packed release installs and imports--watchrestart while a run holds shutdowndev-watch.test.ts: restarts within secondsno restart within 15000ms--app <module file>from a directory where the package doesn't resolvedev-app.test.tsV9: every other
goals/shift-manager/goal on this commit. Seven passed on the first run. Three failed in their build step withCould not resolve "../../scripts/build-inputs.mjs":it-draws-v2s-look,it-takes-its-look-from-the-design-systemanda-lab-is-worked-through-one-skinned-shell. That failure is onmaintoo. FIX-1760 added the import, and these goals build a copy of the package outside the workspace.it-draws-v2s-lookfails the same way on PR-B's head, which ismainplus fsdev.goals/lib/shift-manager.mtsnow points the copy's Vite config at the workspace's script, the same way it already points its tsconfig. After that, both look goals PASS. The closure goal (a-lab-is-worked-through-one-skinned-shell) re-ran its whole sweep: legs a–d, J3 and J4 PASS, and every goal and control it re-runs under P3.2 and P3.3 gives its expected verdict. Three of its own leg controls (optimistic-post,worker-session,no-org) first came back WRONG, failing at setup with esbuild'sThe service is no longer running, an infrastructure failure during a run of over an hour. Re-run on their own, all three FAIL as expected (optimistic-postat a4 and b:post,worker-sessionat a2,no-orgat b:org); the output is in a comment on this PR.The control's named assertion was corrected.
no-page-configwas written to fail TEAMS. It fails Open trace and the change shows instead, because the page's reads work without the config.goal.mdand the run's header now name what it fails, and a separate spec amendment PR corrects the same line in the spec.Docs.
apps/docs/docs/shift-manager/overview.mdnow covers installing and running,--dev, and working on Shift Manager itself.packages/shift-manager/README.md,apps/docs/docs/api/cli.md(the--appmodule-file note) and the glossary are updated. Changesets:patchfor@flow-state-dev/shift-manager(first publish) and@flow-state-dev/fsdev.🤖 Generated with Claude Code
https://claude.ai/code/session_018KBgKPRLfqjmV2LS88Eg9S
Generated by Claude Code