Skip to content

docs(qa): state the console boot flag per command in RUNNER.md - #10346

Merged
os-zhuang merged 1 commit into
mainfrom
claude/issue-10087-runner-boot-flag
Aug 20, 2026
Merged

docs(qa): state the console boot flag per command in RUNNER.md#10346
os-zhuang merged 1 commit into
mainfrom
claude/issue-10087-runner-boot-flag

Conversation

@os-zhuang

@os-zhuangos-zhuang commented Aug 20, 2026

Copy link
Copy Markdown
Contributor

Fixes#10087

What this changes

Docs only — docs/qa/platform-checklist/RUNNER.md. Two edits:

  1. New environment fact: the console boot flag stated per command, plus the one
    canonical checklist boot invocation, plus the check that tells a rejected flag apart
    from a crashed boot.
  2. absence-inference trap row rewritten so it stops carrying --no-ui across to
    dev. That row was the actual defect: its subject sentence is a bare
    objectstack dev, but it explained the default-ON console through serve'sui
    flag and concluded "so --no-ui is the off switch" — which reads as a licence to type
    dev --no-ui. It now names dev's forwarding behaviour, says the default is decided
    one hop downstream, and states that the off switch belongs to serve and start.

Re-measured on current main before editing — this was the acceptance criterion

The card's own measurement is stamped at 4a7b3604c and was not copied on trust.
Built @objectstack/cli and its dependency closure at origin/main = 736cfb14 and ran
the real binary. Verdicts are the commands' own output; exit codes were captured before
any pipe.

The premise holds.dev still rejects --no-ui:

$ node packages/cli/bin/run.js dev --no-ui # EXIT=2
objectstack: INVOCATION ERROR — Nonexistent flag: --no-ui. The command never ran: nothing was started and nothing is listening. Invoked as: objectstack dev --no-ui
› Error: Nonexistent flag: --no-ui

Positive controls, because a zero-hit needs one. Two paired probes, each with the
control inside the same invocation as the negative:

proberejectedaccepted (control)
dev --no-restart --no-ui--no-ui--no-restart — negation syntax works on dev
serve --no-ui --artifact ./x.json--artifact--no-ui — accepted by serve

--help FLAGS blocks agree, and dev renders --[no-]compile / --[no-]restart /
--[no-]seed-admin, so the missing --[no-]ui is a real absence and not a rendering
artifact. Measured surface across all three boot commands:

commandconsole flag--artifact
os dev--ui (no negation)-a, --artifact
os serve--[no-]uinot a flag
os start--[no-]ui-a, --artifact

dev is the odd one out, which is why the flag gets carried across to it. The asymmetry
runs both ways, so the doc says "flags are not portable between the three" rather than
just "serve has it".

One thing HAS changed since the card was filed, and the doc reflects it

The card's sibling domain:cli half — issue #10111, now completed — landed as PR #10181,
after the card's stamp. Both lookalikes now announce themselves: the unknown-flag failure prints a
single loud first line ahead of the usage dump, and node packages/cli/dist/index.js now
refuses by name and exits 1 where it used to exit 0 in silence (measured, both).

That does not soften this card — the flag surface is unchanged, and #10181's own docblock
says so deliberately: "Fixing (2) by teaching dev to accept --no-ui is deliberately
NOT what this module does."
It changes what good documentation looks like: the counter
to the backgrounded-boot failure mode is now actionable, so the new fact ends with read
the FIRST line of the log before touching the app
, and quotes the literal line to
recognise.

Deliberately not done

⛔ Making dev accept --no-ui is in neither card — it is a CLI surface question for the
decision inbox as a Feature. No CLI change here; nothing in this PR adds or removes an
accepted input — the diff is one markdown file.

Verification

  • pnpm check:nul-bytescheck-nul-bytes: OK (scanned 6090 text file(s) ... no raw ASCII control bytes)
  • pnpm check:platform-checklistcheck-platform-checklist: OK — 15 areas, 204 items (204 active); coverage: 30 kinds mapped, 0 waived.
  • node scripts/pm/dispatch-gates.mjs re-run on the final commit 24b14c81:
    No check family names the given paths in its own source, and no workflow's path filter schedules one for them. (0 matched)

Clause-②: no — docs-only diff; no contract accept/reject behaviour changes and no
public surface widens.

Changeset: none — docs/qa/** publishes nothing. Labelled skip-changeset.


Generated by Claude Code


Generated by Claude Code

`--no-ui` is a flag of `serve` and `start`, not of `dev`. RUNNER.md's
`absence-inference` trap row explained the default-ON console by way of
`serve`'s `ui` flag while its subject sentence was a bare `objectstack dev`,
so the off switch read as available on `dev` too. It is not: `dev` declares
`ui` with no `allowNo`, and `objectstack dev --no-ui` fails the parse and
exits 2 without starting anything.
Backgrounded — which is how a runner boots a server — that failure looks
exactly like a server that booted and died, so the reader debugs the
application that was never started.
Adds an environment fact stating the measured flag surface for all three
boot commands, the one canonical checklist boot invocation (which makes no
`ui` decision to get wrong), and the log-reading check that tells a parse
failure apart from a crashed boot. Rewrites the trap row so it stops
carrying `--no-ui` across to `dev`.
Measured on main at 736cfb1 against a real build, not read off the parser
source. No CLI change: nothing here adds or removes an accepted input.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DdCnBGcHeufjrq7drTD3wt
@github-actionsgithub-actionsBot added size/s documentation Improvements or additions to documentation labels Aug 20, 2026
@os-zhuangos-zhuang added skip-changeset PR has no user-facing published change; bypasses the changeset gate and removed documentation Improvements or additions to documentation labels Aug 20, 2026 — with Claude
@os-zhuang
os-zhuang marked this pull request as ready for review August 20, 2026 16:09
@os-zhuang
os-zhuang enabled auto-merge August 20, 2026 16:10
@os-zhuang
os-zhuang disabled auto-merge August 20, 2026 16:11
@os-zhuang
os-zhuang marked this pull request as draft August 20, 2026 16:11
@claudeclaudeBot added the documentation Improvements or additions to documentation label Aug 20, 2026
@os-zhuang
os-zhuang marked this pull request as ready for review August 20, 2026 16:16
@os-zhuang
os-zhuang added this pull request to the merge queueAug 20, 2026
Merged via the queue into main with commit 4926690Aug 20, 2026
32 checks passed
@os-zhuang
os-zhuang deleted the claude/issue-10087-runner-boot-flag branch August 20, 2026 17:23
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentationImprovements or additions to documentationsize/sskip-changesetPR has no user-facing published change; bypasses the changeset gate

Projects

None yet

2 participants

@os-zhuang@claude