Repository navigation
spec(FIX-548): create-flow-state — one command to a working FSD app
#1312
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
base: main
Are you sure you want to change the base?
Changes from 1 commit
0a031eb
3118cce
c2579de
dbda62f
ecce07d
c67c063
a1c1553
4c2e396
836a305
eee403f
af5fd0d
c19b834
2ecd4fa
404e82c
48d2a52
a3fc694
3480183
30f6399
2aebb40
4a400d0
b0b5754
dce7a26
d34dfa9
a2dcb53
4552da7
64227dd
28c2d08
eb38dea
48cc886
071e3e9
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
…ects that shipped a broken app Epic theme 9: the install skill can never reach this template — a brownfield developer installs the plugin and nothing else, theme 4 forbids reading our monorepo, and the template ships inside the published scaffolder. So the template stops being the reference shape the skill points at. FIX-1159 authors a wiring contract and this template conforms to it: the Next.js mount pair, fsdev.config.ts's shape with its store profile, and the dependency set. Recorded as a CONSTRAINT, not a deliverable. Same six files, no new package, artifact or dependency, still the set's only deterministic writer. What moved is authorship of three shapes it was already writing. §2's drift tripwire is re-aimed (both sides cite the contract, rather than the skill citing the template), decision 3's justification shifts from "instructions can point at it" to "conformance can be checked against it", and the FIX-1159 edge is firmer than recorded: it was the library seam plus the printed next-steps block, neither of which touched this template's own files. Node floor. The CLI loads fsdev.config.ts through a native import(), and native type stripping arrives in 22.18 — load-config.ts names it in its runtime-floor note and in the remediation it prints. On 22.0–22.17 the scaffold SUCCEEDED and every printed fsdev command then failed to load the config: the headline outcome breaking silently on a range we advertise. Step 1 now refuses before creating anything. The reasoning is narrower than it looked, and is stated rather than the number alone: the POC settled the shape GIVEN a TypeScript config and never tested the .mjs escape the loader documents. What rules that escape out is a JS config losing type checking on the most error-prone file in the template, FIX-1159 decision 4, and theme 9 making the config's shape a contract — not the POC. The Created summary moves to the wrapper. §5 had init print it while §7's seam hands init no file list, so an implementer had to widen the seam or print a list init cannot verify. The wrapper wrote the files and knows them; this keeps the seam at decision 3's width and is what lets the epic's report-versus-diff check for this issue pass at all. §10 gains two behaviours: the Created summary compared against the actual diff in both directions, and the sub-22.18 refusal leaving the directory untouched. probe.sh is untouched — it stays frozen; this round is prose only. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
- Loading branch information
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -43,8 +43,11 @@ section, the dependency install, and the block of next steps that gets printed. | |
| this spec's previous draft, which had init generate the config and the host wiring while this | ||
| package supplied only demo content. That boundary existed to stop two deterministic writers | ||
| duplicating scaffolding logic; after the split there is one, so the line moved. What replaces it | ||
| is a **drift** tripwire: the template is the reference shape, checked in as real files, and the | ||
| install skill's instructions point at it rather than restating its contents. | ||
| is a **drift** tripwire, and epic theme 9 has since re-aimed it. The template is no longer the | ||
| reference shape the install skill points at — that skill ships in a plugin and can never reach a | ||
| template published inside this scaffolder. Instead **both conform to a wiring contract FIX-1159 | ||
| authors**, and the tripwire watches for either one restating the wiring instead of citing it. | ||
| This package still writes the shape; it no longer defines it. | ||
|
|
||
| **Philosophy** — tenet 2 (composition over features): the command's value is the ordering of | ||
| three things that already exist. Tenet 3 (earn every addition): §6 is mostly about keeping the | ||
|
|
@@ -90,9 +93,10 @@ file list short and refusing surface — including a `--template` flag with one | |
| twice.** | ||
| *Rejected:* the previous draft's split, where init generated `fsdev.config.*` and the Next | ||
| route pair and this package supplied only the demo flow and the page. | ||
| *Locks in:* the template is a directory a person can read, diff, and point instructions at, | ||
| which is what epic theme 1's drift tripwire needs — a shape assembled at runtime from | ||
| `create-next-app` output plus init's generator is not readable anywhere. It also means init's | ||
| *Locks in:* the template is a directory a person can read and diff, which is what checking it | ||
| against **FIX-1159's wiring contract** requires (epic theme 9) — a shape assembled at runtime | ||
| from `create-next-app` output plus init's generator is readable nowhere, so nothing could be | ||
| held to the contract at all. It also means init's | ||
| Next-host branch is no longer on this path (§12 raises that with FIX-1159 rather than | ||
| deciding it). The cost is that a config generator now exists in two places and can drift; | ||
| the epic accepted exactly that trade when it replaced "no two writers" with "watch for | ||
|
|
@@ -117,6 +121,28 @@ file list short and refusing surface — including a `--template` flag with one | |
| not run, and we add one key. Dependencies and the lockfile still belong entirely to the | ||
| package manager. Stated out loud because a reviewer should see the exception, not find it. | ||
|
|
||
| *Consequence — the generated app needs **Node 22.18+**, and step 1 refuses below it.* The CLI | ||
| loads a TypeScript config through a native `import()`, and native type stripping arrives in | ||
| **22.18** — `packages/cli/src/load-config.ts` says so in its runtime-floor note and in the | ||
| remediation text it prints. Below that the scaffold would finish, print its next steps, and | ||
| then **every printed `fsdev` command would fail to load `fsdev.config.ts`**: the epic's | ||
| headline outcome breaking silently, on a Node range we advertise as supported. So the check | ||
| belongs in step 1's validation, refusing **before any directory is created**, with the floor | ||
| and the message init uses — not late, as a config-load error, after a project exists. | ||
|
|
||
| *What actually forces this, stated precisely, because the POC does not.* The POC settled the | ||
| config's shape **given that it is TypeScript**; it never tested a `.mjs` config, and the | ||
| loader documents `.mjs`/`.js` as a universal escape that would work across all of 22.x. That | ||
| escape is rejected on other grounds: a JavaScript config in an otherwise TypeScript template | ||
| drops type checking on the most error-prone file in it, contradicts FIX-1159 decision 4 | ||
| (TypeScript for the CLI half), and — after epic theme 9 — `fsdev.config.ts`'s shape belongs to | ||
| a contract FIX-1159 authors, not to something this template may reformat to widen a Node | ||
| range. 22.18 is old enough by now that requiring it costs approximately nobody. | ||
|
|
||
| *Not the package's `engines`.* This floor is what the **generated app** needs, checked against | ||
| the Node actually running the command. The scaffolder's own `engines` stays at the repo-wide | ||
| `>=22`; §9 records why narrowing that is a separate mistake. | ||
|
|
||
| 5. **The demo flow reaches whichever provider the developer has a key for, through an intent — | ||
| it never hard-codes one provider's model.** The config declares | ||
| `models: { default: <the chosen provider's model>, intents: { chat: [anthropic, openai, | ||
|
|
@@ -287,9 +313,21 @@ $ npm create flow-state my-app | |
| AGENTS.md tells your coding assistant how to write FSD flows. | ||
| ``` | ||
|
|
||
| Everything from `Created` down is **init's output, printed by init** (epic theme 5). The three | ||
| lines above it are this package's. Two details in the block are load-bearing rather than | ||
| cosmetic: `npm exec` needs the `--` separator or npm consumes `--input` as its own configuration | ||
| **Who prints what.** The `Created` block is **this package's**, along with the three lines above | ||
| it. Everything from `Wrote` down is **init's output, printed by init** (epic theme 5) — that is | ||
| where the byte-identical-to-a-standalone-run guarantee applies, and the next-steps block is the | ||
| part theme 5 actually binds. | ||
|
|
||
| *This corrects an earlier draft that put `Created` on init's side of the line.* It could not | ||
| hold: §7's step-4 table hands init broad declarations that config, flows and wiring exist and | ||
| **never a file list**, so init cannot name six files it did not author and was not told about. | ||
| The two ways out were widening the seam — giving back the narrowness decision 3 bought — or | ||
| printing a summary nobody can know is correct. Neither is needed, because the wrapper wrote those | ||
| files and knows exactly what they are. It also matters more than a formatting nit: the epic's | ||
| goal check for this issue **compares the run's report against the actual diff**, so a summary | ||
| that cannot name what was written is a check that cannot pass. | ||
|
|
||
| Two details in the block are load-bearing rather than cosmetic: `npm exec` needs the `--` separator or npm consumes `--input` as its own configuration | ||
| and the command fails, and the two-process caveat is real because both printed servers open the | ||
| same development store. §10 asserts the first by running it. | ||
|
|
||
|
|
@@ -396,6 +434,11 @@ are exhaustive, which is what keeps the citation and the evidence one-to-one. | |
| | the package manager | one manager, one lockfile | | ||
| | **returned:** the next-steps block | printed once, by init, byte-identical to a standalone init run (epic theme 5) | | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Brittle contract: "byte-identical" next-steps (also §10) couples create-fsd-app CI to init wording. Any init copy tweak breaks wrapper tests though behaviour is fine. Consider asserting same commands/URLs in order (normalized whitespace) or owning the snapshot in init's test suite only. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
On every successful scaffold, the transcript requires init to print a Useful? React with 👍 / 👎. |
||
|
|
||
| **Not** crossing the seam: the list of template files. This package prints its own `Created` | ||
| summary (§5) because it is the only side that knows what it wrote — init receives declarations, | ||
| not filenames. Keeping it out is what holds the seam at the width decision 3 chose, and it is | ||
| what lets the run's report be compared against the actual diff (§10). | ||
|
|
||
| **Ordering, and why it is not incidental.** The template is written *before* init runs, so init | ||
| sees a fully declared shape and authors nothing that competes. `create-next-app` must skip its | ||
| install, or the project installs twice and the second run rewrites the lockfile the first wrote. | ||
|
|
@@ -439,7 +482,7 @@ package generates a project; it changes no framework behaviour. | |
| |---|---| | ||
| | Target directory exists and is not empty | Refuse, naming the path. | | ||
| | Project name is not a valid npm package name | Refuse, saying which rule failed, and offer the sanitized form. | | ||
| | Node runtime below the floor the generated project needs | Refuse, with the same floor and the same message init uses. Do **not** narrow the package's `engines` below the repo-wide `>=22` — FIX-1159 §9 records why. | | ||
| | Node runtime below the floor the generated project needs | Refuse in step 1, before anything is created, with the same floor and the same message init uses. The floor is **22.18** — native type stripping, without which every printed `fsdev` command fails to load `fsdev.config.ts` (decision 4). Do **not** narrow the package's `engines` below the repo-wide `>=22` — that is the scaffolder's own runtime, a different question; FIX-1159 §9 records why. | | ||
|
|
||
| **The credential stop — after the scaffold exists, before the key is written.** Its own | ||
| category, because it is neither of the other two and putting it in either produced a | ||
|
|
@@ -533,6 +576,14 @@ init, in a temporary directory, with no network and no install, **except the thr | |
| a missing pin, since `@16` silently re-resolves. The symptoms otherwise are "the first hour is | ||
| slower", "it behaved differently on my machine", and a version nobody tested | ||
| - **the printed next-steps block is byte-identical to a standalone init run** (epic theme 5) | ||
| - **the `Created` summary names exactly the files the run wrote** — compare the reported list | ||
| against the actual diff of the generated directory, in both directions, so a file written but | ||
| not reported fails as loudly as one reported but not written. The epic's proof for this issue | ||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Fresh evidence beyond the earlier summary-ownership comment is this new bidirectional diff requirement: the six-file Useful? React with 👍 / 👎. |
||
| requires that comparison; it also pins the seam, since a summary that drifts from the diff is | ||
| the first sign the file list has crossed into init | ||
| - **the scaffold refuses on Node below 22.18, before creating anything** — assert the exit, the | ||
| message naming the floor, and an untouched target directory. Without it the failure moves to | ||
| every printed `fsdev` command, after a project exists (decision 4) | ||
| - **every printed command runs** — execute the strings the block emitted, in the generated | ||
| project, and assert the process starts. This is where npm's `--` separator is caught | ||
| - every refusal in §9's first block, each asserting nothing was created | ||
|
|
@@ -570,10 +621,27 @@ subprocesses stubbed. | |
|
|
||
| **Dependencies.** | ||
|
|
||
| - **FIX-1159 blocks implementation, not specification.** This package cannot be built until | ||
| init's library seam exists, and cannot merge before init merges. §7's step-4 table is the | ||
| required interface; it is **smaller than the previous draft's**, because decision 3 moved the | ||
| config and the mount here. | ||
| - **FIX-1159 blocks implementation, and now constrains part of this specification.** This package | ||
| cannot be built until init's library seam exists, and cannot merge before init merges. §7's | ||
| step-4 table is the required interface; it is **smaller than the previous draft's**, because | ||
| decision 3 moved the config and the mount here. | ||
|
|
||
| **The edge is firmer than this spec previously recorded it.** It used to be the library seam | ||
| plus the shared next-steps block — both about what crosses the seam at runtime and what gets | ||
| printed, neither about this template's own files. Epic theme 9 adds the **wiring contract**, | ||
| which does constrain them. Specification can still proceed in parallel, but not as far as | ||
| before: the shapes below are conformance targets, not local calls. | ||
| - **This template conforms to FIX-1159's wiring contract (epic theme 9).** The contract is the | ||
| part both entry paths share, and it covers exactly three things: **the Next.js mount pair** | ||
| (`app/api/flows/route.ts` + `app/api/flows/[...path]/route.ts`), **`fsdev.config.ts`'s shape** | ||
| including its required store profile, and **the dependency set**. This package writes them; | ||
| FIX-1159 specifies them. Everything else in §7 — the demo flow, the chat page, the | ||
| agent-instructions section, the manifest edit — is this issue's own and is outside the | ||
| contract. Recorded so an implementer conforms rather than inventing the mount shape a second | ||
| time; the check is theme 8's parity requirement, that this template and the brownfield Next | ||
| path deliver the same mounted-route shape. **No new artifact, package or dependency comes with | ||
| this**: the contract travels as skill content on the path skill content already takes | ||
| (FIX-1159 authors → FIX-1160 packages → the plugin ships). | ||
| - **Publishing the unscoped `create-flow-state` is a hard prerequisite** (decision 1). Not a | ||
| naming preference: without it the headline command resolves to nothing, and there is no | ||
| in-scope workaround, because a scoped publish cannot serve `npm create flow-state`. What is | ||
|
|
@@ -794,6 +862,31 @@ Spec-PR feedback recorded rather than folded. These are inputs, not instructions | |
| PR that never merges, so any later finding is answered by narrowing a README claim to what the | ||
| frozen script proves. The reasoning is on the POC README rather than just the rule: a probe | ||
| that keeps earning rounds is one asserting more than its job requires. | ||
| - **Epic theme 9 lands as a constraint, not a deliverable.** The install skill can never reach | ||
| this template — a brownfield developer installs the plugin and nothing else — so the template | ||
| stopped being the reference shape the skill points at. **FIX-1159 now authors a wiring | ||
| contract and this template conforms to it**, covering the Next.js mount pair, | ||
| `fsdev.config.ts`'s shape with its store profile, and the dependency set. Nothing is added or | ||
| removed: the same six files, no new package, artifact or dependency, and this package remains | ||
| the set's only deterministic writer. What moved is authorship of three shapes it was already | ||
| writing — it is the contract's consumer, not its source. §2's drift tripwire is re-aimed (both | ||
| sides now cite the contract instead of the skill citing the template), decision 3's | ||
| justification shifts from "instructions can point at it" to "conformance can be checked | ||
| against it", and the FIX-1159 edge is recorded as firmer: it used to be the library seam and | ||
| the printed next-steps block, neither of which touched this template's own files. | ||
| - **Two defects that would have shipped a broken app.** The generated project needs **Node | ||
| 22.18+** — the native type-stripping floor `packages/cli/src/load-config.ts` names twice — | ||
| because the CLI loads `fsdev.config.ts` through a native `import()`. Below it the scaffold | ||
| *succeeded* and every printed `fsdev` command then failed, which is the headline outcome | ||
| breaking silently on a range we advertise. Step 1 now refuses before creating anything. The | ||
| reasoning is recorded rather than just the number, and it is narrower than it first looked: | ||
| the POC settled the shape *given a TypeScript config* and never tested the `.mjs` escape the | ||
| loader documents, so what rules that escape out is a JS config losing type checking on the | ||
| most error-prone file, FIX-1159 decision 4, and theme 9 making the config's shape a contract — | ||
| not the POC. Separately, §5 had **init** print the `Created` summary while §7's seam hands it | ||
| no file list, so an implementer had to widen the seam or print a list init cannot verify. The | ||
| summary moves to the wrapper, which wrote the files; that keeps the seam at decision 3's width | ||
| and is what lets the epic's report-versus-diff check pass at all. | ||
| - **§12 overstated the npm mechanism, and it is corrected.** The spec said `npm create <name>` | ||
| *and* a bare `fsdev` on the path both need unscoped names. Only the first is true. A command | ||
| name comes from the package's `bin` key, so `@flow-state-dev/cli` — already declaring | ||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
When a project is scaffolded on Node 22.18+ and later cloned or deployed on Node 22.0–22.17, the one-time scaffolder check no longer runs, the FSD packages'
>=22engines still admit that runtime, and the printed CLI commands fail to importfsdev.config.ts. The current revision addresses the earlier runtime-floor issue only during creation; keep the scaffolder's own engine range unchanged, but addnode >=22.18to the generated app's manifest so its stated requirement travels with the project.Useful? React with 👍 / 👎.