Skip to content

spec(FIX-1770): Run Shift Manager against your own Lab with one command, with a dev mode - #2734

Merged
jhoffner merged 3 commits into
mainfrom
spec/FIX-1770
Oct 4, 2026
Merged

jhoffner merged 3 commits into
mainfrom
spec/FIX-1770

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 4, 2026

Copy link
Copy Markdown
Collaborator
Someone who… Today After
has a Lab outside this repository Cannot run it. It is private and starts only from a checkout Runs npx shift-manager --config ./fsdev.config.mts. Nothing to build
edits the flows of the Lab while Shift Manager is open Restarts by hand after each change Adds --dev. A save restarts the Lab
works on the pages of Shift Manager in this repository Uses two terminals. The Vite page has no DevTool link, user or token Uses one command with --dev
builds a different app to show beside a Lab Copies start.mts Runs fsdev dev --app <package>. fsdev knows nothing about the app
binds Shift Manager to a network address Refused without Lab authentication, or with a page bearer The same refusals, in fsdev

Goal: a person outside this repository installs Shift Manager and opens their own Lab in the browser with one command and no build. With --dev, a saved change to the Lab shows without a manual restart.

flowchart LR
  P["packed release tarballs"] --> I["npm install into an empty project · a held-out Lab beside it"]
  I --> R["shift-manager --config · one command"]
  R --> B["Chromium reads the page"]
  B -->|"TEAMS equals the Lab's workers · trace opens the DevTool"| A["PASS a"]
  R --> E["--dev · save a change to a Lab file"]
  E -->|"the page shows it · no manual restart"| W["PASS b"]
  C["control · no page config or no watch"] -.-> R
Loading

Check: goals/shift-manager/it-runs-from-an-install/, model n/a. Controls: GOAL_CONTROL=no-page-config must fail leg a, and GOAL_CONTROL=no-watch must fail leg b. Why this goal and not a smaller one: SPEC.md.

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

On the left, one lab script does all the work. On the right, fsdev does the generic work, below the framework line.

How: fsdev dev --app serves the pages of an app, the Lab API on the same origin, and the DevTool on a second port. --watch restarts the Lab on a change. Shift Manager publishes a small command over this hook.

Sign off

The goal, at that size. If wrong: we publish a package that works only in a checkout.

fsdev owns the hook, and node gets only two generic page options · D1

D1: fsdev owns the hook, chosen, beside node owning it. Decided by what a production install carries

It comes down to the production install: if node owns the hook, Vite and a file watcher go to all servers. If wrong: dev tools in a production host, or a hook that each app writes again.

The package ships built pages only, and --dev restarts the Lab of the user · D2

D2: built pages and a Lab restart, chosen, beside shipping source and Vite. Decided by who edits what

It comes down to who edits what: outside users edit their Lab, not Shift Manager. If wrong: outside users cannot change the screens without a clone of the repository.

Three PRs in sequence: the hook, then watch, then the published package · D3

D3: three PRs in sequence, chosen, beside one PR. Decided by what one review must hold

It comes down to review size: one PR mixes a host change, a supervisor and a package move. If wrong: nothing installs until the third PR merges.

Open: none. D1 is the one to weigh. News, hard to reverse: this is the first npm publish of @flow-state-dev/shift-manager. An npm name is permanent. Reasoning: DECISIONS.md. Cases: BUSINESS-RULES.md.

Reviewers · look here

  • Decisions → D1. Is the split correct? Does the Vite index keep one HTML injection path in node?
  • Decisions → Decided, not asked. A Lab change restarts the full process (see poc/esm-reload/). Is a page reload on each save acceptable?
  • Rules → BR-12 to BR-15. Do the network-bind refusals miss a case?

Not here: hosting Shift Manager as a deployed team service. The fsdev gen dependency on Workforce is a follow-up.

