Skip to content

fix(fsdev): IPv6 dev URLs and leading-dash script names (FIX-1159) - #1358

Merged
jhoffner merged 4 commits into
mainfrom
fix/FIX-1159-next-steps-followups
Aug 21, 2026
Merged

jhoffner merged 4 commits into
mainfrom
fix/FIX-1159-next-steps-followups

Conversation

@jhoffner

@jhoffner jhoffner commented Aug 21, 2026 •

Copy link
Copy Markdown
Collaborator

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 --help as 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 "let URL find 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.
  • The executed dash-script test. It runs the bare form (which reaches the manager's own help) and the printed form (which reaches the script), so the separator's necessity and its sufficiency are both measured rather than asserted.
  • The Yarn warning assertion. Scoped to the rendered dash line. If Yarn's -- 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.md to be in this diff — the spec PR closes unmerged at approval and the spec never lands on main (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:

invocation result
npm run --help, pnpm run --help, yarn run --help each prints its own help, exit 0, script never runs
npm run '--help' same — quoting does not reach the manager's option parser
npm run -- --help, pnpm run -- --help, yarn run -- --help the script runs, on all three
yarn run -- dev (an ordinary name) works, and warns about explicit --

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 the 1 inside [::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 devUrl claims 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".

hostPortOf hoisted out of the range filter, which was parsing the same URL once per candidate port.

Not fixed here: shellQuote remains 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:35 says "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.

$ cd packages/cli && pnpm test
 Test Files  20 passed (20)
      Tests  238 passed (238)
$ cd packages/cli && pnpm typecheck      (clean)
$ node scripts/validate-changeset-refs.mjs
 ✓ every new changeset names its Linear issue

Rendered, both forms (yarn):

  yarn run dev            ← ordinary, unchanged, no warning
  yarn run -- --help      ← dash-named, runs the script

Both fixes demonstrated able to go red. The IPv6 one by restoring the regex:

× reads the host's port out of an IPv6 dev URL, not the digits inside the address
  → expected '…' to contain 'fsdev dev --port 4211'
    (the rendered block showed → http://[::1]:4210 alongside --port 4210)

And the separator by making runSeparatorFor return "" unconditionally — four red across the render check and all three managers:

× carries the end-of-options separator for a dash-named script, and only for one
  → expected 'Next steps\n\n  npm run --help\n …' to contain 'npm run -- --help'
× npm   > runs a dash-named dev script through the separator the block prints
  → expected 'npm run --help' to be 'npm run -- --help'
× pnpm  > runs a dash-named dev script through the separator the block prints
  → expected 'pnpm run --help' to be 'pnpm run -- --help'
× yarn  > runs a dash-named dev script through the separator the block prints
  → expected 'yarn run --help' to be 'yarn run -- --help'

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 yields ARGV=["--from-dash-script"].

One thing that had to be fixed in the test harness itself: execFileSync discards stderr on success, which is exactly where Yarn prints its warning, so the raw runner uses spawnSync and captures both streams.

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
@linear-code

linear-code Bot commented Aug 21, 2026

Copy link
Copy Markdown

FIX-1159

@vercel

vercel Bot commented Aug 21, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments
Project Deployment Actions Updated (UTC)
flow-state-dev-docs Ignored Ignored Aug 21, 2026 8:03pm
flow-state-dev-kitchen-sink Ignored Ignored Aug 21, 2026 8:03pm
flow-state-dev-ui Ignored Ignored Preview Aug 21, 2026 8:03pm

@cursor

cursor Bot commented Aug 21, 2026

Copy link
Copy Markdown
Contributor

Bugbot couldn't run - usage limit reached

Bugbot 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)

Comment thread packages/cli/src/next-steps.ts Outdated
text = text.replace(sectionPattern(key), () => kept);
}

if (options.devScript !== undefined) assertRunnableScriptName(options.devScript);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 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.

Suggested change
if (options.devScript !== undefined) assertRunnableScriptName(options.devScript);
if (options.topology === "mounted-route" && options.devScript !== undefined) {
assertRunnableScriptName(options.devScript);
}

Fix in Cursor

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 the filter — 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-route only (second-process never 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.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread packages/cli/src/next-steps.ts Outdated
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));

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread packages/cli/src/next-steps.ts Outdated
text = text.replace(sectionPattern(key), () => kept);
}

