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
…hen it fails Both from Codex's review of 3118cce, folded into the rework in flight. P1 — the major-range pin did not hold the guarantee the spec makes. Codex is right: `create-next-app@16` re-resolves to the newest 16.x on every invocation, so a Next minor that moves a flag or the generated layout reaches users the day it ships, while §7 claimed upstream changes cannot reach them until we bump. The pin is now an exact release, the argv assertion rejects a range as well as a missing pin, and §9 gains the cost that makes this honest: create-next-app writes an exact `next` version into the manifest it generates, so pinning the scaffolder also pins the Next version new projects start on. Bumping it is scheduled maintenance behind a goal-check run, not a rare event. The probe is pinned exactly for the same reason — it is cited as evidence, so a reader running it later must get the version the findings were measured on. P2 — dropped by the stated contract, taken anyway, because the reasoning is right. The probe printed FAIL and exited 0, which is a check able to report green for a claim it did not prove — the failure BP-003 and tenet 7 name, and the same one the per-run marker and free-port check were added to close. The served-route and AGENTS.md checks are now assertions: exit 0 they held, 1 one failed, 2 could not be checked. Verified in both directions — a full run passes (`probe: PASS`, exit 0), and the verdict logic returns 1 for a stale marker, a non-200, an empty body, a missing FSD section, and a duplicated next block. 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 |
|---|---|---|
|
|
@@ -3,7 +3,7 @@ | |
| # | ||
| # bash probe.sh [workdir] | ||
| # | ||
| # Scaffolds a real create-next-app@16 project, then for each candidate shape of | ||
| # Scaffolds a real create-next-app@16.3.1 project, then for each candidate shape of | ||
| # the FSD config runs `next build` (the bundler + TypeScript half) and a native | ||
| # `import()` (the fsdev CLI half). Ends with a `next dev` + curl on the chosen | ||
| # shape, so the mounted route is proven to serve, not just to compile. | ||
|
|
@@ -15,7 +15,9 @@ APP="$WORK/probe" | |
| rm -rf "$APP" | ||
| echo "workdir: $WORK" | ||
|
|
||
| npx --yes create-next-app@16 "$APP" \ | ||
| # Exact, not @16 — a range would re-resolve and this script is cited as evidence, | ||
| # so a reader running it later must get the version the findings were measured on. | ||
| npx --yes create-next-app@16.3.1 "$APP" \ | ||
| --ts --app --no-tailwind --no-eslint --no-biome --no-src-dir \ | ||
| --no-react-compiler --no-rspack --import-alias "@/*" \ | ||
| --agents-md --skip-install --disable-git || exit 1 | ||
|
|
@@ -93,7 +95,7 @@ PORT=0 | |
| for p in $(seq 3990 3999); do | ||
| if ! (exec 3<>"/dev/tcp/127.0.0.1/$p") 2>/dev/null; then PORT=$p; break; fi | ||
| done | ||
| if [ "$PORT" = 0 ]; then echo " no free port in 3990-3999 — skipped"; exit 0; fi | ||
| if [ "$PORT" = 0 ]; then echo " no free port in 3990-3999 — CANNOT VERIFY"; exit 2; fi | ||
| echo " port $PORT (verified free)" | ||
|
|
||
| printf '\n<!-- BEGIN:fsd -->\nFSD SECTION SENTINEL\n<!-- END:fsd -->\n' >> AGENTS.md | ||
|
|
@@ -102,11 +104,22 @@ DEV_PID=$! | |
| sleep 18 | ||
| BODY=$(curl -s --max-time 20 --noproxy '*' "http://127.0.0.1:$PORT/api/flows") | ||
| echo " GET /api/flows -> $BODY" | ||
| RC=0 | ||
| case "$BODY" in | ||
| "$MARKER":200) echo " PASS — the route served this run's config module" ;; | ||
| *) echo " FAIL — expected $MARKER:200" ;; | ||
| *) echo " FAIL — expected $MARKER:200"; RC=1 ;; | ||
| esac | ||
| echo " FSD section survived next dev: $(grep -c 'FSD SECTION SENTINEL' AGENTS.md) (expect 1)" | ||
| echo " next's own block still there: $(grep -c 'BEGIN:nextjs-agent-rules' AGENTS.md) (expect 1)" | ||
| FSD_N=$(grep -c 'FSD SECTION SENTINEL' AGENTS.md) | ||
| NEXT_N=$(grep -c 'BEGIN:nextjs-agent-rules' AGENTS.md) | ||
|
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.
The new post- Useful? React with 👍 / 👎. |
||
| echo " FSD section survived next dev: $FSD_N (expect 1)" | ||
| echo " next's own block still there: $NEXT_N (expect 1)" | ||
| [ "$FSD_N" = 1 ] || { echo " FAIL — appended FSD section did not survive"; RC=1; } | ||
| [ "$NEXT_N" = 1 ] || { echo " FAIL — next's own block is not intact"; RC=1; } | ||
| kill "$DEV_PID" 2>/dev/null; wait "$DEV_PID" 2>/dev/null | ||
| exit 0 | ||
|
|
||
| # The exit status is the evidence. This script is cited by the spec and the PR as | ||
| # the thing a reader runs, so it must not be able to report green for a claim it | ||
| # did not prove: 0 = the served-route and AGENTS.md claims held, 1 = one failed, | ||
| # 2 = could not be checked at all. | ||
| [ "$RC" = 0 ] && echo " probe: PASS" || echo " probe: FAIL" | ||
| exit "$RC" | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -321,14 +321,21 @@ persists saved preferences between runs and silently fills unpassed options from | |
| we omit can resolve differently on a developer's machine than on ours. `--yes` is not a | ||
| substitute for passing them. | ||
|
|
||
| **The version is pinned in the spawned specifier, not left to `npx` to resolve.** The command is | ||
| `create-next-app@<tested major>`, held in one constant in this package and bumped as a deliberate | ||
| change with a goal-check run behind it — never a bare `create-next-app`, which resolves whatever | ||
| shipped that morning. The pin is what makes §9's flag-drift row a *loud* failure at our next | ||
| release rather than a silent one in a stranger's terminal, and the CI argv assertion (§10) reads | ||
| the pinned specifier so removing it fails a test. The pin cannot detect upstream drift on its own | ||
| — nothing stubbed can — so the goal check is the detector and the pin is what stops the detection | ||
| gap reaching users in between. | ||
| **The version is pinned to an exact release in the spawned specifier** — `create-next-app@16.3.1`, | ||
| not `@16` and not bare — held in one constant in this package and bumped as a deliberate change | ||
| with a goal-check run behind it. A major-range pin does not hold the guarantee: `@16` re-resolves | ||
| to the newest 16.x on every invocation, so a Next minor that moves a flag or the generated layout | ||
| reaches users the day it ships, which is exactly what the pin exists to prevent. The CI argv | ||
| assertion (§10) reads the pinned specifier, so both removing it and loosening it to a range fail | ||
| a test. The pin cannot *detect* upstream drift — nothing stubbed can — so the goal check is the | ||
| detector and the pin is what keeps the gap between drift and detection off users' machines. | ||
|
|
||
| **What the exact pin costs, stated plainly:** `create-next-app` writes an *exact* `next` version | ||
| into the manifest it generates, so pinning the scaffolder also pins the Next version new projects | ||
| start on. Bumping it is therefore **routine scheduled maintenance with a goal-check run**, not a | ||
| rare event — a starter a few months behind on Next is a real cost, and the alternative is a | ||
| starter that breaks without warning. §9's drift row is the same failure either way; the pin only | ||
| decides whose terminal it happens in. | ||
|
|
||
| **Step 3 — write the template.** Six files, materialized from `templates/nextjs-chat/`, plus one | ||
| manifest key. This is the entire product surface: | ||
|
|
@@ -416,7 +423,8 @@ package generates a project; it changes no framework behaviour. | |
| | Case | Expected | | ||
| |---|---| | ||
| | `create-next-app` fails, is unreachable, or rejects a flag | Report its output, name the directory as it stands, and print the two commands that finish the job by hand. Do not delete it. | | ||
|
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 create-next-app exits after partially populating the target, the promised two finishing commands cannot use this scaffolder because its non-empty-directory validation refuses the retained target, and Useful? React with 👍 / 👎. |
||
| | `create-next-app` changes its flag surface or generated layout | The pinned specifier (§7 step 2) means an upstream change does not reach users until we bump it, so this surfaces as a failing goal check on *our* release rather than as a hang in a stranger's terminal. Treated as a patch-level fix. Nothing stubbed can detect this — the goal check is the only detector. | | ||
| | `create-next-app` changes its flag surface or generated layout | The **exact** pinned version (§7 step 2) means an upstream change cannot reach users until we bump it, so this surfaces as a failing goal check on *our* release rather than as a hang in a stranger's terminal. A major-range pin would not hold that. Treated as a patch-level fix. Nothing stubbed can detect this — the goal check is the only detector. | | ||
| | The pinned `create-next-app` falls behind | New projects start on an older Next than current. Bumping the pin is scheduled maintenance gated on a goal-check run, not a reaction to breakage. | | ||
| | Init fails after the template was written | The scaffold stays. Print init's own retry command against that directory. Mirrors init's install-failure taxonomy, which also leaves files and prints the retry. | | ||
| | Install fails inside init | Init's case, not this one. It reports and this command adds nothing. | | ||
| | `-y` with no key in flags or environment | Scaffold completes. `.env.local` carries the empty key line init writes, and one line before the next-steps block says the key is still needed. Do not refuse — an unattended scaffold is legitimate. | | ||
|
|
@@ -468,8 +476,9 @@ init, in a temporary directory, with no network and no install, **except the thr | |
| symptom otherwise is a second flow file appearing beside the advertised one | ||
| - **the collected provider and key reach init** — asserted on the call, so a regression shows up | ||
| as a failing test rather than a second prompt in someone's terminal | ||
| - **`create-next-app` is invoked with install skipped, every flag explicit, and the pinned major | ||
| in the specifier** — asserted on the argv, since the symptoms otherwise are "the first hour is | ||
| - **`create-next-app` is invoked with install skipped, every flag explicit, and an *exact* pinned | ||
| version in the specifier** — asserted on the argv, and the assertion rejects a range as well as | ||
| 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) | ||
| - **every printed command runs** — execute the strings the block emitted, in the generated | ||
|
|
||
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 the optional workdir already contains a
probe/directory, this unconditional removal silently destroys that directory and all its contents before scaffolding. Sincebash probe.sh [workdir]does not document the argument as a disposable directory, create a unique child directory or refuse when$WORK/probealready exists.Useful? React with 👍 / 👎.