Spec · Decisions · Rules · Plan · Docs · Evolution · Linear FIX-1770 · project Workforce: Shift Manager, no epic · builds on FIX-1662 and FIX-1649 · merges after human approval and required checks

How to review this — altitude, what's in scope, what's deliberately unsettled

This is a direction set, not an implementation. Reviewing it well means
answering one question: is this the right approach?

In scope to challenge:

  • The goal and the problem framing in SPEC.md — is the goal the real need at full size,
    for the people named, or a smaller goal that would let us call this done early? Would the
    named check fail if the goal were not met?
  • The approach — will it work, does it fit the architecture and docs/philosophy.md?
  • Any numbered decision in DECISIONS.md — that's the sign-off surface.
  • A case BUSINESS-RULES.md misses, or a rule that would invalidate the design.
  • Scope — a deliverable that shouldn't ship, or one that's missing.
  • The reader-facing promises in DOCS.md and their fit with the rules; a missing or
    misleading lineage claim in conditional EVOLUTION.md.

Out of scope — deliberately unsettled here, and owned by the implementing agent:

  • Names, signatures, file paths, and module layout beyond the few PLAN.md pins on purpose.
  • Local structure: which helper, how a function is decomposed, error-message wording.
  • Micro-optimizations and style preferences.
  • Test names and internal test structure (the behaviours are the rules; the tests are not).
  • Anything PLAN.md left open on purpose — it is directional by design, and a gap at that
    altitude is intended, not an omission.
  • The figures, at the pixel level. A figure is right when it reads right. A misplaced label
    or a colour you'd have chosen differently is not a finding; a figure that shows a shape the
    decisions don't say is.
  • The solution sketch, at the line level. PLAN.md may include a rough pseudocode sketch
    showing the shape of the proposed solution. It is knowingly incomplete, is not real code,
    and is not what will ship. Review it for directional viability only. Do not report
    that it lacks error handling, omits edge cases, names things that don't exist in the repo, or
    wouldn't build: all of that is true on purpose.
  • POC implementation polish. Experiments under the owning spec's poc/ are retained,
    not production code. Read them for directional evidence, not production completeness.
    Their isolation from production/default discovery and absence of secrets or generated
    dependencies are in scope; retention is not permission to weaken repository checks.

One request, if you are an automated reviewer: the two lists above are the whole difference
between a useful review of this document and a long one. Volume is not signal here — a single
finding above the line is worth more than twenty below it.

Feedback in the second list is welcome and gets recorded verbatim in PLAN.md → Notes from review for the implementer to weigh against real code. It will not be argued with, and it
will not be folded into the design prose. Please don't re-raise it: one mention is enough.

The one exception is the sketch and the POC. Line-level feedback on either is dropped, not
recorded — there is nothing for an implementer to weigh about code that isn't shipping. Feedback
about their direction is not line-level and is treated like any other above-the-bar finding.

Direction approval does not waive merge-time required checks, approvals or thread policy.
Optional comments do not require another design round merely to reach zero comments.

POC — one runnable check, throwaway

node specs/issues/FIX-1770/poc/esm-reload/probe.mjs answers: can --dev reload a Lab inside the process? No. A cache-busted import of the config keeps the old flow module, and node --watch restarts on an imported module only. It is throwaway evidence, not production code.

🤖 Generated with Claude Code

https://claude.ai/code/session_018KBgKPRLfqjmV2LS88Eg9S


Generated by Claude Code

…nd, with a dev mode

Retained spec set: fsdev gains a generic app hook (--app, --host, --watch),
@flow-state-dev/node gains two generic page options, and Shift Manager is
published as a thin CLI over the hook. Includes the esm-reload POC.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018KBgKPRLfqjmV2LS88Eg9S
@jhoffner jhoffner added the spec label Oct 4, 2026 — with Claude
@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 8:51pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 4, 2026 8:51pm UTC
flow-state-dev-ui Ignored Ignored Preview Oct 4, 2026 8:51pm UTC