if (options.devScript !== undefined) assertRunnableScriptName(options.devScript);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread packages/cli/test/next-steps.test.ts Outdated

it("does not crash on a dev URL it cannot parse", () => {
expect(() =>
renderNextSteps({ ...MOUNTED, devUrl: "not a url at all", packageManager: "pnpm" }),

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@claude

claude Bot commented Aug 21, 2026

Copy link
Copy Markdown
Contributor

second-look: PR #1358

Verdict: Appropriately scoped — a tight, measured fix; no trimmable bloat found.
Scope: diff → +137 / −3 across 3 files (packages/cli/src/next-steps.ts, its test, and the changeset).

# Finding Lens Recommendation Est. Δlines Sev Conf
— none passed the calibration gate

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

  • hostPortOf as its own function, rather than inlining the try/catch into allocatePorts — the extraction is what lets the "an unparseable URL claims no port, not a guess" invariant get its own doc line, and the replacement is already strictly simpler than the regex it fixes (no net addition to defend).
  • assertRunnableScriptName's "any leading dash" scope — broad-looking at a glance, but it's backed by the PR's own cross-manager measurement table rather than assumed, and the rejected alternative (always insert --) was tried and dropped on a real, measured cost (Yarn's permanent deprecation warning) rather than a hypothetical one.
  • Executing real npm/pnpm/yarn subprocesses in the new tests, including the new runPrintedCommandRaw (needed because execFileSync swallows stderr on success, which is exactly where Yarn's warning lands) — this matches the file's existing test discipline (assert on what actually ran, not on string shape) rather than adding a new pattern.
  • Looping the "refuses a leading-dash script" test over all three managers, even though assertRunnableScriptName doesn't branch on manager — technically redundant (~4 lines), but well under the threshold where collapsing it would be worth a finding.

Automated second-look pass — restraint/approach lens only. See .claude/skills/second-look for scope.


Generated by Claude Code

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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".

Comment thread packages/cli/src/next-steps.ts Outdated
text = text.replace(sectionPattern(key), () => kept);
}

if (options.devScript !== undefined) assertRunnableScriptName(options.devScript);

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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 👍 / 👎.

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

  1. Bare run --help is the manager's help (quoting does not help).
  2. run -- --help runs the script on npm/pnpm/yarn.
  3. 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 / assertRunnableScriptName restate 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.

Open in Web View Automation 

Sent by Cursor Automation: Grok Review For Best Approach

Comment thread packages/cli/src/next-steps.ts Outdated
Comment on lines +331 to +336
* 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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread packages/cli/test/next-steps.test.ts Outdated
Comment on lines +725 to +727
// 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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread packages/cli/src/next-steps.ts Outdated
Comment on lines +219 to +223
* **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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

claude added 2 commits August 21, 2026 19:56
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

Copy link
Copy Markdown
Collaborator Author

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 × refuses a dev script … → expected [Function] to throw an error, labelled "from the earlier, reversed revision". That is evidence for the design this PR removed, and I had not run the red demo for the design it kept. Now run, by making runSeparatorFor return "" unconditionally — four red, the render check plus all three managers:

× carries the end-of-options separator for a dash-named script, and only for one
  → expected 'Next steps\n\n  npm run --help\n …' to contain 'npm run -- --help'
× npm   → expected 'npm run --help'  to be 'npm run -- --help'
× pnpm  → expected 'pnpm run --help' to be 'pnpm run -- --help'
× yarn  → expected 'yarn run --help' to be 'yarn run -- --help'

2. GitHub was eating <manager> as an HTML tag, so the measurement table's third row rendered as | run -- --help | — a blank command. The table read as nonsense in exactly the row that carries the fix. Rows are spelled out per manager now.

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 git diff | grep cannot check the body, so the body's correctness rested on my having rewritten it carefully rather than on any check. That is how an unrun red demo and a broken table both survived a pass I considered complete.

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 assertRunnableScriptName, which no longer exists.

🤖 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.
jhoffner pushed a commit that referenced this pull request Aug 21, 2026
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
@jhoffner
jhoffner merged commit df15ee4 into main Aug 21, 2026
12 checks passed
jhoffner pushed a commit that referenced this pull request Aug 21, 2026
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
jhoffner pushed a commit that referenced this pull request Aug 26, 2026
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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants