Repository navigation
fix(fsdev): IPv6 dev URLs and leading-dash script names (FIX-1159) - #1358
Conversation
Two findings on the merged next-steps block. Neither is a port-range choice,
so neither is the "report a fourth port" case.
IPV6 PORT PARSING. `/:(\d+)/` finds the first colon-digits anywhere in the
string, which in `http://[::1]:4210` is the `1` inside the address. So the
collision guard compared 1 against the reserved range, never matched, and
printed `--port 4210` into a host that already owns it — the guard
reintroducing the exact failure it was added to prevent.
Worth saying plainly: this is a bug in the code I added last round to fix the
previous port finding. The hand-rolled authority parsing was mine, and it was
the wrong instrument for a job `new URL` already does correctly. Now parsed
with `new URL`, with an unparseable value claiming no port rather than
guessing at one.
LEADING-DASH SCRIPT NAMES. A script named `--help` is read by every package
manager as its own option: `npm run --help` prints npm's help, exits 0, and
never runs the script. SHELL QUOTING DOES NOT REACH THIS — `npm run '--help'`
does the same thing, because the shell hands `--help` to npm intact and npm's
option parser takes it before the script name is looked up. That is why it
survived the quoting fix.
Both offered remedies were measured:
<manager> run --help npm/pnpm/yarn all print their own help
<manager> run -- --help all three run the script
<manager> run -- dev works, AND Yarn warns:
"scripts don't require "--" for options to be forwarded. In a future
version, any explicit "--" will be forwarded as-is"
The separator works everywhere, but Yarn prints that deprecation warning on
EVERY invocation — including ordinary script names. Emitting it always would
make every Yarn user read a warning forever to accommodate a script name
essentially nobody has, and it is deprecated in the direction that breaks us.
So the block refuses a leading-dash name instead, the same way it already
refuses an unfilled placeholder: the caller gets an error rather than the
developer getting a command that silently does nothing.
The fixture now carries a `--help` script, and the test executes both forms
so the refusal rests on measurement rather than on the claim that it is
warranted.
Both demonstrated red by reverting each fix:
x reads the host's port out of an IPv6 dev URL
-> expected ... to contain 'fsdev dev --port 4211' (it printed 4210)
x refuses a dev script the package manager would read as its own option
-> expected [Function] to throw an error
238 tests pass.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
|
The latest updates on your projects. Learn more about Vercel for GitHub. 3 Skipped Deployments
|
Bugbot couldn't run - usage limit reachedBugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit. A user or team admin can review and increase usage limits in the Cursor dashboard. (requestId: serverGenReqId_dd7f5eb3-e9f0-4ce5-be77-3e488810503c) |
| text = text.replace(sectionPattern(key), () => kept); | ||
| } | ||
|
|
||
| if (options.devScript !== undefined) assertRunnableScriptName(options.devScript); |
There was a problem hiding this comment.
Unused script validation blocks rendering
When second-process is rendered with a leading-dash devScript, the unconditional validation throws even though this topology never emits the script, causing an otherwise valid next-steps render to fail.
| if (options.devScript !== undefined) assertRunnableScriptName(options.devScript); | |
| if (options.topology === "mounted-route" && options.devScript !== undefined) { | |
| assertRunnableScriptName(options.devScript); | |
| } |
There was a problem hiding this comment.
Simplify review
Two small, correct follow-ups to the next-steps block shipped in #1352. Neither fix overreaches relative to the problem.
IPv6 port parsing (hostPortOf). Replacing /:(\d+)/ with new URL() is the right minimal fix — same pattern used elsewhere in the repo, no third-party URL parser warranted on Node 22, and returning null on unparseable input (rather than guessing) is the conservative choice the collision guard needs.
Leading-dash script names (assertRunnableScriptName). Refusing rather than printing a dud command matches how the block already treats values it cannot fill correctly. The measured rejection of always emitting run -- (Yarn deprecation on ordinary names) is sound. A conditional runSep mirroring existing {{execSep}} would also work and only warn Yarn on the rare dash-prefixed case — but it would touch the canonical template and both shipper embeds; for a script name that essentially never occurs, throw-at-render is the smaller diff and I would keep it.
Did this go too far? No major concerns. The integration probe for dash scripts (~600ms/manager when available) is consistent with this file's "measured, not assumed" philosophy from #1352; I would not strip it. Comment volume matches the parent module — not new complexity, just the same voice.
Non-blocking nits (inline where they apply):
- Hoist
hostPortOf(devUrl)before thefilter— today it parses the same URL up to 10× per render. - Strengthen the unparseable-URL test to assert default ports, not just
not.toThrow(). - Optionally scope the dash guard to
mounted-routeonly (second-processnever renders{{devScript}}).
Tests verified locally: packages/cli 238/238 pass, next-steps file ~8.3s.
Verdict: Approve. The approach is cleaner than the regex it replaces, and the refusal trade-off is better than taxing every Yarn user.
Sent by Cursor Automation: Review For Best Approach
| function allocatePorts(devUrl: string | undefined): { devPort: string; servePort: string } { | ||
| const hostPort = devUrl === undefined ? null : Number(/:(\d+)/.exec(devUrl)?.[1] ?? Number.NaN); | ||
| const free = reservedRange().filter((port) => port !== hostPort); | ||
| const free = reservedRange().filter((port) => port !== hostPortOf(devUrl)); |
There was a problem hiding this comment.
Micro-optimization: hostPortOf(devUrl) runs inside the filter, so new URL(devUrl) can execute up to 10× with the same input. Hoisting one parse before the filter would be a one-liner and keeps the helper honest about being cheap.
| text = text.replace(sectionPattern(key), () => kept); | ||
| } | ||
|
|
||
| if (options.devScript !== undefined) assertRunnableScriptName(options.devScript); |
There was a problem hiding this comment.
Optional scope tighten: this throws even for second-process, where {{devScript}} is never rendered. Harmless if callers never pass devScript for that topology, but moving the guard after topology selection (or gating on options.topology === "mounted-route") would match what the block actually prints.
|
|
||
| it("does not crash on a dev URL it cannot parse", () => { | ||
| expect(() => | ||
| renderNextSteps({ ...MOUNTED, devUrl: "not a url at all", packageManager: "pnpm" }), |
There was a problem hiding this comment.
This test only asserts not.toThrow(). Worth also asserting the default ports stay 4210/4211 — that is the behavior the null-on-unparseable path is meant to preserve, and it would catch a regression where we silently shift ports on garbage input.
second-look: PR #1358Verdict: Appropriately scoped — a tight, measured fix; no trimmable bloat found.
No line-level or architecture concerns either — the two functions this PR adds follow the module's existing convention (measure real manager behavior, document the trade-off inline, keep the fix as small as the bug), so there's no refactor opportunity scoped to what this PR touches. Considered & deemed justified
Automated Generated by Claude Code |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 0884ae80cc
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| text = text.replace(sectionPattern(key), () => kept); | ||
| } | ||
|
|
||
| if (options.devScript !== undefined) assertRunnableScriptName(options.devScript); |
There was a problem hiding this comment.
Validate the script only for the mounted branch
When a caller passes a shared detection object with topology: "second-process" and a leading-dash devScript, this unconditional assertion throws even though branch selection has already removed the only command that uses that value. The function's contract says the second-process branch does not need devScript, so validate it only for the mounted-route branch or only when its placeholder survives.
Useful? React with 👍 / 👎.
| "@flow-state-dev/fsdev": patch | ||
| --- | ||
|
|
||
| Two fixes to the next-steps block (FIX-1159). The port a project's own dev server uses is now read from the dev URL with a real URL parser, so an IPv6 address like `http://[::1]:4210` no longer has the digits inside the address mistaken for its port — which had the block print `--port 4210` into a host already holding it. And `renderNextSteps` now refuses a dev script whose name starts with a dash: every package manager reads `npm run --help` as its own option and prints its help instead of running the script, and quoting the name does not change that. |
There was a problem hiding this comment.
Condense the changeset to one user-facing sentence
This changeset contains three sentences and detailed implementation rationale, although the repository requires generated changesets to use a single user-facing sentence; the entire paragraph would otherwise be published as package release notes.
AGENTS.md reference: AGENTS.md:L32-L37
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Grok simplify review (2nd pass)
Verdict: IPv6 port parsing is the right fix. The leading-dash script handling went farther than it needed to — refusal is defensible, but a cleaner approach was not weighed.
What landed cleanly
hostPortOf via new URL — Correct simplify. The previous /:(\d+)/ reintroduced the collision the guard was meant to prevent on http://[::1]:4210. Using the platform URL parser is exactly the "don't hand-roll authority parsing" move. No third-party package needed; URL is the established tool. Unparseable → claim no port is the right null boundary.
Directory stays clean (one leaf file). No cross-import smell. Perf: none material — cold emit path, one new URL per render.
Where the approach overshot
Leading-dash scripts: refuse vs conditional --
The PR correctly measured that:
- Bare
run --helpis the manager's help (quoting does not help). run -- --helpruns the script on npm/pnpm/yarn.- Yarn warns on every
run -- <name>, including ordinary names.
It then rejected "emit -- always" and chose throw. That frames a false dichotomy. The third option — emit -- only when devScript.startsWith("-") — keeps the common Yarn path clean and still prints a working command for the pathological name.
That also mirrors a pattern already in this file: execSep exists so leading-dash arguments reach the binary instead of the manager ({{exec}}{{execSep}} fsdev …). run has the sibling problem when the script name starts with -; a conditional separator (or prefixing -- onto the rendered script token) is the same idea, scoped to the rare case.
Refusal turns a help-text renderer into an error path for an essentially-nobody script name, and pulls in measurement machinery (runPrintedCommandRaw, fixture --help, Yarn-warning assertion) to justify not fixing it. Conditional -- would turn that measurement into a positive-path executed test — same evidence, less surface.
Should-discuss (I'm unsure): Yarn's warning says a future version may forward explicit -- as-is. If that eventually breaks yarn run -- --help as a script-name escape, refusal is the more durable answer and the overshoot claim weakens. I am not sure of Yarn's timeline or exact future semantics — if you have a reason the separator is doomed on Yarn Classic, keep the throw and say so in one line. If not, prefer conditional --.
Smaller polish (non-blocking)
- Essay JSDocs on
hostPortOf/assertRunnableScriptNamerestate bug history the tests already pin — same prose-weight pattern as #1352 / #1355. One sentence each is enough. - IPv6 unit tests are good; the crash-on-unparseable check is cheap and worth keeping either way.
Disposition
Comment, not approve — IPv6 half is merge-ready; dash-script half should reconsider conditional -- before treating refuse-as-design as settled. Not requesting changes because refusal is a coherent (if heavier) answer if Yarn's future -- semantics are the real constraint.
Reviewer-only pass. No code changes, no new PR.
Sent by Cursor Automation: Grok Review For Best Approach
| * The alternative was emitting `<manager> run -- <script>` always, which does work everywhere. | ||
| * Rejected on measurement: Yarn prints *"scripts don't require `--` for options to be forwarded. | ||
| * In a future version, any explicit `--` will be forwarded as-is"* on **every** invocation — so | ||
| * every ordinary Yarn user would read a deprecation warning forever to accommodate a script name | ||
| * essentially nobody has. Refusing keeps the common path clean and turns the pathological one | ||
| * into an error the caller sees instead of a command the developer runs. |
There was a problem hiding this comment.
Grok simplify: The measured alternatives here are "always emit run -- <script>" vs refuse. That skips the middle path: emit -- only when devScript.startsWith("-").
- Ordinary names → no
--→ no Yarn deprecation warning on the common path. - Dash-prefixed names →
pnpm run -- --help(etc.) → script actually runs (your own measurement already shows this works on all three managers).
This file already solved the sibling problem for exec with execSep. A conditional separator for run is the same pattern, scoped to the rare case, and avoids turning the renderer into a throw for an essentially-nobody script name.
Unsure: If Yarn's "future -- forwarded as-is" will break that escape for option-like script names, refusal may be the durable answer — say so explicitly if that's the constraint. If not, conditional -- is the cleaner change.
| // And the separator form, which is the fix we did NOT take: it works, but Yarn prints a | ||
| // deprecation warning on every invocation — including for ordinary script names — so a | ||
| // refusal costs less than making every Yarn user read that forever. |
There was a problem hiding this comment.
Grok simplify: This comment encodes the same false dichotomy as the production JSDoc ("the fix we did NOT take" = always --).
If the product change becomes conditional -- only for leading-dash names, this probe should flip from "justify refusal" to a positive-path check: render devScript: "--help", assert the printed line contains the separator, and runPrintedCommand sees ARGV=. The Yarn warning assertion then only needs to hold for that rare rendered line — not as a reason to refuse forever.
If you keep refusal after weighing conditional --, this measurement stays valuable evidence; I'd still trim the "including for ordinary script names" rationale once the middle path is acknowledged.
| * **Parsed with `new URL`, not with a regex.** `/:(\d+)/` finds the first colon-digits anywhere in | ||
| * the string, which in `http://[::1]:4210` is the `1` inside the IPv6 address — so the guard above | ||
| * compared 1 against the reserved range, never matched, and printed `--port 4210` into a host that | ||
| * owns it. That is the same failure the guard was added to prevent, reintroduced by hand-rolling | ||
| * authority parsing. `URL` knows where the authority ends; we do not need to. |
There was a problem hiding this comment.
Grok simplify (non-blocking): The new URL switch is the right fix — keep the helper. The bug-history essay can shrink to one line ("URL.port, not /:(\d+)/, so IPv6 authority digits are not mistaken for the port"). The IPv6 unit test already pins the regression.
REVERSES THIS PR'S OWN DASH-SCRIPT DECISION. The previous revision framed two
options - always emit `--`, or refuse - and took the refusal. That was a false
dichotomy and a reviewer named the third: emit `--` ONLY when the script name
starts with a dash. Ordinary names keep the clean form and the Yarn warning
stays off the common path; dash-named scripts get a command that actually
runs, which this PR's own measurement table already proved works on all three
managers.
The decisive argument was already in this file. `{{execSep}}` exists so a
leading-dash ARGUMENT reaches the binary instead of the manager's option
parser. A script NAME has the identical problem and never got the sibling.
Refusing while `exec` has a separator is one half fixed and the other half
erroring - the same pattern this file keeps producing, sitting inside the fix
for it. So `{{runSep}}` mirrors `{{execSep}}`, conditional on the name rather
than on the manager.
It is also the better outcome: refusing meant a real project with an oddly
named script got no next-steps output at all, in exchange for avoiding a rare
deprecation line on a rare command.
yarn run dev (ordinary - unchanged, no warning)
yarn run -- --help (dash-named - runs the script)
`assertRunnableScriptName` is gone; there is nothing to refuse once the
command works.
THE PROBE NOW PROVES THE POSITIVE PATH. It renders `devScript: "--help"`,
asserts the printed line carries the separator, and asserts the executed
command's ARGV shows the script ran. The Yarn-warning assertion is kept and
scoped to the rendered dash line: Yarn Classic 1.x is in maintenance so the
escape is stable where it was measured, and Berry's direction is a genuine
unknown - which is why it is pinned by an executed test rather than by a
comment.
Also: hoist `hostPortOf(devUrl)` out of the range filter, which was parsing
the same URL once per candidate port.
And strengthen the unparseable-URL test to assert the ports stay as issued
rather than only that nothing threw. That is the rule the last two defects in
this file shared: A GUARD'S TESTS MUST COVER ITS INPUT DOMAIN, NOT ONLY THE
SCENARIO THAT MOTIVATED IT. The port guard was tested with the collision it
was built for and never with a URL shape; `process.features.typescript` was
tested with the value passed explicitly and never with its default. A check
that could not fail, twice, from opposite directions.
Bug-history prose on `hostPortOf` and the dash logic trimmed to one line each
- the tests pin those regressions, so the comments were restating them.
238 tests pass.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
The reversal fixed the code and left the prose arguing for the design it
replaced - the same one-half-updated shape as the pairs, now reaching the
comments.
Swept the whole diff rather than the one comment that was named. Two stale
artifacts in source, and the PR body separately:
- the fixture comment still said "the block refuses it; this fixture is what
proves the refusal is warranted rather than superstition". That fixture now
proves the separator makes the command RUN.
- the test-file header enumerated only the exec separator as the thing the
executed checks pin. Both are pinned now: a leading-dash ARGUMENT (exec) and
a leading-dash script NAME (run).
Checked and left alone: the module header already lists {{runSep}}; the other
"refuses" in both files are the missing-value, unsupported-manager and
bare-bind refusals, all still real.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
|
The body is rewritten to describe the separator rather than the refusal — it had been updated once already, but two real defects survived that pass and both are worth naming. 1. The verification block cited a red run I never performed. It showed 2. GitHub was eating Also corrected in the body: Grok is credited with finding the third option, and the declined option is stated accurately — it was always emitting the separator, not the conditional form. On the sweep. You are right about the shape, and it is worth stating precisely because it is not the same miss as the earlier pairs: my sweep found the two source artifacts and I did rewrite the body — but a The transferable line: a prose sweep scoped to the diff cannot see the PR body, the changeset rationale, or a Linear description — none of them are in the diff. They need a separate pass with its own checklist, because the tool that finds stale prose in code is blind to every artifact that lives outside the repository. Checked for the same reason: the changeset. It describes both behaviours in user terms and never mentions refusing — no stale claim there. Re-requesting review, since the open finding is against 🤖 Generated with Claude Code Generated by Claude Code |
The open Greptile finding is scoped to assertRunnableScriptName, which no longer exists. Empty commit to re-trigger review against the current diff.
The cheap, checkable facts about a repository that a coding assistant would
otherwise guess at, produced before anything is written to it. Ten
resolutions, one report with two renderers, and every refusal decided from
state the run has not modified.
NOTHING HERE WRITES, and no fact is read off the directory - each is asked of
the tool that owns it. README.md carries why both rules are shaped that way.
STRUCTURAL CHANGE THIS ROUND: STOP FIXING SIBLINGS, MAKE THE PAIR ONE RULE.
Every defect this module has shipped had the same shape. A pair exists - two
env loaders, two secrets, two static scans - a reviewer names one half, the
fix lands on the half that was named, and the other half surfaces the round
after. Six of the last eight findings were the third instance of two roots
already "fixed". So the pairs are now single rules with the set enumerated:
- DESTINATION SELECTION is one function. Every secret goes through it; the
only thing that differs is provenance (the developer supplies a provider
key, the run authors the token), which is one row of a table rather than
a branch. The demo token's hand-written branch is gone.
- STATIC READING is one entry point. source-scan.mjs owns every read of a
foreign source file - settings, imports, and the flow `kind` scan that
was still raw first-match after the config-level one was fixed.
- THE SETS ARE ENUMERATED IN TESTS. One walks every key in SECRET_KEYS and
asserts each was resolved from every loader that reads it. One walks
every module in detect/ and asserts none scans foreign source itself.
Both demonstrated red by restoring the exact defect:
x FSD_DEMO_TOKEN was resolved from 1 runtime(s):
expected [ 'your CLI' ] to deeply equal [ 'your CLI', 'next dev' ]
x fsdev-config.mjs reads foreign source directly; route it through
source-scan.mjs
Honest limit: adding a key to SECRET_KEYS is automatically routed by the
shared rule, so there is nothing to catch there. What the check catches
is the BYPASS - a hand-written branch that consults one loader - which is
the defect that actually occurred, twice.
Also fixed, each with a test:
- the write barrier now checks the PATH it would write, not the registry.
A project can own `flows/hello/flow.mts` without registering it; asking
the registry was checking a proxy for the thing.
- the container scan reached two levels by hand-unrolled loop, so a
workspace nested deeper evaded the refusal and reported as a plain Node
host. Depth is now a declared constant with a boundary test.
- an unparseable registry member is `undetermined`, not silently dropped.
- `plainString` decodes escape sequences: `basePath: "/docs\\x2fv1"` is the
path /docs/v1 to Next and was two literal characters to us.
THE DEV-SCRIPT REFUSAL WAS ASKED FOR AND IS DELIBERATELY NOT HERE. The
instruction predated #1358 reversing its own dash-script decision: the
renderer no longer throws on `--help`, it emits the separator and the command
runs. A phase-1 refusal would now reject a project that works. So the pair is
completed the other way - `needsRunSeparator` in detect and `runSeparatorFor`
in the CLI answer the same question, and a twin test runs both over one table
and fails if they diverge. That test is why this branch is STACKED on #1358:
it needs both halves to exist.
149 tests.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
The cheap, checkable facts about a repository that a coding assistant would
otherwise guess at, produced before anything is written to it. Ten
resolutions, one report with two renderers, and every refusal decided from
state the run has not modified.
NOTHING HERE WRITES, and no fact is read off the directory - each is asked of
the tool that owns it. README.md carries why both rules are shaped that way.
STRUCTURAL CHANGE THIS ROUND: STOP FIXING SIBLINGS, MAKE THE PAIR ONE RULE.
Every defect this module has shipped had the same shape. A pair exists - two
env loaders, two secrets, two static scans - a reviewer names one half, the
fix lands on the half that was named, and the other half surfaces the round
after. Six of the last eight findings were the third instance of two roots
already "fixed". So the pairs are now single rules with the set enumerated:
- DESTINATION SELECTION is one function. Every secret goes through it; the
only thing that differs is provenance (the developer supplies a provider
key, the run authors the token), which is one row of a table rather than
a branch. The demo token's hand-written branch is gone.
- STATIC READING is one entry point. source-scan.mjs owns every read of a
foreign source file - settings, imports, and the flow `kind` scan that
was still raw first-match after the config-level one was fixed.
- THE SETS ARE ENUMERATED IN TESTS. One walks every key in SECRET_KEYS and
asserts each was resolved from every loader that reads it. One walks
every module in detect/ and asserts none scans foreign source itself.
Both demonstrated red by restoring the exact defect:
x FSD_DEMO_TOKEN was resolved from 1 runtime(s):
expected [ 'your CLI' ] to deeply equal [ 'your CLI', 'next dev' ]
x fsdev-config.mjs reads foreign source directly; route it through
source-scan.mjs
Honest limit: adding a key to SECRET_KEYS is automatically routed by the
shared rule, so there is nothing to catch there. What the check catches
is the BYPASS - a hand-written branch that consults one loader - which is
the defect that actually occurred, twice.
Also fixed, each with a test:
- the write barrier now checks the PATH it would write, not the registry.
A project can own `flows/hello/flow.mts` without registering it; asking
the registry was checking a proxy for the thing.
- the container scan reached two levels by hand-unrolled loop, so a
workspace nested deeper evaded the refusal and reported as a plain Node
host. Depth is now a declared constant with a boundary test.
- an unparseable registry member is `undetermined`, not silently dropped.
- `plainString` decodes escape sequences: `basePath: "/docs\\x2fv1"` is the
path /docs/v1 to Next and was two literal characters to us.
THE DEV-SCRIPT REFUSAL WAS ASKED FOR AND IS DELIBERATELY NOT HERE. The
instruction predated #1358 reversing its own dash-script decision: the
renderer no longer throws on `--help`, it emits the separator and the command
runs. A phase-1 refusal would now reject a project that works. So the pair is
completed the other way - `needsRunSeparator` in detect and `runSeparatorFor`
in the CLI answer the same question, and a twin test runs both over one table
and fails if they diverge. That test is why this branch is STACKED on #1358:
it needs both halves to exist.
149 tests.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
The cheap, checkable facts about a repository that a coding assistant would
otherwise guess at, produced before anything is written to it. Ten
resolutions, one report with two renderers, and every refusal decided from
state the run has not modified.
NOTHING HERE WRITES, and no fact is read off the directory - each is asked of
the tool that owns it. README.md carries why both rules are shaped that way.
STRUCTURAL CHANGE THIS ROUND: STOP FIXING SIBLINGS, MAKE THE PAIR ONE RULE.
Every defect this module has shipped had the same shape. A pair exists - two
env loaders, two secrets, two static scans - a reviewer names one half, the
fix lands on the half that was named, and the other half surfaces the round
after. Six of the last eight findings were the third instance of two roots
already "fixed". So the pairs are now single rules with the set enumerated:
- DESTINATION SELECTION is one function. Every secret goes through it; the
only thing that differs is provenance (the developer supplies a provider
key, the run authors the token), which is one row of a table rather than
a branch. The demo token's hand-written branch is gone.
- STATIC READING is one entry point. source-scan.mjs owns every read of a
foreign source file - settings, imports, and the flow `kind` scan that
was still raw first-match after the config-level one was fixed.
- THE SETS ARE ENUMERATED IN TESTS. One walks every key in SECRET_KEYS and
asserts each was resolved from every loader that reads it. One walks
every module in detect/ and asserts none scans foreign source itself.
Both demonstrated red by restoring the exact defect:
x FSD_DEMO_TOKEN was resolved from 1 runtime(s):
expected [ 'your CLI' ] to deeply equal [ 'your CLI', 'next dev' ]
x fsdev-config.mjs reads foreign source directly; route it through
source-scan.mjs
Honest limit: adding a key to SECRET_KEYS is automatically routed by the
shared rule, so there is nothing to catch there. What the check catches
is the BYPASS - a hand-written branch that consults one loader - which is
the defect that actually occurred, twice.
Also fixed, each with a test:
- the write barrier now checks the PATH it would write, not the registry.
A project can own `flows/hello/flow.mts` without registering it; asking
the registry was checking a proxy for the thing.
- the container scan reached two levels by hand-unrolled loop, so a
workspace nested deeper evaded the refusal and reported as a plain Node
host. Depth is now a declared constant with a boundary test.
- an unparseable registry member is `undetermined`, not silently dropped.
- `plainString` decodes escape sequences: `basePath: "/docs\\x2fv1"` is the
path /docs/v1 to Next and was two literal characters to us.
THE DEV-SCRIPT REFUSAL WAS ASKED FOR AND IS DELIBERATELY NOT HERE. The
instruction predated #1358 reversing its own dash-script decision: the
renderer no longer throws on `--help`, it emits the separator and the command
runs. A phase-1 refusal would now reject a project that works. So the pair is
completed the other way - `needsRunSeparator` in detect and `runSeparatorFor`
in the CLI answer the same question, and a twin test runs both over one table
and fails if they diverge. That test is why this branch is STACKED on #1358:
it needs both halves to exist.
149 tests.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m


The problem
Two ways the closing "next steps" paragraph can hand a developer a command that does not do what it says.
A project whose own dev server runs on an IPv6 address gets told to start FSD on a port that server already holds. The block is supposed to notice that and step aside; it was reading the wrong number out of the address and stepping right into it.
A project whose dev script has an unusual name gets a command that silently does nothing. Every package manager treats a script called
--helpas a request for its own help — it prints the help, reports success, and never runs the script. The developer types the one command we gave them and nothing happens.What this does
The first is now read with a real URL parser instead of pattern-matching the text, so the port is the port regardless of what the address looks like.
The second adds the end-of-options separator to the printed command, so the script actually runs. It appears only for the rare dash-named script — an ordinary name renders exactly as before.
That second fix is the completion of a pair this file already had half of. The block has long carried a separator so that a leading-dash argument reaches our CLI instead of being eaten by the package manager. A leading-dash script name has the identical problem and had never been given the matching treatment. Same problem, same solution, one of them missing.
What's asked of you
Nothing new to decide — both are corrections to shipped behaviour, and neither changes the approach.
One thing worth knowing about how this PR moved, because it is the more useful part:
An earlier revision of this PR refused the odd script name instead of making it work. It presented the choice as two options — always add the separator, or refuse — and picked refusing, on the grounds that always adding it puts a deprecation warning in front of every ordinary Yarn user. That framing was mine and it was a false dichotomy: Grok named the third option, which is to add the separator only when the name needs it. That gets the clean common path and the working rare command, and the measurement showing it works was already in the PR. The option genuinely declined is always emitting the separator; conditional is the middle path I had not weighed.
The practical difference for a user: under the old revision, a real project with an oddly named script got no next-steps output at all. Now it gets a command that runs.
Parts worth reviewing closely
runSeparatorFor. Conditional on the script name, not on the package manager — that is what keeps the separator off every ordinary render. Worth checking the condition is the same one the argument separator answers, since the whole point is that the two halves match.hostPortOf. The fix is "letURLfind the authority". Worth confirming the unparseable case claims no port rather than guessing one — that is what keeps a malformed input from silently shifting the ports.--semantics change, that test goes red and we revisit — rather than a user discovering it.Links
Linear FIX-1159 · follows #1352 (merged) · epic FIX-1161 (#1301) — merges.
How to review this
How to review this. This implements an approved spec — the approach and the numbered Decisions in its §6 are already signed off by a human, so please review the code against that direction, not the direction itself. The spec lives on the issue's Linear document (the durable copy) and on the closed spec PR (#1310), which keeps its review history. Don't expect
spec/FIX-1159.mdto be in this diff — the spec PR closes unmerged at approval and the spec never lands onmain(BP-037).Most valuable here: correctness on the second path (the legacy shape, the null boundary, the concurrent case, the cancel path), anything deriving an auth or routing decision from caller-controllable input, and a behaviour the tests assert around rather than on.
Already settled upstream: the approach and every §6 Decision (human-approved — if one is wrong, say so as a spec finding and it gets folded back; don't re-argue it inline), and the conventions in
docs/contributing/best-practices.md.Engineering calls
The run separator mirrors the exec separator, conditional on the name rather than the manager. Measured on npm 10.9.7 / pnpm 10.4.1 / yarn 1.22.22:
npm run --help,pnpm run --help,yarn run --helpnpm run '--help'npm run -- --help,pnpm run -- --help,yarn run -- --helpyarn run -- dev(an ordinary name)--That last row is why the separator is conditional rather than always emitted: it confines the warning to the rare command instead of putting it in front of every ordinary render.
On whether a future Yarn breaks
--as a script-name escape: Yarn Classic 1.x is in maintenance, so the escape is stable where it was measured. Berry's direction is a genuine unknown — which is exactly why it is pinned by an executed test rather than by a comment. I am not claiming to know Yarn's roadmap; I am claiming the test goes red if it changes.The IPv6 bug was in code added the round before, to fix the previous port finding — that guard hand-rolled authority parsing with
/:(\d+)/, which captured the1inside[::1]. Named because "the fix introduced the next instance" is the pattern worth noticing, not because the history needs preserving in a comment; the test pins it and the comment is one line.An unparseable
devUrlclaims no port. Returning a guess would let a malformed value shift the ports unpredictably, which is worse than the collision the guard is for. Asserted on the resulting ports, not on "did not throw".hostPortOfhoisted out of the range filter, which was parsing the same URL once per candidate port.Not fixed here:
shellQuoteremains POSIX-only (FIX-1196). Unchanged by this PR.On the changeset length
Trimmed to what a changelog reader needs — the two behaviours that change, no implementation rationale.
Trimmed because that is the right length, not because a one-sentence rule requires it.
AGENTS.md:35says "Write a single user-facing sentence describing the change. Multi-paragraph or migration notes are fine when warranted." The one-sentence reading has now been raised twice; it is not what the file says, and a genuinely breaking or migration-shaped change should still get the room it needs.Verification
Run from
packages/cli, not the repo root.Rendered, both forms (yarn):
Both fixes demonstrated able to go red. The IPv6 one by restoring the regex:
And the separator by making
runSeparatorForreturn""unconditionally — four red across the render check and all three managers:The executed dash-script check asserts three things in sequence: the bare form produces no
ARGV=at all, the rendered line is exactly<manager> run -- --help, and the printed command yieldsARGV=["--from-dash-script"].One thing that had to be fixed in the test harness itself:
execFileSyncdiscards stderr on success, which is exactly where Yarn prints its warning, so the raw runner usesspawnSyncand captures both streams.