Request Review

@linear-code

linear-code Bot commented Oct 4, 2026

Copy link
Copy Markdown

FIX-1770

@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-04T20:50:47.139712Z 3ff093a 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.

jhoffner commented Oct 4, 2026

Copy link
Copy Markdown
Collaborator Author

Second-look and architecture review (direction only)

The shape holds up. The generic hook sits in fsdev and policy plugs in as page meta, which keeps node free of dev tooling. The main risks are in S5/S6 and in how PR-C is sized. The first two items could change the plan; the rest are notes.

Above the bar

1. S5: the supervisor may be mostly node --watch, and the spec should say why not.

  • The POC shows node --watch already restarts on an imported module and ignores unrelated files, and it keeps watching after a crash.
  • What's left for a custom supervisor is BR-17 (tree files under the config dir), BR-18 (ignore node_modules and data files) and BR-15 (loopback only).
  • Please state in PLAN S5 whether --watch-path=<configDir> plus an ignore filter was tried. If the filter can't be expressed, record that as the reason for the supervisor. Otherwise S5 can shrink to a thin spawn wrapper.
  • The "Vite temp config bundle loops restarts" note in "At implement time" points the same way: an own watch list is likely needed either way, so decide it now rather than at implementation.

2. S2/S6: the plan doesn't cover Vite's HMR websocket.

  • serve() is Hono over a Node http server. S2 adds a Connect-style handler, but Vite middleware mode in a checkout also needs an upgrade path or a separate hmr.port.
  • Without that, "pages from source through Vite in the same process" (BR-21) loads but doesn't hot-update.
  • Pin the choice in PLAN. A separate hmr.port is the cheaper one and adds nothing to node's surface.
  • Also say how the Connect-style handler is adapted inside Hono. The new node option is small only if that adapter is small.

3. D3: PR-C holds too much (S7–S13).

  • It bundles a package move with about 20 goals/ path edits, publish wiring, the removals, a CI packed-install job, docs and the goal check. That is the "one review holds too much" problem D3 is meant to avoid.
  • Split out a mechanical PR-C1: move to packages/shift-manager and re-point callers (S7 move only, S10). Then PR-C2: bin, files, publish guards, removals, packed-install CI and the goal check.
  • C1 is a rename, so its review is cheap and it can merge early.
  • Then the first npm publish, which is irreversible, is reviewed alone.

Notes

  • D2: one flag, two behaviours by install. --dev takes the Vite path when getSourceRoot() resolves and the built pages otherwise. If a future files change leaks src/ into the tarball, outside users silently get Vite. V7 should assert that getSourceRoot is absent or unresolvable from the packed install, not only that src/ is missing.
  • Move to packages/. The rejected "second root for the guards" is validate-publish-set.mjs, which is currently an allowlist of packages that stay private. It may not need a second root at all. Check that before paying for the rename. If the move does stand, the reason is release:build, as the plan already says.
  • Refactor opportunity. labs/shift-manager/bin/start.mts (349 lines) is the code that S3/S4/S8 replace: host guard, config load, DevTool asset lookup and the temp-copy HTML injection. packages/fsdev/src/commands/dev.ts already does the DevTool asset lookup and serve.ts already calls assertNetworkBindIsAuthenticated. Extract that shared setup into one helper that dev.ts and serve.ts both use, instead of a third copy in the --app branch. That is the refactor worth taking while this lands.
  • Verification (V4/BR-23). A source check for "no Workforce word in the hook modules" is a grep-style test and easy to evade by renaming. It's fine as a tripwire. The import-boundary part is better in validate-package-boundaries.mjs.

Anything below the bar (names, module layout, option naming) is left to the implementer.


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.

Simplify review (spec FIX-1770)

What we're judging: Whether this spec is the smallest credible path to “install Shift Manager, one command, --dev restarts my Lab on save” without copying start.mts into every app.

