Repository navigation
spec(FIX-1770): Run Shift Manager against your own Lab with one command, with a dev mode #2734
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 <path>` 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 <dir>` is given | That build is served as it is. No `index.html` there: refused *(fsdev, as `--app <dir>`)* | 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 <name>`, 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; `--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 | | ||
|
|
||
| ## `--dev` | ||
|
|
||
| | # | When | Then | Proved by | | ||
| |---|---|---|---| | ||
| | 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 | | ||
| | 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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,112 @@ | ||
| # 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<br/>node gets two generic options"] | ||
| D1 -.->|"rejected"| X1["node owns it<br/>Vite and a file watcher in a production host"] | ||
| I --> D2["D2 · the package ships built pages<br/>--dev restarts your Lab"] | ||
| D2 -.->|"rejected"| X2["ship source and Vite<br/>every install carries a dev toolchain"] | ||
| I --> D3["D3 · three PRs<br/>hook, then watch, then publish"] | ||
| D3 -.->|"rejected"| X3["one PR<br/>node, fsdev and a package move reviewed at once"] | ||
| ``` | ||
|
|
||
| Solid edges are what you're signing. Dashed edges lost, and the label says why. | ||
|
|
||
| <a name="d1"></a> | ||
| ## 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 `<meta>` 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` | | ||
|
|
||
|  | ||
|
|
||
| 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. | ||
|
|
||
| <a name="d2"></a> | ||
| ## 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 | | ||
|
|
||
|  | ||
|
|
||
| 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. | ||
|
|
||
| <a name="d3"></a> | ||
| ## 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"] | ||
| ``` | ||
|
|
||
|  | ||
|
|
||
| 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. | ||
| - **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.** | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 <path>` | `fsdev.config.*` in the current directory | The Lab's config. A relative path resolves from where you ran the command. | | ||
| > | `--port <n>` | `4300` | `0` picks a free port. | | ||
| > | `--host <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 <day\|night>` | `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 <dir>` | 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 <package\|dir>` | 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>` | 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 | ||
| > `<meta name="fsdev-devtool-url" content="…">`, 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<string, string>` of `<meta name content>` 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 | ||
|
jhoffner marked this conversation as resolved.
Resolved
|
||
| `--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. | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.