docs(qa): state the console boot flag per command in RUNNER.md - #10346
Merged
Conversation
`--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
os-zhuang
marked this pull request as ready for review
August 20, 2026 16:09
os-zhuang
enabled auto-merge
August 20, 2026 16:10
os-zhuang
disabled auto-merge
August 20, 2026 16:11
os-zhuang
marked this pull request as draft
August 20, 2026 16:11
os-zhuang
marked this pull request as ready for review
August 20, 2026 16:16
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #10087
What this changes
Docs only —
docs/qa/platform-checklist/RUNNER.md. Two edits:canonical checklist boot invocation, plus the check that tells a rejected flag apart
from a crashed boot.
absence-inferencetrap row rewritten so it stops carrying--no-uiacross todev. That row was the actual defect: its subject sentence is a bareobjectstack dev, but it explained the default-ON console throughserve'suiflag and concluded "so
--no-uiis the off switch" — which reads as a licence to typedev --no-ui. It now namesdev's forwarding behaviour, says the default is decidedone hop downstream, and states that the off switch belongs to
serveandstart.Re-measured on current
mainbefore editing — this was the acceptance criterionThe card's own measurement is stamped at
4a7b3604cand was not copied on trust.Built
@objectstack/cliand its dependency closure atorigin/main=736cfb14and ranthe real binary. Verdicts are the commands' own output; exit codes were captured before
any pipe.
The premise holds.
devstill rejects--no-ui:Positive controls, because a zero-hit needs one. Two paired probes, each with the
control inside the same invocation as the negative:
dev --no-restart --no-ui--no-ui--no-restart— negation syntax works ondevserve --no-ui --artifact ./x.json--artifact--no-ui— accepted byserve--helpFLAGS blocks agree, anddevrenders--[no-]compile/--[no-]restart/--[no-]seed-admin, so the missing--[no-]uiis a real absence and not a renderingartifact. Measured surface across all three boot commands:
--artifactos dev--ui(no negation)-a, --artifactos serve--[no-]uios start--[no-]ui-a, --artifactdevis the odd one out, which is why the flag gets carried across to it. The asymmetryruns 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:clihalf — 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.jsnowrefuses 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
devto accept--no-uiis deliberatelyNOT 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
devaccept--no-uiis in neither card — it is a CLI surface question for thedecision 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-bytes—check-nul-bytes: OK (scanned 6090 text file(s) ... no raw ASCII control bytes)pnpm check:platform-checklist—check-platform-checklist: OK — 15 areas, 204 items (204 active); coverage: 30 kinds mapped, 0 waived.node scripts/pm/dispatch-gates.mjsre-run on the final commit24b14c81: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. Labelledskip-changeset.Generated by Claude Code
Generated by Claude Code