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
…with a per-package map, assert the written manifest Five findings on eb38dea, three of them defects in the pinning fix from the previous round. Leaving zod floating aimed the risk at a specific type boundary: core depends on zod ^3.25.76 and types its public block surface as v3 ZodTypeAny, so a bare zod resolving to v4 fails next build on a type error before any model call. Pinned to a compatible v3 range; whether core should accept v4 is raised as a separate framework question. One version placeholder cannot version six independently released packages — changeset config declares fixed:[] and linked:[]. Replaced with a per-package version map. A fixed release group would collapse it to one entry; that is FIX-1162's work and is a note, not a dependency, since the map is correct either way. add pkg@1.2.3 does not persist 1.2.3: npm defaults to save-prefix=^ and pnpm needs -E. The exact flag is specified and §10 now asserts the written manifest rather than the argv, which also catches a changed default and a lockfile refresh. §9's deployment row still mandated the withdrawn production refusal — the third surface for that withdrawal and the fourth table row across all of them. §13's note now names tables and matrices specifically, since a row states a claim in a section organised by a different question and a phrase search never finds it. probe.sh cleared NODE_NO_WARNINGS/NODE_OPTIONS for the import check: inherited suppression made a true claim about Node report as disproved. Second application of the standing unfreeze clause, applied without re-arguing it. 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 |
|---|---|---|
|
|
@@ -181,6 +181,13 @@ variant() { | |
| # MODULE_TYPELESS_PACKAGE_JSON asynchronously, and an immediate exit() cuts it | ||
| # off before it reaches stderr, which made this probe report "clean" for the | ||
| # variant whose whole point is that it warns. | ||
| # Node's warning suppression is inherited from the environment, and this check | ||
| # reads stderr to decide whether a documented warning appeared. With | ||
| # NODE_NO_WARNINGS=1 or --no-warnings in NODE_OPTIONS, the no-`type`-field | ||
| # variant emits nothing, classifies as `clean`, and the probe reports a TRUE | ||
| # claim about Node as DISPROVED — the same false-disproof direction as the | ||
| # `git init` case, from a different cause. Cleared for this invocation only. | ||
| NODE_NO_WARNINGS= NODE_OPTIONS= \ | ||
| node -e "import('./$cfg').then(m=>{ | ||
|
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. When this probe runs on Node 22.0–22.17, the native imports cannot satisfy the expected clean TypeScript-import result because Useful? React with 👍 / 👎. |
||
| if(m.default.marker!=='config-module-loaded'){console.error('WRONG MODULE');process.exitCode=3} | ||
| }).catch(e=>{console.error('IMPORT THREW: '+e.message);process.exitCode=3})" > import.log 2>&1 | ||
|
Comment on lines
+191
to
+193
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.
When the caller has Useful? React with 👍 / 👎. |
||
|
|
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -881,38 +881,62 @@ have caught it — the pnpm-isolated install — was itself specified against a | |
| **A requirement recorded in one section and enforced by no step is not a requirement**, which is | ||
| the same shape as the FIX-1160 edge two rounds earlier. | ||
|
|
||
| **The FSD packages in that argument set carry an exact version; the others do not.** `npm install | ||
| @flow-state-dev/core@<v> @flow-state-dev/engine@<v> …` — one version string, held in the same | ||
| constant file as the `create-next-app` pin and bumped with it as scheduled maintenance behind a | ||
| goal-check run. `zod` and the `@ai-sdk/*` package keep their bare names. | ||
|
|
||
| *Why this is a decision and not a detail.* `.changeset/config.json` declares **`"fixed": []` and | ||
| `"linked": []`**, so every FSD package versions independently, and pre-1.0 a `minor` is a breaking | ||
| change by convention. Bare names resolve whatever `latest` is at the moment a stranger runs the | ||
| command — **not what the checked-in template was tested against** — so `create-flow-state@1.2.0` | ||
| could scaffold a project pulling `engine` and `core` from different release trains that were never | ||
| built together. **The asymmetry is what makes it worse than an ordinary risk**: this spec pins | ||
| `create-next-app` to an exact release and argues at length that a range would let upstream drift | ||
| reach users, which makes the generated project *look* reproducible while its FSD half is not | ||
| pinned at all. The same argument applies to our own packages with more force, since we ship the | ||
| breaking changes. | ||
| **Every package in that argument set carries an exact version, and the versions come from a | ||
| per-package map rather than one string.** The scaffolder holds a **version map** — one entry per | ||
| package, beside the `create-next-app` pin — and step 6 renders it into the `add` arguments: | ||
|
|
||
| ``` | ||
| npm install --save-exact \ | ||
| @flow-state-dev/core@<core> @flow-state-dev/engine@<engine> \ | ||
| @flow-state-dev/next@<next> @flow-state-dev/react@<react> \ | ||
| @flow-state-dev/cli@<cli> @flow-state-dev/devtool@<devtool> \ | ||
| @ai-sdk/openai@<sdk> zod@<zod> | ||
|
Comment on lines
+888
to
+893
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.
When a generated app is packaged for production, this ordinary Useful? React with 👍 / 👎. |
||
| ``` | ||
|
|
||
| **One placeholder cannot version six independently released packages**, and an earlier revision of | ||
| this paragraph used one. `.changeset/config.json` declares **`"fixed": []` and `"linked": []`**, so | ||
| `core`, `engine`, `next`, `react`, `cli` and `devtool` each move on their own — after any release | ||
| where two of them differ, a single `<v>` requests a version that is wrong for one and very likely | ||
| does not exist for another, and the scaffolder fails on its own install. *The map is not a | ||
| workaround for the missing release group; it is what independent versioning requires.* **A `fixed` | ||
| group would collapse it to one entry, and that is FIX-1162's release work — §12 carries it as a | ||
| cross-issue note and this spec does not depend on it**, because the map is correct either way. | ||
|
|
||
| **`zod` is pinned to a Zod 3 range compatible with `@flow-state-dev/core`, and this is the entry | ||
| that breaks a build if it floats.** `packages/core/package.json` depends on `zod: ^3.25.76`, and | ||
| core's public block surface types schemas as v3 `ZodTypeAny` — `packages/core/src/types/block.ts` | ||
| imports it for `stateSchema` and the connector targets, and `types/agent.ts` for `outputSchema`. | ||
| The generated flow imports `z` directly and hands its `z.object(...)` to those APIs. **A bare `zod` | ||
| resolves to Zod 4, whose schema types are not assignable to v3 `ZodTypeAny`, so the generated Next | ||
| project fails `next build` on a type error before it ever reaches a model.** An earlier revision | ||
| left `zod` deliberately floating while pinning the FSD packages, which did not leave the risk | ||
| general — it aimed it precisely at the one type boundary the generated flow crosses on every run. | ||
|
|
||
| *Whether core's schema boundary should accept Zod 4 is a real question and it is not this | ||
| spec's.* Raised as a separate issue rather than carried here: this template must work against the | ||
| framework as it ships, and pinning v3 costs nothing if the boundary later widens. | ||
|
|
||
| **The exactness is asserted on the written manifest, not on the flag.** `npm install pkg@1.2.3` | ||
| does **not** persist `1.2.3` — npm defaults to `save-exact=false` with `save-prefix=^`, so it | ||
| writes `^1.2.3`; pnpm behaves the same without `-E`. So the `add` command carries the | ||
| manager-appropriate exact flag (`--save-exact` / `-E`), **and §10 asserts the outcome**: every FSD | ||
| entry and `zod` in the generated `package.json` is a literal version with no range operator. | ||
| Checking the manifest rather than the argv is deliberate — it catches a wrong flag, a manager whose | ||
| default changes, and a later lockfile refresh that re-resolves a caret, none of which an argv | ||
| assertion sees. *Without this the spec's pinning guarantee would be prose: the argument would say | ||
| `1.2.3` and the manifest would say `^1.2.3`, and the drift the pin exists to prevent would arrive | ||
| on the developer's next install.* | ||
|
|
||
| *Why exact rather than a range.* A caret on `0.x` allows only patches, which sounds sufficient — | ||
| but the release train is pre-1.0 precisely because minors still break, and a range re-resolves on | ||
| every invocation, which is the property §7 already rejected for the scaffolder. | ||
|
|
||
| *What it costs, and it is the same cost already accepted once:* bumping the pin is routine | ||
| *What it costs, and it is the same cost already accepted once:* bumping the map is routine | ||
| maintenance rather than a rare event, and a starter a few months behind on FSD is a real cost. The | ||
| alternative is a starter that breaks without warning, on someone else's machine, in the first five | ||
| minutes. §9's drift row is the same failure either way. | ||
|
|
||
| *Not decided here — raised with FIX-1162.* If the release process adopts a **`fixed` group** for | ||
| `@flow-state-dev/*`, every package moves in lockstep and this pin collapses from N version strings | ||
| to one, with the changeset release itself keeping them consistent. That is a repo-wide release | ||
| decision that belongs to whoever owns publishing, not to this template; §12 carries it as a | ||
| cross-issue note rather than a dependency, because the exact pin above works under either answer. | ||
|
|
||
| **Why `add` rather than authoring the entries in step 3.** Decision 4 bends the "package manager | ||
| *Why `add` rather than authoring the entries in step 3.** Decision 4 bends the "package manager | ||
| owns `package.json`" rule for exactly one key and says so; widening that to the whole dependency | ||
| block would mean this package authoring and maintaining a version range for every entry, which is | ||
| a second place for the corpus's versions to drift and the thing that rule exists to prevent. | ||
|
|
@@ -1099,7 +1123,7 @@ elsewhere: the directory is seconds old and contains nothing the developer autho | |
| | `-y` with no key in the environment | Scaffold completes. `.env.local` carries the empty variable line, and one line before the next-steps block says the key is still needed. Do not refuse — an unattended scaffold is legitimate. **There is no key flag** (§5), so `-y` and an unset variable is the only way to reach this state, and it is CI's path rather than the goal check's. | | ||
| | The developer runs `npm run dev` and `fsdev dev` together | Both open the same development file store; concurrent writes to one session can each be accepted. Tolerable for a development default, and the next-steps block says to drive one at a time (§12 raises the wording with FIX-1159, which authors the block). | | ||
| | The developer wants to reach the app from another device | `npm run dev` binds `127.0.0.1` (decision 8), so it will not connect. This is the intended behaviour, not a bug: the flow is unauthenticated and the bind is the only control. The fix is theirs to make — remove `--hostname 127.0.0.1` from `scripts.dev`, a one-word edit in a file we wrote seconds ago — and they should understand what they are removing. | | ||
| | The developer deploys the generated app as-is | The mounted route **refuses before any model invocation**, with an error naming the missing authentication (decision 8). Not a warning, and not a 200 with an error body. | | ||
| | The developer deploys the generated app as-is | **Nothing of ours stops them, and nothing of ours refuses the request.** `scripts.start` is unmodified so the app binds wherever Next binds, and the demo flow is on the framework default resolver, so the deployed endpoint runs model calls for any caller, billed to the developer's provider key (§12). This is the state epic **§5 Q7** is deciding; decision 8 withdrew the production refusal an earlier revision of this row mandated. **Do not implement one before Q7 answers** — the epic's rule is explicit and this row is where an implementer would otherwise pick it up. | | ||
|
|
||
| **Taxonomy — three categories, and the middle one exists because the first two could not hold | ||
| it.** Refusals happen before anything is created and leave the disk untouched. The credential | ||
|
|
@@ -1288,6 +1312,17 @@ my-app` is the advertised UX; the pnpm run beside it is what makes that one safe | |
| - **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 pinned entry in the generated `package.json` is a literal version, with no range | ||
| operator** — asserted on the **written manifest**, not on the `add` argv. `npm install pkg@1.2.3` | ||
| persists `^1.2.3` unless `--save-exact` is passed, and pnpm behaves the same without `-E`, so an | ||
| argv assertion passes while the manifest drifts on the developer's next install. Checking the | ||
| outcome also catches a manager whose default changes and a lockfile refresh that re-resolves a | ||
| caret. **Assert `zod` specifically**: it is the entry whose drift is a build break rather than a | ||
| version skew (§7) | ||
| - **the version map has an entry per package, and the emitted `add` uses it** — assert that the six | ||
| `@flow-state-dev/*` arguments do not all carry the same version string when the map says they | ||
| differ. The failure this guards is a single placeholder rendered into six independently released | ||
| packages, which requests a nonexistent version and fails the scaffolder's own install | ||
| - **the dependency set is actually written, not merely listed** — assert the `add` argv contains | ||
| every derived member, and that the generated `package.json` carries those entries afterwards. | ||
| **A spec-level list with no step behind it is what this assertion exists to catch**: the previous | ||
|
|
@@ -1697,12 +1732,21 @@ enforced by no other*: | |
| stop being made **everywhere it appears**, and the surfaces that restate it are exactly the ones | ||
| nobody re-reads. | ||
|
|
||
| | round | what was withdrawn | where it survived | | ||
| |---|---|---| | ||
| | `scripts.start` narrowing | epic theme 6 exception (c) dropped `start` | this spec's decision 8, change table, §8, §10 — for a full round | | ||
| | the production refusal | decision 8, after the rail was measured | the flow-file description, step 3, a §12 premise, a follow-up | | ||
| | the same refusal again | decision 8 | **the generated success transcript**, which promises it to the user | | ||
| | the §12 description | — | decision 8 pointed at a §12 that did not contain it | | ||
| | round | what was withdrawn | where it survived | kind of surface | | ||
| |---|---|---|---| | ||
| | `scripts.start` narrowing | epic theme 6 exception (c) dropped `start` | decision 8, the **change table**, §8, §10 | table row | | ||
| | the production refusal | decision 8, after the rail was measured | the **file table** row, step 3, a §12 premise, a follow-up | table row | | ||
| | the same refusal again | decision 8 | **the generated success transcript** | printed output | | ||
| | the §12 description | — | decision 8 pointed at a §12 that did not contain it | cross-reference | | ||
| | the same refusal, a third time | decision 8 | **§9's deployment row**, still mandating it | table row | | ||
|
|
||
| **Look at the last column: four of the five were a row, not a sentence.** That is not a | ||
| coincidence and it is the most actionable thing in this note. Prose restates a claim in language a | ||
| reader recognises as a restatement; **a table row states it as a fact, in a compressed form, in a | ||
| section organised by a different question** — §9 is organised by *failure case*, §7's file table by | ||
| *file*, neither by *which control ships*. So a `Ctrl-F` for the withdrawn wording misses them, | ||
| because the row never used that wording. **When you withdraw a claim, walk every table and matrix | ||
| whose rows could assert it, by reading the rows — not by searching for the phrase.** | ||
|
|
||
| **So the rule is one rule with two directions.** *Additions:* name the artifact that will execute | ||
| the requirement — a step, a test, a manifest entry, a tracker edge — not merely the paragraph | ||
|
|
@@ -2085,3 +2129,39 @@ The same discipline applies to the checks: §10 collects three directions this h | |
| while its FSD half was not pinned at all. Raised with **FIX-1162** rather than decided alone: a | ||
| `fixed` release group would collapse the pin from N version strings to one, and the exact pin works | ||
| under either answer. | ||
|
|
||
| - **The pinning fix had three defects of its own, one of them a build break.** *(1)* It pinned the | ||
| FSD packages and **deliberately left `zod` floating** — which did not leave the risk general, it | ||
| aimed it at the one type boundary the generated flow crosses on every run. `packages/core` depends | ||
| on `zod ^3.25.76` and types its public block surface as v3 `ZodTypeAny` (`types/block.ts` for | ||
| `stateSchema` and connector targets, `types/agent.ts` for `outputSchema`), while a bare `zod` | ||
| resolves to Zod 4, whose schemas are not assignable to it — **so the generated project fails | ||
| `next build` on a type error before reaching a model.** `zod` is now pinned to a compatible v3 | ||
| range; whether core's boundary should accept v4 is a framework question raised separately rather | ||
| than carried here. *(2)* It used **one version placeholder for six independently released | ||
| packages**, which `.changeset/config.json` (`"fixed": []`, `"linked": []`) makes impossible — | ||
| after any release where two differ, the single string requests a version that is wrong for one and | ||
| nonexistent for another. Replaced with a **per-package version map**; a `fixed` release group would | ||
| collapse it to one entry, which is FIX-1162's work and a note rather than a dependency, since the | ||
| map is correct either way. *(3)* It assumed `add pkg@1.2.3` persists `1.2.3`. **It does not** — npm | ||
| defaults to `save-prefix=^` and pnpm needs `-E` — so the guarantee was prose while the manifest | ||
| said `^1.2.3`. The exact flag is now specified **and §10 asserts the written manifest**, which is | ||
| the stronger check: it catches a wrong flag, a changed default, and a later lockfile refresh, none | ||
| of which an argv assertion sees. | ||
| - **§13's note is sharpened to name tables, because the data says the surface matters.** Four of | ||
| the five withdrawal residuals were a **table row**, not a sentence — including §9's deployment row, | ||
| which still instructed an implementer to build the production refusal decision 8 had withdrawn, | ||
| three surfaces after the withdrawal. Prose restates a claim in language a reader recognises as a | ||
| restatement; **a row states it as a fact, compressed, in a section organised by a different | ||
| question** — §9 by failure case, §7's file table by file, neither by which control ships — so a | ||
| search for the withdrawn wording never finds it. The rule now says to walk every table and matrix | ||
| by **reading the rows**, not by searching for the phrase. | ||
| - **The POC's unfreeze clause fired a second time, and was applied without re-arguing it.** The | ||
| native `import()` check reads stderr to decide whether Node's documented | ||
| `MODULE_TYPELESS_PACKAGE_JSON` warning appeared, and warning suppression is inherited: under | ||
| `NODE_NO_WARNINGS=1` or `--no-warnings`, the no-`type`-field variant emits nothing, classifies as | ||
| `clean`, and the probe reports a **true claim as disproved**. Same direction as the `git init` | ||
| case, different cause, so the standing clause decided it. Two instances are enough to state the | ||
| shape the README now carries: **this probe reads its evidence from process output, and process | ||
| output is environment-dependent** — any check deciding a claim from stdout/stderr clears what | ||
| suppresses the signal it reads, or classifies the environment as cannot-verify. | ||
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.
Fresh evidence after the earlier warning-suppression fix is Node’s separate
NODE_REDIRECT_WARNINGSenvironment variable, which this invocation still inherits.node --helpdescribes the corresponding option as “write warnings to file instead of stderr”; with this variable set, the expectedMODULE_TYPELESS_PACKAGE_JSONwarning goes to that file,import.logremains empty, and the no-type-field variant is misclassified asclean, causing exit 1 for a true claim. ClearNODE_REDIRECT_WARNINGSas well or classify that environment as cannot-verify.Useful? React with 👍 / 👎.