From 3ff093af9f79fdecd29808f281da74d21bd09824 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 4 Oct 2026 20:44:41 +0000 Subject: [PATCH 1/3] spec(FIX-1770): run Shift Manager against your own Lab with one command, 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) Claude-Session: https://claude.ai/code/session_018KBgKPRLfqjmV2LS88Eg9S --- specs/issues/FIX-1770/BUSINESS-RULES.md | 67 +++++++++ specs/issues/FIX-1770/DECISIONS.md | 109 ++++++++++++++ specs/issues/FIX-1770/DOCS.md | 136 ++++++++++++++++++ specs/issues/FIX-1770/EVOLUTION.md | 15 ++ specs/issues/FIX-1770/PLAN.md | 126 ++++++++++++++++ specs/issues/FIX-1770/SPEC.md | 109 ++++++++++++++ .../issues/FIX-1770/figures/d1-hook-home.svg | 100 +++++++++++++ .../FIX-1770/figures/d2-dev-for-whom.svg | 99 +++++++++++++ .../issues/FIX-1770/figures/d3-three-prs.svg | 100 +++++++++++++ .../issues/FIX-1770/figures/what-changes.svg | 69 +++++++++ .../issues/FIX-1770/poc/esm-reload/README.md | 23 +++ .../issues/FIX-1770/poc/esm-reload/probe.mjs | 49 +++++++ 12 files changed, 1002 insertions(+) create mode 100644 specs/issues/FIX-1770/BUSINESS-RULES.md create mode 100644 specs/issues/FIX-1770/DECISIONS.md create mode 100644 specs/issues/FIX-1770/DOCS.md create mode 100644 specs/issues/FIX-1770/EVOLUTION.md create mode 100644 specs/issues/FIX-1770/PLAN.md create mode 100644 specs/issues/FIX-1770/SPEC.md create mode 100644 specs/issues/FIX-1770/figures/d1-hook-home.svg create mode 100644 specs/issues/FIX-1770/figures/d2-dev-for-whom.svg create mode 100644 specs/issues/FIX-1770/figures/d3-three-prs.svg create mode 100644 specs/issues/FIX-1770/figures/what-changes.svg create mode 100644 specs/issues/FIX-1770/poc/esm-reload/README.md create mode 100644 specs/issues/FIX-1770/poc/esm-reload/probe.mjs diff --git a/specs/issues/FIX-1770/BUSINESS-RULES.md b/specs/issues/FIX-1770/BUSINESS-RULES.md new file mode 100644 index 0000000000..5d41281756 --- /dev/null +++ b/specs/issues/FIX-1770/BUSINESS-RULES.md @@ -0,0 +1,67 @@ +# FIX-1770 · Business rules + +[Spec](SPEC.md) · [Decisions](DECISIONS.md) · **Rules** · [Plan](PLAN.md) · [Docs](DOCS.md) · [Evolution](EVOLUTION.md) + +The cases, as rules. *Proved by* is the check the plan runs. A rule marked *(fsdev)* holds for +`fsdev dev --app` too, since `shift-manager` wraps it. + +## Starting it + +| # | When | Then | Proved by | +|---|---|---|---| +| BR-1 | Someone runs `shift-manager --config ` where the package is installed | One port serves the pages and `/api/flows`; the DevTool gets its own port. Both addresses and the config path print. Nothing is built | Goal check a · packed-install CI | +| BR-2 | No `--config` is given | Found in the current directory as `fsdev dev` finds it; none there is refused, naming `--config` | CI | +| BR-3 | The config doesn't load, or its default export is not a `FlowState` | Stops with the loader's own message, exit code 3 | CI | +| BR-4 | A relative path is given, or the Lab uses one | Resolved from the directory the command ran in, and the process runs there *(fsdev)* | CI | +| BR-5 | `--port 0`, or a port that isn't a whole number up to 65535 | `0` picks a free port and prints it; anything else is refused, exit code 3 *(fsdev)* | CI | +| BR-6 | `--assets ` is given | That build is served as it is. No `index.html` there: refused *(fsdev, as `--app `)* | CI | +| BR-7 | `fsdev dev` runs with no `--app` | Exactly as today: the DevTool at the root of port 4200, loopback, browser opened | Existing suite | + +## What the page is handed + +| # | When | Then | Proved by | +|---|---|---|---| +| BR-8 | The Lab declares a `devtool` block | Every HTML page served carries the user and bearer, on a loopback host only *(fsdev)* | CI · goal check a | +| BR-9 | The DevTool is served beside the app | Every HTML page carries its address as the `fsdev-devtool-url` meta, and *Open trace* opens it *(fsdev)* | CI · goal check a | +| BR-10 | The DevTool's pages are not installed or not built | The app starts, says so, carries no address meta; *Open trace* is off and says why *(fsdev)* | CI | +| BR-11 | `--shift `, or `SHIFT_MANAGER_SHIFT`, names a profile | The page boots on that profile's scheme. An unknown name is refused, listing the known ones | CI | + +## Binding a network address + +| # | When | Then | Proved by | +|---|---|---|---| +| BR-12 | `--host` is not a loopback address and the Lab would run as the framework's unauthenticated default principal | Refused, with the guard's message *(fsdev)* | CI | +| BR-13 | `--host` is not loopback and the Lab declares a bearer for its page | Refused: the token only ever goes to a loopback page *(fsdev)* | CI | +| BR-14 | `--host` is not loopback and the bind is allowed | The anonymous debug surface `fsdev dev` opens on loopback stays closed *(fsdev)* | CI | +| BR-15 | `--dev` with a non-loopback `--host` | Refused *(fsdev, as `--watch`)* | CI | + +## `--dev` + +| # | When | Then | Proved by | +|---|---|---|---| +| BR-16 | A module the Lab imported is saved | The Lab restarts within seconds, the command keeps running, the page reloads *(fsdev)* | Goal check b · CI | +| BR-17 | A file under the config's directory is saved, such as a `WORKER.md` | Same as BR-16 *(fsdev)* | CI | +| BR-18 | The app's page source, the Lab's data file, or anything in `node_modules` is saved | The Lab does not restart *(fsdev)* | CI | +| BR-19 | A restart fails, for example on a syntax error | The error prints, the command keeps watching, and the next save tries again *(fsdev)* | CI | +| BR-20 | `--dev` in an install, where the package has no source | The built pages are served; BR-16 to BR-19 still hold | Goal check b | +| BR-21 | `--dev` in a checkout | Pages come from source through Vite in the same process, with BR-8, BR-9 and BR-11's config; no proxy | CI | +| BR-22 | The app has source, but Vite doesn't resolve from it | Says so and serves the built pages *(fsdev)* | CI | + +## The layer line and the package + +| # | When | Then | Proved by | +|---|---|---|---| +| BR-23 | fsdev and `node` source is read | Neither imports Workforce or Shift Manager for this hook, and neither names a team, worker or shift | CI source check | +| BR-24 | The package is packed for release | It holds the built pages, the shift profiles and the command. No source, team profiles or tests | Packed-install CI | +| BR-25 | A publish runs without the built pages | It fails before packing | CI | +| BR-26 | The command gets SIGINT or SIGTERM | Both servers close and the Lab is disposed. Nothing is left in a temp directory | CI | + +## Failure taxonomy + +Bad input is fatal at start, exit code 3, before anything listens; so is a refused network +bind. A missing DevTool degrades. Under `--dev` a broken Lab is never fatal: it waits for a save. + +## Acceptance criteria this issue owns + +[The goal](SPEC.md#the-goal-and-how-well-know-its-met), from packed tarballs in an empty +project, each leg failing under its control. The plan runs it last. diff --git a/specs/issues/FIX-1770/DECISIONS.md b/specs/issues/FIX-1770/DECISIONS.md new file mode 100644 index 0000000000..16621750ba --- /dev/null +++ b/specs/issues/FIX-1770/DECISIONS.md @@ -0,0 +1,109 @@ +# FIX-1770 · Decisions + +[Spec](SPEC.md) · **Decisions** · [Rules](BUSINESS-RULES.md) · [Plan](PLAN.md) · [Docs](DOCS.md) · [Evolution](EVOLUTION.md) + +Jake chose the shape: publish Shift Manager, a real CLI with `--dev`, a generic hook in fsdev. +These three decisions are what that shape left open. + +## The tree + +```mermaid +flowchart TD + I["FIX-1770"] --> D1["D1 · fsdev owns the hook
node gets two generic options"] + D1 -.->|"rejected"| X1["node owns it
Vite and a file watcher in a production host"] + I --> D2["D2 · the package ships built pages
--dev restarts your Lab"] + D2 -.->|"rejected"| X2["ship source and Vite
every install carries a dev toolchain"] + I --> D3["D3 · three PRs
hook, then watch, then publish"] + D3 -.->|"rejected"| X3["one PR
node, fsdev and a package move reviewed at once"] +``` + +Solid edges are what you're signing. Dashed edges lost, and the label says why. + + +## D1 · fsdev owns "serve this app's pages beside the Lab"; `@flow-state-dev/node` gains only two generic page-serving options + +| | | +|---|---| +| **Instead of** | `@flow-state-dev/node`'s `serve()` learning about apps: resolving an app package, running Vite, watching files, serving the DevTool beside it | +| **Because** | Each package keeps its job. `node` is the production host: it serves files and writes the page's config into HTML today. `fsdev dev` is the dev loop: it loads the config, serves the DevTool, sets dev-only switches. The hook is a dev loop, so it goes in fsdev (tenet 5). `node` gains only what any host could use: extra `` tags, and a request handler before the static directory. Neither names a team or a worker (tenet 4) | +| **Locks in** | Three public fsdev flags, and an app contract of one export, `getAssetPath()`, as `@flow-state-dev/devtool` has. Production hosting of an app stays `serve()` with `staticDir` | + +![D1: fsdev owns the hook, chosen, beside node owning it; decided by what a production install carries](figures/d1-hook-home.svg) + +It comes down to what a production install carries: in `node`, Vite and a watcher ship to every server. + +**What would change my mind:** a need to serve an app with the DevTool beside it in production. + + +## D2 · The published package ships built pages only; `--dev` restarts the user's Lab, and serves Shift Manager's pages from source only in a checkout + +| | | +|---|---| +| **Instead of** | Publishing Shift Manager's source and Vite with it, so `--dev` live-reloads its pages in every install | +| **Because** | Someone with their own Lab edits their Lab, not Shift Manager, so `--dev` owes them a Lab that restarts on save. Live page reload is for Shift Manager's developers, who have a checkout. Shipping source puts Vite, React tooling and Tailwind in every install for a feature nobody there uses | +| **Locks in** | One flag, two meanings set by the install: in a checkout `--dev` also serves pages through Vite. Changing the screens means cloning | + +![D2: built pages and a Lab restart, chosen, beside shipping source and Vite; decided by who edits what](figures/d2-dev-for-whom.svg) + +It comes down to who edits what: outside users edit their Lab, so Vite in every install buys them nothing. + +**What would change my mind:** outside users asking to customise the screens. + + +## D3 · Three PRs in order: fsdev's app hook, then `--watch`, then the published Shift Manager + +| | | +|---|---| +| **Instead of** | One PR carrying the `node` options, three fsdev flags, the package move, the publish wiring and the goal check | +| **Because** | Each PR is usable when it merges and holds one idea: the hook, provable with no Shift Manager change; the restart supervisor, the riskiest part, alone; the package move and publish, which touch goals and CI | +| **Locks in** | Nothing installs, and the goal check can't run, until the third PR. The repository's Shift Manager works throughout | + +```mermaid +flowchart LR + A["PR-A · fsdev dev --app, --host · node page options"] -->|"the hook"| B["PR-B · fsdev dev --watch · Vite from source"] + B -->|"--dev to wrap"| C["PR-C · Shift Manager published · goal check"] +``` + +![D3: three PRs in order, chosen, beside one PR; decided by what one review has to hold](figures/d3-three-prs.svg) + +It comes down to what one review has to hold: one PR mixes a host change, a supervisor and a package move. + +## Decided, not asked + +- **A Lab change restarts the whole process; the page reloads.** Node can't unload an imported + flow ([Settled](#settled)). Keeping the page alive needs the Lab behind a proxy, today's setup. +- **A Lab change** is a module the Lab imported, or a file under the config's directory (trees + are read from disk). Never page source, data files or `node_modules`. +- **A failed restart keeps watching.** `--dev` binds loopback only. +- **A non-loopback `--host` keeps the anonymous debug surface closed**, runs the `fsdev serve` + guard, and refuses a Lab that hands its page a bearer. +- **The page gets the DevTool's address as one generic meta**, `fsdev-devtool-url`. +- **Vite loads from the app's own install**, never from fsdev's dependencies. +- **Shift Manager moves to `packages/shift-manager`**, where the publish guards look. Name unchanged. +- **Flags that leave:** `--team` (profiles import `goals/`, so can't ship), `--devtool`, + `--devtool-assets`. `--assets` stays for goal controls. +- **The stale-build rebuild moves to the checkout's `start` script**; it reads repository paths. +- **The design-system package stays private**, bundled into the pages. + +## Considered and dropped + +| Alternative | Why not | +|---|---| +| Publish `start.mts` unchanged | Every other app copies it, temp-copy injection included | +| Keep the package in `labs/`, teach the guards a second root | Two homes for published packages, for one package | +| The Lab in a child process behind a proxy, page kept alive | The proxy Jake asked to remove, under every SSE stream | +| Reload the Lab in-process | Misses changed flow files ([Settled](#settled)) | + +## Settled + +- **Re-importing the config does not reload a flow file it imports** — **CONFIRMED** on Node + 22.22: after an edit, a cache-busted re-import still returns the old value. **`node --watch` + restarts on an imported module's change and not on an unrelated file** — **CONFIRMED**. + Evidence: [`poc/esm-reload/`](poc/esm-reload/README.md). + +## How it got here + +- **Draft** — distribute Shift Manager beyond the repository: a generic fsdev app hook with + `--host` and `--watch`, two `node` page options, a published thin CLI; three PRs. + +**Open: none.** diff --git a/specs/issues/FIX-1770/DOCS.md b/specs/issues/FIX-1770/DOCS.md new file mode 100644 index 0000000000..a9ae866dc1 --- /dev/null +++ b/specs/issues/FIX-1770/DOCS.md @@ -0,0 +1,136 @@ +# FIX-1770 · Documentation draft + +[Spec](SPEC.md) · [Decisions](DECISIONS.md) · [Rules](BUSINESS-RULES.md) · [Plan](PLAN.md) · **Docs** · [Evolution](EVOLUTION.md) + +Proposed reader-facing prose. Implementation reconciles it against what ships, then publishes +it. Voice rules most at risk here: no em-dash as a connector, no "seamless", "worker" for +what runs a row, and say what `fsdev dev` is the first time a page names it. + +## UPDATE · `apps/docs/docs/shift-manager/overview.md` · intro, third paragraph + +Replace "It lives in this repository under `labs/shift-manager` and isn't published to npm, so +you run it from a checkout." with: + +> It is published to npm as `@flow-state-dev/shift-manager`. The pages ship built, so there is +> nothing to compile. + +## UPDATE · `apps/docs/docs/shift-manager/overview.md` · replace "Run it" up to "The `devteam` profile" + +> ## Run it +> +> Install it in the project that holds your Lab's config, then point it at that config: +> +> ```bash +> npm install @flow-state-dev/shift-manager +> npx shift-manager --config ./fsdev.config.mts +> ``` +> +> Without `--config`, it looks for `fsdev.config.ts` (or `.mts`, `.js`, `.mjs`) in the current +> directory, the way `fsdev dev` does. It prints its address, `http://127.0.0.1:4300` by +> default, and opens it. One process serves the Lab's API under `/api/flows`, Shift Manager's +> pages, and the [DevTool](../devtool/overview.md) over the same Lab on a port of its own. +> +> | Option | Default | What it does | +> |--------|---------|--------------| +> | `--config ` | `fsdev.config.*` in the current directory | The Lab's config. A relative path resolves from where you ran the command. | +> | `--port ` | `4300` | `0` picks a free port. | +> | `--host ` | `127.0.0.1` | A non-loopback host is refused unless the Lab authenticates requests, and always refused for a Lab that hands its page a bearer token. | +> | `--shift ` | `SHIFT_MANAGER_SHIFT`, else unset | Start on the light (`day`) or dark (`night`) look. Unset, the page follows your OS. | +> | `--dev` | off | Restart the Lab when you save one of its files. See below. Loopback only. | +> | `--assets ` | the built pages in the package | Serve a different build of the pages, as it is. | +> | `--no-open` | opens | Don't open the browser. | +> +> The process runs from the directory you started it in, so a Lab's relative paths, such as a +> SQLite file, land where they would under `fsdev dev`. A config that doesn't load, or doesn't +> default-export a `FlowState`, stops the command with the loader's message. +> +> If the DevTool's pages aren't installed, Shift Manager still starts, says so, and turns +> *Open trace* off. Install `@flow-state-dev/devtool` to get them. +> +> ### While you edit your Lab +> +> Add `--dev` and leave it running. When you save a file your Lab loaded, a flow module or a +> file under the config's folder such as a `WORKER.md`, the Lab restarts by itself and the page +> reloads. Saving something the Lab didn't load, or its data file, does nothing. +> +> If the Lab fails to start after a save, the error prints and Shift Manager waits for the +> next save. A restart is a new process: a Lab with in-memory stores starts empty each time, +> so use SQLite if you want your data to survive edits. +> +> ### Working on Shift Manager itself +> +> In this repository, `pnpm --filter @flow-state-dev/shift-manager dev` runs the `devteam` +> profile with `--dev`. From a checkout, `--dev` also serves Shift Manager's pages from source, +> so a change to a screen shows as you save it. `start` runs the same profile on the built +> pages, and builds them first when they're older than their source. +> +> To open another Lab from a checkout, pass its config: +> `pnpm --filter @flow-state-dev/shift-manager dev --config ../my-lab/fsdev.config.mts`. + +## UPDATE · `apps/docs/docs/shift-manager/overview.md` · "The `devteam` profile", first sentence + +> `devteam` is the team profile in this repository, at `teams/devteam/fsdev.config.mts`. It +> isn't in the published package, because it builds on the repository's own test Labs. + +Change the data path in that section from `labs/shift-manager/.fsdev/devteam.sqlite` to +`packages/shift-manager/.fsdev/devteam.sqlite`. + +## UPDATE · `apps/docs/docs/api/cli.md` · `fsdev dev` options table, three rows + +> | `--app ` | Serve an app's pages at the root instead of the DevTool. See [Serving an app beside your flows](#serving-an-app-beside-your-flows). | +> | `--host ` | Host to bind (default `127.0.0.1`). A non-loopback host runs the same check as `fsdev serve` and refuses a config that hands its page a bearer token. | +> | `--watch` | Restart when a file your config loaded changes. Loopback only. | + +## UPDATE · `apps/docs/docs/api/cli.md` · new subsection after the `fsdev dev` paragraph + +> #### Serving an app beside your flows +> +> `fsdev dev` normally puts the DevTool at the root of its port. With `--app`, your own app's +> pages go there instead and the DevTool moves to a port of its own: +> +> ```bash +> fsdev dev --config ./fsdev.config.mts --app @acme/ops-console +> ``` +> +> `--app` takes a directory with an `index.html`, or a package that exports `getAssetPath()`, +> a function returning that directory. The API stays at `/api/flows` on the same origin, so +> your pages call it with relative URLs and need no proxy. +> +> Every HTML page fsdev serves carries two things your app can read on boot. The connection +> config from your config's `devtool` block is `window.__FSD_DEVTOOL_CONFIG__`, as the DevTool +> gets it, on a loopback host only. The DevTool's address is +> ``, absent when the DevTool isn't installed. +> +> With `--watch`, a package that also exports `getSourceRoot()` is served from that folder +> through Vite, loaded from the app's own install, so its pages reload as you edit them. When +> `getSourceRoot()` returns nothing, or Vite isn't installed there, the built pages are served. +> +> This is for development. To host an app's pages in production, pass its directory as +> `staticDir` to [`serve()`](/docs/server/host-adapters). + +## UPDATE · `packages/cli/README.md` · `fsdev dev` section + +Add the three flags as in the CLI reference, and one example: + +> ```bash +> # Your own app's pages beside your flows, restarting on a change +> fsdev dev --app @acme/ops-console --watch +> ``` + +## UPDATE · `packages/node/README.md` · `ServeOptions` table, two rows + +> | page meta option | — | A `Record` of `` tags written into every HTML page served from `staticDir`, on any host. Not for secrets. | +> | page handler option | — | A Connect-style `(req, res, next)` handler tried before `staticDir` for non-API GET requests, for a dev server's middleware. | + +The implementer fills in the two option names. + +## UPDATE · `packages/shift-manager/README.md` · "Run it" + +Replace with the site page's "Run it" section above, verbatim, and remove the paragraphs on +`--team`, `--devtool` and `--devtool-assets`. + +## Publication ownership + +PR-A publishes the CLI reference's `--app` and `--host` rows, the subsection without its +`--watch` paragraph, and the `node` README rows. PR-B adds `--watch`. PR-C publishes the +Shift Manager page and README. No new page and no sidebar change. diff --git a/specs/issues/FIX-1770/EVOLUTION.md b/specs/issues/FIX-1770/EVOLUTION.md new file mode 100644 index 0000000000..84771e656f --- /dev/null +++ b/specs/issues/FIX-1770/EVOLUTION.md @@ -0,0 +1,15 @@ +# FIX-1770 · Evolution + +[Spec](SPEC.md) · [Decisions](DECISIONS.md) · [Rules](BUSINESS-RULES.md) · [Plan](PLAN.md) · [Docs](DOCS.md) · **Evolution** + +| Prior intent and precise source | Treatment | Why / evidence | Replacement | Compatibility | +|---|---|---|---|---| +| FIX-1662 D1 *Locks in*: Shift Manager (then App Lab) "ships as a static app plus the shipped Node host, so it runs where `fsdev dev` runs". Source [`../FIX-1662/DECISIONS.md#d1`](../FIX-1662/DECISIONS.md#d1) | **Retained.** Still a static app over `serve()`; the host is now reached through fsdev's app hook | `start.mts` already called `serve()` with `staticDir`, the way `fsdev dev` serves the DevTool | [D1](DECISIONS.md#d1) | The Lab's config is still loaded as is | +| FIX-1662 PLAN S1: "New private package … plus a start script that loads a Lab's config … and hands it to `serve(flowstate, { staticDir })`". Source [`../FIX-1662/PLAN.md#surfaces`](../FIX-1662/PLAN.md#surfaces) | **Superseded.** The package is published and the start script is removed | Jake chose to publish (FIX-1770). The script's generic half belongs to fsdev | [D1](DECISIONS.md#d1), [D2](DECISIONS.md#d2), PLAN S7–S9 | `start --team devteam` becomes `start`; `--config` and `--assets` keep working; `--team`, `--devtool` and `--devtool-assets` are refused as unknown | +| FIX-1664 BR-23: the trace link "opens the devtool App Lab was started with". Source [`../FIX-1664/BUSINESS-RULES.md`](../FIX-1664/BUSINESS-RULES.md) | **Amended.** Only the DevTool served beside the app; no external DevTool by flag | A DevTool in another process can't read an in-memory Lab's runs, which is why Shift Manager started serving its own | BR-9, BR-10 | Callers of `--devtool ` get an unknown-flag refusal | +| FIX-1649 epic, *Decided in review*: "App Lab lives at `labs/app-lab/`, with the repo's dogfooded apps". Source [`../../epics/FIX-1649/DECISIONS.md#decided-in-review-recorded-so-no-child-reopens-them`](../../epics/FIX-1649/DECISIONS.md#decided-in-review-recorded-so-no-child-reopens-them) | **Superseded in part.** Moves to `packages/shift-manager`. The same bullet list's "the design-system package is private" is retained | Every publish guard and the packed-install check read `packages/` only | DECISIONS → *Decided, not asked* | Paths under `goals/` move with it (PLAN S10) | +| FIX-1649 D3: "One app that opens any Lab"; *Locks in* "the chrome stays inside `labs/app-lab`". Source [`../../epics/FIX-1649/DECISIONS.md#d3`](../../epics/FIX-1649/DECISIONS.md#d3) | **Retained**, extended to Labs outside this repository; the chrome stays inside the Shift Manager package at its new path | Nothing about a Lab changes; only where the app installs from | [D2](DECISIONS.md#d2) | No Lab writes UI, as before | + +No predecessor is wholly superseded. Compare these intents with current code before building: +`start.mts` on `main` has since gained a stale-build rebuild, which PLAN S10 moves to the +checkout's `start` script. diff --git a/specs/issues/FIX-1770/PLAN.md b/specs/issues/FIX-1770/PLAN.md new file mode 100644 index 0000000000..4ccd8f4266 --- /dev/null +++ b/specs/issues/FIX-1770/PLAN.md @@ -0,0 +1,126 @@ +# FIX-1770 · Plan + +[Spec](SPEC.md) · [Decisions](DECISIONS.md) · [Rules](BUSINESS-RULES.md) · **Plan** · [Docs](DOCS.md) · [Evolution](EVOLUTION.md) + +Written for the implementing agent. IDs cross-reference [BUSINESS-RULES.md](BUSINESS-RULES.md) +(BR-n) and [DECISIONS.md](DECISIONS.md) (Dn). `tdd`. Three PRs ([D3](DECISIONS.md#d3)). + +## Surfaces + +| ID | Package · role | Change | Rules | +|---|---|---|---| +| S1 | `node` · `serve()` HTML injection | Page-meta option: `` tags in every HTML response (file and SPA fallback), any host; same injection path as the devtool config | BR-9 BR-11 | +| S2 | `node` · `serve()` page layer | A Connect-style handler tried before `staticDir` for non-API GETs; S1's injection exposed as one function its index path calls | BR-21 | +| S3 | `fsdev` · `dev --app ` | Resolve the app (`getAssetPath()` or a directory with `index.html`); serve it at `--port`'s root; DevTool on port 0, its address as `fsdev-devtool-url`, degrading when missing. Programmatic: extra page meta | BR-1 BR-4–BR-10 | +| S4 | `fsdev` · `dev --host` | Default `127.0.0.1`. Non-loopback: `assertNetworkBindIsAuthenticated`, refuse a declared bearer, skip the debug env defaults | BR-12–BR-14 | +| S5 | `fsdev` · `dev --watch` | A supervisor restarts the serving child on a Lab change (DECISIONS → Decided, not asked); survives a failed child; loopback only | BR-15–BR-19 | +| S6 | `fsdev` · `--watch` with an app that has source | Vite middleware mode at `getSourceRoot()`, resolved from there; index through Vite's transform then S2's injection; else built pages | BR-21 BR-22 | +| S7 | `shift-manager` · the package | Move to `packages/shift-manager`; drop `private`; `bin`, `files` (pages, profiles, command), `publishConfig`; page-only deps to dev; export `getAssetPath()`, `getSourceRoot()`; `prepublishOnly` check as the DevTool's; `minor` changesets for it, `fsdev`, `node` | BR-24 BR-25 | +| S8 | `shift-manager` · the command | Thin wrapper over fsdev's dev entry with `app` set to itself; the shift becomes its scheme meta. The page reads `fsdev-devtool-url` | BR-1–BR-6 BR-11 BR-20 BR-26 | +| S9 | `shift-manager` · **removals** | **Remove** `bin/start.mts`, its temp-copy injection, the Vite `/api` proxy, `--team`, `--devtool`, `--devtool-assets`, the `shift-manager-devtool` meta. Rewrite `test/start.test.ts`; reword the trace-off line naming `--devtool` | — | +| S10 | repository · callers | Scripts `start` (after the build-if-stale step) and `dev` over `teams/devteam/fsdev.config.mts`. Re-point `goals/lib/shift-manager.mts`, `shell.mts` and three `run.mts` that spawn `bin/start.mts`, and `--team devteam` callers; every `labs/shift-manager` path in `goals/` (~20 files) and READMEs | BR-6 | +| S11 | CI · packed install | Pack it; a check runs the installed command over a fixture Lab and reads `/`, an asset, `/api/flows` | BR-1 BR-24 | +| S12 | Docs | Per [DOCS.md](DOCS.md) | — | +| S13 | `goals/shift-manager/it-runs-from-an-install/` | The goal check, with controls `no-page-config` and `no-watch` | Goal | + +## Sequence + +```mermaid +flowchart TD + S1["S1 · page meta"] --> S2["S2 · page handler"] + S1 --> S3["S3 · --app"] + S3 --> S4["S4 · --host"] + S3 --> S5["S5 · --watch"] + S2 --> S6["S6 · Vite from source"] + S5 --> S6 + S6 --> S7["S7 · the package"] + S7 --> S8["S8 · the command"] + S8 --> S9["S9 · removals"] + S8 --> S10["S10 · callers"] + S10 --> S11["S11 · packed install"] + S11 --> S13["S13 · goal check"] + S8 --> S12["S12 · docs"] +``` + +| PR | Deliverables | depends_on | +|---|---|---| +| PR-A | S1 S2 S3 S4, their docs, V1–V4 | — | +| PR-B | S5 S6, their docs, V5–V6 | PR-A | +| PR-C | S7–S13, V7–V10, VG | PR-B | + +## Checks + +| ID | Runs after | Passes when | +|---|---|---| +| V1 | S1 S2 | No new option: byte-identical (BP-030); meta on file and fallback HTML; handler sees non-API GETs only | +| V2 | S3 | BR-1 BR-4–BR-10 on a fixture directory and package; BR-7 on the existing suite | +| V3 | S4 | BR-12–BR-14 by message; BR-14 reads the debug route anonymously and is refused | +| V4 | S3 | **D1:** a source check finds no Workforce or Shift Manager import or word in the hook modules (BR-23); a planted import turns it red | +| V5 | S5 | BR-16–BR-19 on a real child: save a module, a tree file, a page file, a data file; count restarts | +| V6 | S6 | BR-21 BR-22: the index carries Vite's client and the config; no Vite falls back | +| V7 | S7 | **D2:** tarball has pages, profiles, command; no `src/`, `teams/`, `test/`; publish without pages fails (BR-24 BR-25) | +| V8 | S8 S9 | BR-2 BR-3 BR-6 BR-11 BR-26 via the command; no `bin/start.mts` or `shift-manager-devtool` left | +| V9 | S10 | Every `goals/shift-manager/` goal passes as before, controls' FAILs included | +| V10 | S11 | Packed install passes; fails with `shift-manager` left out of the pack | +| VG | S13 | [The goal](SPEC.md#the-goal-and-how-well-know-its-met): `goals/shift-manager/it-runs-from-an-install/run.mts` PASSES after FAILing under each control. **D3:** each PR's checks pass on that PR alone | + +## Pinned names + +| Where | Name | Why pinned | +|---|---|---| +| Command | `shift-manager`, with `--config --port --host --shift --assets --dev --no-open` | Public. People type it | +| fsdev flags | `fsdev dev --app `, `--host `, `--watch` | Public, and D1's contract | +| App contract | `getAssetPath()` (as `@flow-state-dev/devtool`), optional `getSourceRoot()` | What any app beside a Lab exports | +| Page meta | `fsdev-devtool-url` | A page reads it | +| Location | `packages/shift-manager`, name unchanged | Publish guards and packed install look there | + +Everything else, including the two `node` option names, is yours. + +## Guardrails + +| Rule | Because | +|---|---| +| One HTML injection path in `node`, the Vite index included | Two writers drift, and the bearer's loopback rule lives there (tenet 5) | +| Nothing in fsdev or `node` names a team, worker, roster or shift | Jake's layer rule. Policy plugs in as page meta from the wrapper (tenet 4) | +| Debug surface and bearer are loopback-only, decided from the bound host | A network bind must stay authenticated (BP-031) | +| `fsdev dev` without `--app` and `serve()` without the new options behave byte for byte as today | Every current user runs those paths (BP-030) | +| `start.mts` and the proxy leave in PR-C, which replaces them | Old beside new is how incoherence starts (tenet 3) | +| Every restart case runs on a real child process and a real file save | A watcher that never fires passes every mocked test (tenet 7) | + +## Docs + +Publish [DOCS.md](DOCS.md) per its ownership section, each part after its PR's checks pass. + +## Sketch · pseudocode, illustrative, react to the shape + +``` +shift-manager [flags]: + scheme ← shift profile named by --shift or SHIFT_MANAGER_SHIFT + fsdev dev entry(config, port, host, watch ← --dev, + app ← --assets or this package, + page meta ← { color scheme: scheme }) + +fsdev dev entry, with an app: + if watch: supervisor runs this entry again as a child, restarts it on a Lab change + lab ← load config + guard the host + devtool ← serve(lab, devtool pages, port 0) page config only + pages ← app source under watch and Vite resolves ? Vite middleware : app's built pages + serve(lab, pages, port, page meta + devtool url) +``` + +**POC:** [`poc/esm-reload/`](poc/esm-reload/README.md): a re-imported config keeps the old flow; +`node --watch` restarts on imported modules only. The restart premise held. + +## At implement time + +- `node --watch` may see Vite's temporary config bundle. If restarts loop, use an own watch list. +- PR #2715 edits `labs/shift-manager/README.md`. If it merges first, move its text with the package. +- DevTeam's tree is under `goals/devforce-lab/lab/`, outside its config's directory: a `WORKER.md` + edit there is no Lab change (BR-17). Say so; don't special-case it. +- Check `release:build` builds Shift Manager's pages once it sits in `packages/`. + +## Follow-ups + +- `fsdev` already imports `@flow-state-dev/workforce` for `fsdev gen`, which the layer rule says + L1 must not. Out of scope; file it. diff --git a/specs/issues/FIX-1770/SPEC.md b/specs/issues/FIX-1770/SPEC.md new file mode 100644 index 0000000000..ffd7a09b75 --- /dev/null +++ b/specs/issues/FIX-1770/SPEC.md @@ -0,0 +1,109 @@ +# FIX-1770 · Run Shift Manager against your own Lab with one command, with a dev mode + +**Spec** · [Decisions](DECISIONS.md) · [Rules](BUSINESS-RULES.md) · [Plan](PLAN.md) · [Docs](DOCS.md) · [Evolution](EVOLUTION.md) + +## Five people, before and after + +| Someone who… | Today | After | +|---|---|---| +| **has their own Lab, outside this repository** | Can't run Shift Manager: it is private and starts only from a checkout | Installs it, runs `shift-manager --config ./fsdev.config.mts`. Nothing to build | +| **edits their Lab's flows while Shift Manager is open** | Restarts the process by hand after every change | Adds `--dev`: a save restarts the Lab and reloads the page | +| **works on Shift Manager's pages in this repository** | Runs Vite and the start script in two terminals; the Vite page misses the DevTool link, shift, user and token | One command with `--dev`: live pages, same config | +| **builds another app to sit beside a Lab** | Copies `start.mts` | Runs `fsdev dev --app `; fsdev knows nothing about the app | +| **binds Shift Manager to a network address** | Refused unless the Lab authenticates, and always when the page would get a bearer | The same refusals, now in fsdev, for every app | + +Shift Manager is how people work a Workforce team. Today nobody outside this repository can run it. + +## The goal, and how we'll know it's met + +**Someone outside this repository installs Shift Manager, opens their own Lab in the browser with one command and no build, and with `--dev` sees a saved change to their Lab take effect without restarting anything by hand.** + +| Is it the right goal? | | +|---|---| +| **The real need** | "A version that is going to be better to distribute once this is being used by others", plus "a dev mode that works like start, where you pass in a config for which team to run" (Jake, [FIX-1770](https://linear.app/fixpoint-labs/issue/FIX-1770)) | +| **Smaller, and rejected** | "`start.mts` gets a `--dev` flag." Fixes the two terminals and leaves every outside user unable to install it | +| **Bigger, and not this issue's** | Hosting Shift Manager as a deployed team service, with its own auth questions | +| **Not done if** | It passes only in a checkout, where workspace links hide a missing file · the page loads but can't read the Lab · `--dev` misses a flow edit · fsdev learns a Workforce word | + +```mermaid +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 +``` + +The check reads what a browser shows from an installed copy. Each control must turn its leg red. + +| How we verify | | +|---|---| +| **Goal check** | `goals/shift-manager/it-runs-from-an-install/` · model n/a · the implementer, at completion · verdict in PR-C. Needs Chromium; hand to `fsd-qa` only if the implementer can't run it | +| **Signal** | **a:** the sidebar's TEAMS equals the held-out Lab's declared workers, and *Open trace* loads the DevTool on a session of that Lab. **b:** within 20 s of saving a change to the Lab, with no other input, the page shows it | +| **Input** | A small Lab (config and Workforce tree) importing only installed packages. Another tree, or another changed file, must pass too | +| **Anti-game** | No repository import, workspace link or `pnpm` filter. Read the page, never fsdev's log | +| **Control that must fail** | `GOAL_CONTROL=no-page-config` must FAIL **a:TEAMS equals the Lab's workers**. `GOAL_CONTROL=no-watch` must FAIL **b:the change shows**. Today's `main` fails at install: there is no `shift-manager` to install | + +## What changes + +![Before: two terminals and a lab script, checkout only. After: one installed command over fsdev's app hook and node's serve()](figures/what-changes.svg) + +Left, a lab script does it all. Right, fsdev owns the generic part, below the framework line. + +**What an outside user types:** + +```diff +- git clone … && pnpm install && pnpm --filter @flow-state-dev/shift-manager build +- pnpm --filter @flow-state-dev/shift-manager start --config ../my-lab/fsdev.config.mts ++ npm install @flow-state-dev/shift-manager ++ npx shift-manager --config ./fsdev.config.mts # add --dev while you edit your flows +``` + +**What a Shift Manager developer types in this repository:** + +```diff +- pnpm --filter @flow-state-dev/shift-manager start --team devteam # terminal 1 +- pnpm --filter @flow-state-dev/shift-manager dev # terminal 2, proxies /api to :4300 ++ pnpm --filter @flow-state-dev/shift-manager dev # one process: Vite, the Lab, the DevTool +``` + +**What any other app beside a Lab types:** + +```diff + fsdev dev --config ./fsdev.config.mts ++ fsdev dev --config ./fsdev.config.mts --app @acme/ops-console --watch +``` + +## How a request reaches the Lab + +```mermaid +flowchart LR + U["browser"] --> H["one port · the app's pages"] + H -->|"/api/flows"| L["the Lab · its FlowState"] + H -->|"other paths"| G["built pages, or Vite in --dev from source"] + D["DevTool · its own port"] -->|"/api/flows"| L + W["--dev watcher"] -.->|"restart on a Lab change"| L +``` + +Pages and Lab share one origin, so no proxy. The DevTool keeps its own port: its build loads from `/`. + +## What stays as it is + +- Shift Manager's screens, and the Lab's config, which is never edited or wrapped. +- `fsdev dev` with no `--app`: the DevTool at the root of port 4200, on loopback. +- `@flow-state-dev/node`'s production use: `serve()` with a static directory behaves byte for byte as today. +- The team profiles under `teams/`: repository only, not published. + +## Sign off + +**[The goal](#the-goal-and-how-well-know-its-met), at that size:** an install, one command, and `--dev` restarting on a Lab change. If wrong: we publish a package that works only in a checkout. + +1. **[D1](DECISIONS.md#d1) · fsdev owns the "pages beside the Lab" hook; `@flow-state-dev/node` gets only two generic page-serving options.** If wrong: dev tooling in a production host, or a hook every app rewrites. +2. **[D2](DECISIONS.md#d2) · The published package ships built pages only. `--dev` restarts your Lab; live page editing needs a checkout.** If wrong: outside users can't change the screens without cloning. +3. **[D3](DECISIONS.md#d3) · Three PRs, in order: the fsdev hook, then `--watch`, then the published package.** If wrong: nothing installs until the third PR merges. + +**Open: none.** D1 is the one to weigh. **News, hard to reverse:** the first npm publish of `@flow-state-dev/shift-manager`; an npm name is permanent. Reasoning: [DECISIONS.md](DECISIONS.md). Cases: [BUSINESS-RULES.md](BUSINESS-RULES.md). + +Feature · `fsdev` + `node` + `shift-manager` · large (13 surfaces, 3 PRs) · project Workforce: Shift Manager · no epic diff --git a/specs/issues/FIX-1770/figures/d1-hook-home.svg b/specs/issues/FIX-1770/figures/d1-hook-home.svg new file mode 100644 index 0000000000..8f595d7405 --- /dev/null +++ b/specs/issues/FIX-1770/figures/d1-hook-home.svg @@ -0,0 +1,100 @@ + + + + + + + D1 · THE CALL + Which package owns "serve this app's pages beside the Lab"? + + + + + CHOSEN + fsdev, with two generic node options + + INSTEAD OF + node's serve() learns apps + + + + + + WHAT A PRODUCTION + INSTALL CARRIES + ▸ DECIDES IT + + + No dev tooling + Vite and the watcher stay in fsdev + − + Vite and a file watcher + in every server that installs node + + + + NEW PUBLIC SURFACE + − + Three fsdev flags, two node options + --app, --host, --watch + + + Options on one function + but each one dev-only + + + + + WORKFORCE IN L1 + = + None + neither names a team or a worker + = + None + the same + + + + + + LOCKS IN + An app is anything exporting getAssetPath() + production hosting of an app stays serve() with staticDir + + + + + FLIPS IF + Production needs an app with the DevTool beside it + then the hook is hosting, and belongs in node + + diff --git a/specs/issues/FIX-1770/figures/d2-dev-for-whom.svg b/specs/issues/FIX-1770/figures/d2-dev-for-whom.svg new file mode 100644 index 0000000000..7fe806aed0 --- /dev/null +++ b/specs/issues/FIX-1770/figures/d2-dev-for-whom.svg @@ -0,0 +1,99 @@ + + + + + + + D2 · THE CALL + What does --dev give someone who installed Shift Manager? + + + + + CHOSEN + Built pages, and a Lab restart + + INSTEAD OF + Source and Vite, live page reload + + + + + + WHO EDITS WHAT + ▸ DECIDES IT + + + Matches what they edit + their Lab restarts when they save + − + Reloads pages they never edit + Shift Manager's screens aren't theirs + + + + THE INSTALL + + + Small + no build toolchain in their dependencies + − + Vite, React tooling, Tailwind + in every user's install + + + + + CHANGING THE SCREENS + − + Needs a checkout + no live page editing in an install + + + Possible in any install + edit the shipped source + + + + + + LOCKS IN + One flag, two meanings, set by the install + in a checkout --dev also serves pages from source + + + + + FLIPS IF + Outside users ask to change the screens + then a source package or theming is its own issue + + diff --git a/specs/issues/FIX-1770/figures/d3-three-prs.svg b/specs/issues/FIX-1770/figures/d3-three-prs.svg new file mode 100644 index 0000000000..2b16994335 --- /dev/null +++ b/specs/issues/FIX-1770/figures/d3-three-prs.svg @@ -0,0 +1,100 @@ + + + + + + + D3 · THE CALL + How does this ship? + + + + + CHOSEN + Three PRs: hook, watch, publish + + INSTEAD OF + One PR + + + + + + WHAT ONE REVIEW + HAS TO HOLD + ▸ DECIDES IT + + + One idea each + a host option, a supervisor, a package move + − + All of it at once + node, fsdev and a package move + + + + WHEN IT INSTALLS + − + After the third PR + the goal check runs only then + = + When the one PR merges + about the same day, if review is quick + + + + + THE REPO MEANWHILE + = + Keeps working + start.mts leaves only in the third PR + = + Keeps working + one switch-over + + + + + + LOCKS IN + Nothing installs until the third PR merges + each earlier PR ships a usable fsdev feature + + + + + FLIPS IF + The three need to land as one release + then the PRs merge together, same order + + diff --git a/specs/issues/FIX-1770/figures/what-changes.svg b/specs/issues/FIX-1770/figures/what-changes.svg new file mode 100644 index 0000000000..0855882628 --- /dev/null +++ b/specs/issues/FIX-1770/figures/what-changes.svg @@ -0,0 +1,69 @@ + + + + + + + BEFORE · IN A CHECKOUT ONLY + + TERMINAL 1 + pnpm --filter …/shift-manager dev + Vite on its own port + proxies /api to the Lab on :4300 + page has no DevTool link, shift, user or token + + TERMINAL 2 + pnpm … start --team devteam + a lab script, bin/start.mts, that does it all: + loads the config · guards the host + serves the DevTool on a second port + copies the pages to write the config in + needs a fresh build of dist/ + no restart when a flow changes + + + + + AFTER · FROM AN INSTALL, ONE COMMAND + + SHIFT MANAGER · PUBLISHED + shift-manager --config … [--dev] + a thin wrapper: built pages, plus the shift + + + FRAMEWORK · L1 + + FSDEV DEV --APP + loads the config · guards the host + serves the DevTool beside the pages + hands the page its config + --watch: restarts the Lab on a change + in a checkout: pages from source via Vite + + + NODE · SERVE() + serves the pages, writes the page config into HTML + + diff --git a/specs/issues/FIX-1770/poc/esm-reload/README.md b/specs/issues/FIX-1770/poc/esm-reload/README.md new file mode 100644 index 0000000000..e76f57e05a --- /dev/null +++ b/specs/issues/FIX-1770/poc/esm-reload/README.md @@ -0,0 +1,23 @@ +# POC · esm-reload + +Throwaway evidence for [FIX-1770](../../SPEC.md). Not production code, not discovered by any +test runner. + +**Question:** can `--dev` reload a Lab inside the running process, or must it restart the process? + +**Run:** `node specs/issues/FIX-1770/poc/esm-reload/probe.mjs` (Node 22, no dependencies). + +**Result (Node 22.22.0, 2026-10-04):** + +``` +{"probe":"re-import reloads an imported flow","first":1,"second":1,"verdict":"no"} +{"probe":"node --watch restarts on imported module only","afterUnrelated":1,"afterImported":2,"verdict":"yes"} +``` + +A cache-busted re-import of the config (what `loadFsdevConfig` does) returns the old flow +module, so an in-process reload would serve stale flows. `node --watch` restarts on an imported +module's change and ignores an unrelated file. The restart is a process restart +([DECISIONS → Decided, not asked](../../DECISIONS.md#decided-not-asked)). + +**Control:** probe 1 fails (exit 1) if Node ever reloads the imported module; probe 2 fails if +the unrelated file triggers a restart or the imported one doesn't. diff --git a/specs/issues/FIX-1770/poc/esm-reload/probe.mjs b/specs/issues/FIX-1770/poc/esm-reload/probe.mjs new file mode 100644 index 0000000000..6fc91cc54f --- /dev/null +++ b/specs/issues/FIX-1770/poc/esm-reload/probe.mjs @@ -0,0 +1,49 @@ +#!/usr/bin/env node +/** + * Throwaway evidence for FIX-1770's restart premise. Two probes, in a temp directory: + * 1. Re-importing a config with a cache-busting query does NOT reload a module it imports. + * 2. `node --watch` restarts when an imported module changes, and not when an unrelated file does. + * Prints one JSON verdict per probe. Exit 0 when both premises hold. + */ +import { spawn } from "node:child_process"; +import { mkdtempSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { pathToFileURL } from "node:url"; + +const dir = mkdtempSync(join(tmpdir(), "fix-1770-esm-")); +const wait = (ms) => new Promise((r) => setTimeout(r, ms)); +let ok = true; + +// Probe 1: cache-busted re-import of the config. +writeFileSync(join(dir, "flow.mjs"), "export const v = 1;"); +writeFileSync(join(dir, "config.mjs"), 'import { v } from "./flow.mjs"; export default v;'); +const url = pathToFileURL(join(dir, "config.mjs")).href; +const first = (await import(`${url}?t=1`)).default; +writeFileSync(join(dir, "flow.mjs"), "export const v = 2;"); +const second = (await import(`${url}?t=2`)).default; +const reloads = second === 2; +console.log(JSON.stringify({ probe: "re-import reloads an imported flow", first, second, verdict: reloads ? "yes" : "no" })); +if (reloads) ok = false; + +// Probe 2: node --watch on the module graph. +writeFileSync(join(dir, "flow.mjs"), "export const v = 1;"); +writeFileSync(join(dir, "server.mjs"), 'import { v } from "./flow.mjs"; console.log("started v=" + v); setInterval(() => {}, 1000);'); +const child = spawn(process.execPath, ["--watch", "server.mjs"], { cwd: dir }); +let log = ""; +child.stdout.on("data", (d) => (log += d)); +child.stderr.on("data", (d) => (log += d)); +await wait(1500); +writeFileSync(join(dir, "unrelated.txt"), "not imported"); +await wait(1500); +const afterUnrelated = (log.match(/started/g) ?? []).length; +writeFileSync(join(dir, "flow.mjs"), "export const v = 2;"); +await wait(2000); +const afterImported = (log.match(/started/g) ?? []).length; +child.kill(); +const watchHolds = afterUnrelated === 1 && afterImported === 2 && log.includes("started v=2"); +console.log(JSON.stringify({ probe: "node --watch restarts on imported module only", afterUnrelated, afterImported, verdict: watchHolds ? "yes" : "no" })); +if (!watchHolds) ok = false; + +rmSync(dir, { recursive: true, force: true }); +process.exit(ok ? 0 : 1); From 3c2df08f2b5ebec45870cf0183ceddface61d320 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 4 Oct 2026 20:49:21 +0000 Subject: [PATCH 2/3] spec(FIX-1770): name node --watch as the one watch authority for --watch Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_018KBgKPRLfqjmV2LS88Eg9S --- specs/issues/FIX-1770/PLAN.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/issues/FIX-1770/PLAN.md b/specs/issues/FIX-1770/PLAN.md index 4ccd8f4266..d905163440 100644 --- a/specs/issues/FIX-1770/PLAN.md +++ b/specs/issues/FIX-1770/PLAN.md @@ -13,7 +13,7 @@ Written for the implementing agent. IDs cross-reference [BUSINESS-RULES.md](BUSI | S2 | `node` · `serve()` page layer | A Connect-style handler tried before `staticDir` for non-API GETs; S1's injection exposed as one function its index path calls | BR-21 | | S3 | `fsdev` · `dev --app ` | Resolve the app (`getAssetPath()` or a directory with `index.html`); serve it at `--port`'s root; DevTool on port 0, its address as `fsdev-devtool-url`, degrading when missing. Programmatic: extra page meta | BR-1 BR-4–BR-10 | | S4 | `fsdev` · `dev --host` | Default `127.0.0.1`. Non-loopback: `assertNetworkBindIsAuthenticated`, refuse a declared bearer, skip the debug env defaults | BR-12–BR-14 | -| S5 | `fsdev` · `dev --watch` | A supervisor restarts the serving child on a Lab change (DECISIONS → Decided, not asked); survives a failed child; loopback only | BR-15–BR-19 | +| S5 | `fsdev` · `dev --watch` | Re-runs the dev entry as a child under `node --watch`, the one watch authority (no watcher package), so a Lab change restarts it (DECISIONS → Decided, not asked); survives a failed child; loopback only | BR-15–BR-19 | | S6 | `fsdev` · `--watch` with an app that has source | Vite middleware mode at `getSourceRoot()`, resolved from there; index through Vite's transform then S2's injection; else built pages | BR-21 BR-22 | | S7 | `shift-manager` · the package | Move to `packages/shift-manager`; drop `private`; `bin`, `files` (pages, profiles, command), `publishConfig`; page-only deps to dev; export `getAssetPath()`, `getSourceRoot()`; `prepublishOnly` check as the DevTool's; `minor` changesets for it, `fsdev`, `node` | BR-24 BR-25 | | S8 | `shift-manager` · the command | Thin wrapper over fsdev's dev entry with `app` set to itself; the shift becomes its scheme meta. The page reads `fsdev-devtool-url` | BR-1–BR-6 BR-11 BR-20 BR-26 | From d2e2732cea77eb6bb2ca247cd52400490998e480 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 4 Oct 2026 20:51:43 +0000 Subject: [PATCH 3/3] spec(FIX-1770): fold review round 1 (reload signal, route order, auth override, patch changesets) Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_018KBgKPRLfqjmV2LS88Eg9S --- specs/issues/FIX-1770/BUSINESS-RULES.md | 4 ++-- specs/issues/FIX-1770/DECISIONS.md | 3 +++ specs/issues/FIX-1770/PLAN.md | 14 +++++++------- 3 files changed, 12 insertions(+), 9 deletions(-) diff --git a/specs/issues/FIX-1770/BUSINESS-RULES.md b/specs/issues/FIX-1770/BUSINESS-RULES.md index 5d41281756..18edc0b4b2 100644 --- a/specs/issues/FIX-1770/BUSINESS-RULES.md +++ b/specs/issues/FIX-1770/BUSINESS-RULES.md @@ -30,7 +30,7 @@ The cases, as rules. *Proved by* is the check the plan runs. A rule marked *(fsd | # | When | Then | Proved by | |---|---|---|---| -| BR-12 | `--host` is not a loopback address and the Lab would run as the framework's unauthenticated default principal | Refused, with the guard's message *(fsdev)* | CI | +| BR-12 | `--host` is not a loopback address and the Lab would run as the framework's unauthenticated default principal | Refused, with the guard's message; `--allow-unauthenticated` overrides it for a Lab authenticated at host level, as on `fsdev serve` *(fsdev)* | CI | | BR-13 | `--host` is not loopback and the Lab declares a bearer for its page | Refused: the token only ever goes to a loopback page *(fsdev)* | CI | | BR-14 | `--host` is not loopback and the bind is allowed | The anonymous debug surface `fsdev dev` opens on loopback stays closed *(fsdev)* | CI | | BR-15 | `--dev` with a non-loopback `--host` | Refused *(fsdev, as `--watch`)* | CI | @@ -39,7 +39,7 @@ The cases, as rules. *Proved by* is the check the plan runs. A rule marked *(fsd | # | When | Then | Proved by | |---|---|---|---| -| BR-16 | A module the Lab imported is saved | The Lab restarts within seconds, the command keeps running, the page reloads *(fsdev)* | Goal check b · CI | +| BR-16 | A module the Lab imported is saved | The Lab restarts within seconds on the same port, the command keeps running, and an open page reloads itself, built pages included *(fsdev)* | Goal check b · CI | | BR-17 | A file under the config's directory is saved, such as a `WORKER.md` | Same as BR-16 *(fsdev)* | CI | | BR-18 | The app's page source, the Lab's data file, or anything in `node_modules` is saved | The Lab does not restart *(fsdev)* | CI | | BR-19 | A restart fails, for example on a syntax error | The error prints, the command keeps watching, and the next save tries again *(fsdev)* | CI | diff --git a/specs/issues/FIX-1770/DECISIONS.md b/specs/issues/FIX-1770/DECISIONS.md index 16621750ba..97f9abf472 100644 --- a/specs/issues/FIX-1770/DECISIONS.md +++ b/specs/issues/FIX-1770/DECISIONS.md @@ -105,5 +105,8 @@ It comes down to what one review has to hold: one PR mixes a host change, a supe - **Draft** — distribute Shift Manager beyond the repository: a generic fsdev app hook with `--host` and `--watch`, two `node` page options, a published thin CLI; three PRs. +- **Round 1** — folded from review: `node --watch` is the one watch authority; the parent fixes + the port and a dev-only signal reloads an open page; dedicated GET routes stay ahead of the + page handler; `--allow-unauthenticated` as on `fsdev serve`; `patch` changesets. **Open: none.** diff --git a/specs/issues/FIX-1770/PLAN.md b/specs/issues/FIX-1770/PLAN.md index d905163440..598f24e9c0 100644 --- a/specs/issues/FIX-1770/PLAN.md +++ b/specs/issues/FIX-1770/PLAN.md @@ -10,12 +10,12 @@ Written for the implementing agent. IDs cross-reference [BUSINESS-RULES.md](BUSI | ID | Package · role | Change | Rules | |---|---|---|---| | S1 | `node` · `serve()` HTML injection | Page-meta option: `` tags in every HTML response (file and SPA fallback), any host; same injection path as the devtool config | BR-9 BR-11 | -| S2 | `node` · `serve()` page layer | A Connect-style handler tried before `staticDir` for non-API GETs; S1's injection exposed as one function its index path calls | BR-21 | +| S2 | `node` · `serve()` page layer | A Connect-style handler for non-API GETs, tried after a real file and the dedicated-route dispatch, before the SPA fallback; S1's injection exposed as one function its index path calls | BR-21 | | S3 | `fsdev` · `dev --app ` | Resolve the app (`getAssetPath()` or a directory with `index.html`); serve it at `--port`'s root; DevTool on port 0, its address as `fsdev-devtool-url`, degrading when missing. Programmatic: extra page meta | BR-1 BR-4–BR-10 | -| S4 | `fsdev` · `dev --host` | Default `127.0.0.1`. Non-loopback: `assertNetworkBindIsAuthenticated`, refuse a declared bearer, skip the debug env defaults | BR-12–BR-14 | -| S5 | `fsdev` · `dev --watch` | Re-runs the dev entry as a child under `node --watch`, the one watch authority (no watcher package), so a Lab change restarts it (DECISIONS → Decided, not asked); survives a failed child; loopback only | BR-15–BR-19 | +| S4 | `fsdev` · `dev --host` | Default `127.0.0.1`. Non-loopback: `assertNetworkBindIsAuthenticated` with `--allow-unauthenticated` as `fsdev serve` has it, refuse a declared bearer, skip the debug env defaults | BR-12–BR-14 | +| S5 | `fsdev` · `dev --watch` | Re-runs the dev entry as a child under `node --watch`, the one watch authority (no watcher package), so a Lab change restarts it (DECISIONS → Decided, not asked); the parent resolves the port once (including `--port 0`) and hands it to every child; a dev-only page signal (boot id in a meta, a reconnecting stream) reloads an open page when a new child is up, with built pages too; survives a failed child; loopback only | BR-15–BR-19 | | S6 | `fsdev` · `--watch` with an app that has source | Vite middleware mode at `getSourceRoot()`, resolved from there; index through Vite's transform then S2's injection; else built pages | BR-21 BR-22 | -| S7 | `shift-manager` · the package | Move to `packages/shift-manager`; drop `private`; `bin`, `files` (pages, profiles, command), `publishConfig`; page-only deps to dev; export `getAssetPath()`, `getSourceRoot()`; `prepublishOnly` check as the DevTool's; `minor` changesets for it, `fsdev`, `node` | BR-24 BR-25 | +| S7 | `shift-manager` · the package | Move to `packages/shift-manager`; drop `private`; `bin`, `files` (pages, profiles, command), `publishConfig`; page-only deps to dev; export `getAssetPath()`, `getSourceRoot()`; `prepublishOnly` check as the DevTool's; `patch` changesets for it, `fsdev`, `node` (additive, per AGENTS.md) | BR-24 BR-25 | | S8 | `shift-manager` · the command | Thin wrapper over fsdev's dev entry with `app` set to itself; the shift becomes its scheme meta. The page reads `fsdev-devtool-url` | BR-1–BR-6 BR-11 BR-20 BR-26 | | S9 | `shift-manager` · **removals** | **Remove** `bin/start.mts`, its temp-copy injection, the Vite `/api` proxy, `--team`, `--devtool`, `--devtool-assets`, the `shift-manager-devtool` meta. Rewrite `test/start.test.ts`; reword the trace-off line naming `--devtool` | — | | S10 | repository · callers | Scripts `start` (after the build-if-stale step) and `dev` over `teams/devteam/fsdev.config.mts`. Re-point `goals/lib/shift-manager.mts`, `shell.mts` and three `run.mts` that spawn `bin/start.mts`, and `--team devteam` callers; every `labs/shift-manager` path in `goals/` (~20 files) and READMEs | BR-6 | @@ -52,11 +52,11 @@ flowchart TD | ID | Runs after | Passes when | |---|---|---| -| V1 | S1 S2 | No new option: byte-identical (BP-030); meta on file and fallback HTML; handler sees non-API GETs only | +| V1 | S1 S2 | No new option: byte-identical (BP-030); meta on file and fallback HTML; handler sees non-API GETs only; a dedicated GET route such as an OAuth callback still wins over it, during cold start too | | V2 | S3 | BR-1 BR-4–BR-10 on a fixture directory and package; BR-7 on the existing suite | | V3 | S4 | BR-12–BR-14 by message; BR-14 reads the debug route anonymously and is refused | | V4 | S3 | **D1:** a source check finds no Workforce or Shift Manager import or word in the hook modules (BR-23); a planted import turns it red | -| V5 | S5 | BR-16–BR-19 on a real child: save a module, a tree file, a page file, a data file; count restarts | +| V5 | S5 | BR-16–BR-19 on a real child: save a module, a tree file, a page file, a data file; count restarts; an open built page reloads on its own and keeps the same origin under `--port 0` | | V6 | S6 | BR-21 BR-22: the index carries Vite's client and the config; no Vite falls back | | V7 | S7 | **D2:** tarball has pages, profiles, command; no `src/`, `teams/`, `test/`; publish without pages fails (BR-24 BR-25) | | V8 | S8 S9 | BR-2 BR-3 BR-6 BR-11 BR-26 via the command; no `bin/start.mts` or `shift-manager-devtool` left | @@ -69,7 +69,7 @@ flowchart TD | Where | Name | Why pinned | |---|---|---| | Command | `shift-manager`, with `--config --port --host --shift --assets --dev --no-open` | Public. People type it | -| fsdev flags | `fsdev dev --app `, `--host `, `--watch` | Public, and D1's contract | +| fsdev flags | `fsdev dev --app `, `--host `, `--allow-unauthenticated`, `--watch` | Public, and D1's contract | | App contract | `getAssetPath()` (as `@flow-state-dev/devtool`), optional `getSourceRoot()` | What any app beside a Lab exports | | Page meta | `fsdev-devtool-url` | A page reads it | | Location | `packages/shift-manager`, name unchanged | Publish guards and packed install look there |