Verdict: Approve direction. D1 (fsdev owns the hook, node stays generic), D2 (built pages for npm; Lab restart is what outside users need), and D3 (three PRs) hang together. The esm-reload POC correctly closes in-process reload and justifies process restart. I don't see a blocking spec incoherence.

The work is large relative to the issue title (13 surfaces, 26 BRs) but proportionate if the real deliverable is a reusable “app beside a Lab” hook, not only Shift Manager on npm. If you only cared about npm + restart, you could ship publish + node --watch first and defer --app / --host / Vite-from-source — that would be faster but would violate the layer rule and repeat start.mts for the next app.

Where complexity might be trimmed (non-blocking)

  1. --watch implementation shape — PLAN says “supervisor restarts the serving child” while the POC settles on node --watch on the import graph. Worth one explicit sentence in PLAN (or Decided): prefer wrapping the dev entry with node --watch and a single watch authority; avoid a second chokidar/fs.watch layer unless Vite temp-config loops force it (you already flag that at implement time).

  2. Dual meaning of --dev — For installs, --dev = Lab restart + built pages; in a checkout, it also turns on Vite for Shift Manager pages (S6, BR-20–22). That’s coherent with D2 but is the densest part of PR-B and the docs table. Optional fork (product, not required): document npm --dev as Lab-only and keep page HMR on pnpm dev only, deferring or narrowing S6. I’m not sure that’s better for in-repo ergonomics; flagging it in case PR-B cost matters.

  3. node surface (S1 + S2) — Two new serve() options (meta map + Connect handler) may both be necessary for Vite index + static assets. If implementers can serve checkout pages with handler-only and call a shared inject helper internally, you might ship one public option — only if it doesn’t fight the “one injection path” guardrail.

  4. Docs duplication — DOCS asks for site overview.md and packages/shift-manager/README.md “Run it” verbatim. Fine for launch; consider “site canonical, README links” later to avoid three-way drift with cli.md.

  5. Implement-time perf (spec gap, not direction) — When implementing S5/S6: debounce/coalesce restarts under save bursts, one Vite server per child, cap success-path restart logging. None of this needs to block spec merge.

Alternatives considered (simpler cuts)

Cut Tradeoff
Publish + node --watch before fsdev dev --app Faster npm; generic hook and “no Workforce in fsdev” slip a release
No shift-manager bin — fsdev dev --app @flow-state-dev/shift-manager Fewer surfaces; weaker branded one-liner for outsiders
Split Lab restart vs page HMR across flags/scripts Clearer npm story; may reintroduce two-terminal dev for SM authors unless pnpm dev bundles both

Reuse: Implementation should mostly extend executeDevCommand / resolveDevToolAssets patterns and lift double-serve() from start.mts, not reimplement. Packed-install fixture beside serve-devtool.mjs is the right CI template.

What's asked of you: No must-fix before merge from this review. If you amend the spec before approval, the highest-leverage clarifications are (1) watch = node --watch by default and (2) whether dual --dev semantics stay as written or you narrow S6 in PR-B scope.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread specs/issues/FIX-1770/PLAN.md Resolved
Comment thread specs/issues/FIX-1770/PLAN.md Resolved
Comment thread specs/issues/FIX-1770/PLAN.md Resolved
Comment thread specs/issues/FIX-1770/DOCS.md Resolved
Comment thread specs/issues/FIX-1770/DECISIONS.md Resolved
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018KBgKPRLfqjmV2LS88Eg9S

@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: 3ff093af9f

ℹ️ 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 specs/issues/FIX-1770/PLAN.md Resolved
Comment thread specs/issues/FIX-1770/PLAN.md Resolved
Comment thread specs/issues/FIX-1770/PLAN.md Resolved
Comment thread specs/issues/FIX-1770/PLAN.md Resolved
… override, patch changesets)

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018KBgKPRLfqjmV2LS88Eg9S
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants