Repository navigation
[finding] README's pnpm install && pnpm build && pnpm dev serves no Console on a fresh clone: /_console/ and / answer 404, and the boot warning names a remedy that does not exist in this repo #22155
Description
Filing gate: ① product defect with a named landing spot and a reproduction (finding class (a): the README's command sequence yields a 404 where the same README says the Console is; plus a boot message whose prescription is wrong for this repository).
reach: public entry measured once — after the README's three commands, GET /_console/ on the showcase dev server answers 404 {"success":false,"error":{"code":"ENDPOINT_NOT_FOUND"…}} and GET / answers 404; after the undocumented pnpm objectui:build the same requests answer 200 and 302.
Reader: domain:devx seat for README.md (one line) and the boot warning's remedy text in the Console-mount code path (packages/cli / plugin-hono-server, whichever prints Console dist not found — install @object-ui/console …); the bare-404 half is domain:cli.
Dedup: search_issues "README pnpm dev Console dist not found fresh clone /_console/ 404 objectui:build step missing Hack on the framework" (open + closed) → 0 cards.
Filed on the maintainer's instruction in this session: 「设想你是一个新人,第一次打开 github objectstack 项目主页,了解本项目,并按照文档指引执行完整的试用流程,并对阅读文档和试用过程中遇到的问题立 issue」.
Summary
The README's contributor on-ramp is three commands:
pnpm install # Node 22+, pnpm 10 (corepack enable)
pnpm build # build all packages
pnpm dev # showcase example: REST + Console on :3000On a fresh clone of main that sequence boots the showcase API but no Console. packages/console/dist is gitignored and turbo run build never produces it (by design — scripts/check-console-sha.mjs and content/docs/getting-started/examples.mdx both say so), so the step that actually produces the Console, pnpm objectui:build, is missing from the README. A newcomer who follows the README then opens http://localhost:3000/_console/ (the URL the same README gives in Try it in five minutes) and gets a JSON 404.
Two smaller problems compound it:
- The boot-time warning names the wrong remedy for this repository. The server prints
⚠ Console dist not found — install \@object-ui/console` (already built) or run `pnpm --filter @object-ui/console build` in the objectui workspace. Neither instruction applies insideobjectstack-ai/objectstack:@object-ui/consoleis not a dependency anyone installs here, andpnpm --filter @object-ui/console buildassumes a cwd inside the objectui workspace. The repo's own remedy ispnpm objectui:build(whichscripts/build-console.shresolves against a../objectuisibling or, failing that, a shallow clone into.cache/), andpnpm check:console-sha` already prints exactly that line one step earlier. The two messages disagree on the same boot. - The absence is not loud at the HTTP surface. With no Console,
GET /returns404with an empty body andGET /_console/returns{"success":false,"error":{"code":"ENDPOINT_NOT_FOUND","message":"Not found"}}— indistinguishable from a wrong URL. AGENTS.md's "Absence must be loud" rule asks for a composition that legitimately serves nothing to say so once, naming the remedy; here the remedy is only in the terminal, and it is the wrong one.
Reproduction
Fresh clone of main, Node v22.22.0, pnpm 10.31.0.
pnpm install # 16 s
pnpm build # 72 turbo tasks, ~7 min, exit 0
ls packages/console/dist # No such file or directory
pnpm dev -- --fresh -p 38431 # README's `pnpm dev`, on a spare portBoot output (abridged):
ℹ No console dist at packages/console/dist — skipping SHA check. Build it with: pnpm objectui:build
…
⚠ Page source and `requires` not validated at save: no SDUI component manifest at …/examples/app-showcase/sdui.manifest.json or …/packages/console/dist/sdui.manifest.json …
⚠ Console dist not found — install `@object-ui/console` (already built) or run `pnpm --filter @object-ui/console build` in the objectui workspace
✓ Server is ready
➜ API: http://localhost:38431/
➜ MCP: http://localhost:38431/api/v1/mcp
(Note the ➜ Console: line that a scaffolded project prints is absent — the only hint on the banner.)
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:38431/_console/ # 404 (application/json, ENDPOINT_NOT_FOUND)
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:38431/ # 404
curl -s http://localhost:38431/api/v1/health # {"success":true,…} — the API itself is fineFor contrast, a project scaffolded with npm create objectstack@latest serves /_console/ (200, the SPA) out of the box because the published @objectstack/cli depends on the prebuilt @objectstack/console package.
The missing step itself works on a fresh machine with no ../objectui checkout: pnpm objectui:build shallow-cloned objectui at the pinned SHA into .cache/, built it in 10 m 36 s, wrote packages/console/dist (63 MB), left git status clean, and pnpm check:console-sha then reported ✓ Console dist matches the objectui pin. So the fix on the README side is one line.
Expected
- The README's three-command flow either produces a Console or says in the same block that
pnpm objectui:buildis the extra step (and that it needs network or a../objectuicheckout), matchingexamples.mdx. - The boot warning names the remedy that works in the cwd it is printed from — for this repo,
pnpm objectui:build. GET /_console/(and ideally/) on a composition with no Console answer with a short page or JSON that says the Console is not built and how to build it, instead of a bareENDPOINT_NOT_FOUND.
Actual
The README omits the step, the warning sends the reader to a different repository's command, and the HTTP surface returns anonymous 404s.
Generated by Claude Code
Activity
objectstack-fleet commentedon Oct 8, 2026
Path: the road — start: a contributor sees the Console | 缺项 | P2
Triage: first grade,
bug·priority:p2·domain:devx·area:devpath·pm:queue(findingremoved). Direction: the README names the Console step, and the boot warning names a remedy that existsTriage seat (objectstack-wide, seat post #6015) ·
session_01AavokzJ5DndAwitDXvKy4U· 2026-10-08T05:01Z. ⛔ Not a claim, ⛔ not a dispatch.Triage: lands in
README.md("Hack on the framework") and the Console-mount warning text (Console dist not found — install @object-ui/console …, in the CLI's console mount) ⇒domain:devx; rationale:README.mdis that lane's; the warning text is declared todomain:clicross-lane. Read onmainec8f37c890.pnpm objectui:build(with its cost, see [maintainer] README "Hack on the framework" should state what its commands cost on a fresh clone —pnpm objectui:build≈ 10 min to get the Console,pnpm test≈ 54 min — and point to turbo's--affectedpath for a contributor's own change #22164)pnpm objectui:buildin the framework repo, the package install elsewherepnpm objectui:build≈ 10 min to get the Console,pnpm test≈ 54 min — and point to turbo's--affectedpath for a contributor's own change #22164 and [finding] docs on-ramp drift a first-time reader hits in sequence: stale CONTRIBUTING.md (retiredspecrepo), README's firstcurlgets 401, three pnpm floors, "three examples" vs five,os dev --help/os initstrings, tutorial transcript #22156, which edit the same README section: one PR may carry all three; name the cards it closes.Clause-②: no. Patch changeset only for the CLI text.objectstack-fleet commentedon Oct 8, 2026
Claim: PM loop round 8 · anchor of a two-card bundle (#22155 + #22164), as triage's direction on both allows ("one PR may carry all three; name the cards it closes")
Session:
session_01VF48aw8RPG6wzDnMgp6rtwAccount:
os-justin(the seat's linked user asGET /useranswers it; the cards' assignee)Branch:
claude/issue-22155-readme-contributor-path(new, cut fromorigin/main6ed0c0f3e5)Worktree:
objectstack-issue-22155Domain:
domain:devxSeat:
domain:devx#2Cards closed by the one PR: #22155 (p2, this anchor) and #22164 (p3, the maintainer's ③; a pointer claim is on that card).
File surface:
README.md, the "Hack on the framework" section:pnpm install && pnpm build && pnpm devserves no Console on a fresh clone:/_console/and/answer 404, and the boot warning names a remedy that does not exist in this repo #22155: thepnpm objectui:buildstep that serves the Console;pnpm objectui:build≈ 10 min to get the Console,pnpm test≈ 54 min — and point to turbo's--affectedpath for a contributor's own change #22164: each command's measured cost, and turbo's--affectedpath for a contributor's own change.packages/cli/src/commands/serve.ts, cross-lane (domain:cli, declared): theConsole dist not foundwarning's remedy text, so it names the remedy for where it runs. A patch changeset for@objectstack/cli.specrepo), README's firstcurlgets 401, three pnpm floors, "three examples" vs five,os dev --help/os initstrings, tutorial transcript #22156's README items (curl, pnpm floors) andCONTRIBUTING.md. [finding] docs on-ramp drift a first-time reader hits in sequence: stale CONTRIBUTING.md (retiredspecrepo), README's firstcurlgets 401, three pnpm floors, "three examples" vs five,os dev --help/os initstrings, tutorial transcript #22156 is serial after this PR. The bare-404 half of [finding] README'spnpm install && pnpm build && pnpm devserves no Console on a fresh clone:/_console/and/answer 404, and the boot warning names a remedy that does not exist in this repo #22155 isdomain:cli's.Container & model:
M,mode:subagent,model: opus(dispatch-gates --tier: no path-derived mandate; default tier)Clause-②: no
Responsibility:
README.md's contributor on-ramp and the CLI's Console-mount warning (this repo's) |domain:clifor the 404 behaviour itself | every first-time contributor who follows the READMEThread-read: 6052663128
Serial constraints cleared:
README.md,CONTRIBUTING.mdorserve.ts(all open PRs' file lists read this round).specrepo), README's firstcurlgets 401, three pnpm floors, "three examples" vs five,os dev --help/os initstrings, tutorial transcript #22156 waits behind this PR and the [finding] docs(getting-started): the Build-with-Claude-Code tutorial'sresolve_ticketaction names atargethandler nothing registers — the "Resolve" button it tells you to verify in the Console is the dead-button trap the Actions page warns about #22152 bundle; it shares the README section and the getting-started pages.objectstack-fleet commentedon Oct 8, 2026
os-dev-report
{ "issue": 22155, "status": "done", "branch": "claude/issue-22155-readme-contributor-path", "pr": "https://github.com/objectstack-ai/objectstack/pull/22224", "session": "session_01VF48aw8RPG6wzDnMgp6rtw (subagent; the parent's harness-stamped id, read from CLAUDE_CODE_REMOTE_SESSION_ID)", "premise_still_valid": true, "summary": "Bundle #22155 + #22164, one draft PR (#22224), head 0ef75bd7d9, BASE c6fe02d7ac. Body line 1 is 'Fixes #22155', line 2 is 'Fixes #22164', then 'Clause-②: no'; there are no other closing keywords, and #22156 is named only as not addressed. Every premise held on origin/main c6fe02d7ac: serve.ts:5069 printed the @object-ui/console remedy in every context; packages/console/dist is gitignored and not built by turbo; scripts/build-console.sh resolves ../objectui or makes a shallow clone into .cache/objectui-SHA12, and runs pnpm install in both modes, so it needs network either way; examples.mdx says the same. README 'Hack on the framework' now: (1) adds 'pnpm objectui:build' to the block, with a paragraph on what it builds, where from, that it needs network, that pnpm dev serves REST without it, and to rerun it when .objectui-sha moves; (2) has a cost table quoting the cards' fresh-clone numbers with the machine class (install 16 s, build 6 m 54 s, objectui:build 10 m 36 s, test 54 m 03 s; none re-measured); (3) points to 'pnpm turbo run test --affected' and 'pnpm --filter @objectstack/PKG test', with the local-main base caveat. The bare 'pnpm test' line moved out of the block into the table. The 'pnpm install' comment text is unchanged (re-aligned only). CLI: serve.ts now calls the new formatConsoleDistMissingWarning(consolePath) in packages/cli/src/utils/console.ts, beside the drift formatters. The remedy signal is whether the NEAREST package.json above the resolved console package declares an 'objectui:build' script, which is exactly the claim the message makes; I chose it over the .objectui-sha pin or a repo-layout check. If the script is declared, the warning says 'pnpm objectui:build' plus the root dir to run it in, since pnpm dev's cwd is examples/app-showcase. Otherwise it says to reinstall @objectstack/console at the CLI's version: a scaffolded project depends on @objectstack/cli, which depends on @objectstack/console, the only package the resolver reads. File surface beyond the literal serve.ts path, all inside 'the minimum code that decides which remedy to name' plus its tests: packages/cli/src/utils/console.ts, packages/cli/test/console-resolve.test.ts (4 cases), and packages/cli/test/published-subpath-console.pin.test.ts. The last one partitions every export of utils/console.ts and went red on the new export until it was recorded as INTERNAL_SINCE_RETIREMENT; the existing 'exactly three names' checks keep it off the published ./console subpath. Not done here: the bare-404 HTTP half of #22155 (domain:cli), named in the PR body. Note for the seat: 'Fixes #22155' closes the card on merge, so that half has no open card afterwards unless the seat files one. PR assignee set to os-justin. No labels written: the dispatch named none and skip-changeset does not apply. size/m was added by another actor. Cleanup: node_modules and the worktree are removed right after this comment posts.", "tests": "All on HEAD 0ef75bd7d9 unless noted, every heavy run through os-verify-lock (VERDICT lines quoted). (1) Build: 'pnpm --filter @objectstack/cli^... build' VERDICT command-exit 0 (5m50s); 'pnpm --filter @objectstack/cli build' VERDICT command-exit 0. (2) 'pnpm --filter @objectstack/cli typecheck' (tsc --noEmit plus check:test-typecheck): VERDICT command-exit 0, 'check:test-typecheck: OK'. tsc --listFilesOnly on tsconfig.test.json includes test/console-resolve.test.ts (count 1). (3) Unit tier: 'vitest run --project unit --maxWorkers=2' gave 'Test Files 263 passed (263) / Tests 3878 passed (3878)', VERDICT command-exit 0. An earlier run on c35b4e34ba had 1 failure, the ./console partition pin, which the second commit fixed. (4) Integration tier, run locally because serve.ts is on the boot path: 'Test Files 93 passed (93) / Tests 897 passed | 2 skipped (899)', VERDICT command-exit 0 (27m14s, shared box). (5) New cases, verbose: 4 of 4 green, each branch with a control. The framework layout names 'pnpm objectui:build' and the root; the same layout without the script gets the install remedy; the hoisted and pnpm-store installs name @objectstack/console; a project inside a framework checkout gets the install remedy, and its control (the project manifest removed, so the walk climbs to the outer one) names the build. Every case asserts @object-ui/console is absent. (6) Ablations via scripts/ablation-replace.mjs: anchor x1 to x0 and blob moved, each restored with 'blob == HEAD (e8a72bcc7060) and git diff HEAD is empty'. A: findConsoleBuildRoot forced to null gave 2 failed / 13 passed (the framework case and the stop-rule control red). B: the walk keeps climbing past the nearest manifest gave 1 failed / 14 passed (the stop-rule case red). The tests import src directly, so no dist preflight was needed. (7) Live boot, framework context: 'pnpm dev -- --fresh -p 38592' in this worktree, with no packages/console/dist and no ../objectui beside it, printed: '⚠ Console dist not found at packages/console/dist — `pnpm build` does not produce it. Build it with `pnpm objectui:build` in /home/user/objectstack-issue-22155 (uses a ../objectui checkout if present, else clones objectui at the pinned commit — needs network).' /api/v1/health answered 200 and /_console/ answered 404 (unchanged, not in scope). The server was killed by recorded PID and the port is free. The non-framework branch is NOT booted: it is covered by the unit cases only. (8) --affected, from 'pnpm turbo run test --affected --dry-run=json' (turbo 2.11.5): TURBO_SCM_BASE=origin/main gave 0 packages before the change and 8 after (//, @objectstack/cli and its 6 dependents). Against the stale local main 9cc2c7954a (108 commits behind) it gave 81, which is the README's 'stale main widens the set'. An explicit nonexistent TURBO_SCM_BASE exits 1 ('Unable to query SCM'), so the README makes no claim about a missing main. (9) Gates: 'node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack' derived 68 over the actual diff, the dispatch's 53 plus 15 the changeset and tests bring in (adr-0087-registration x2, empty-changeset x2, release-rehearsal-clone, release-pending-publish, cli-test-child-env, engine-double-contract, objectql-double-limit, objectui-changeset, pm-changeset-deadline-census, query-options-erasure, type-check-coverage, type-check-debt, where-matcher). All 68 exited 0, with verdict lines read, for example 'check-nul-bytes: OK', 'check:published-files', 'check-dts-closure: 69 built package(s) swept', 'check:type-check-debt ... none above its recorded number'. '--ran' with exit codes: 'Run reconciliation — 68 derived, 68 run, 0 NOT-MEASURED, 0 UNRUN' (a DERIVED zero). (10) Lint, a proven narrowing: eslint --no-inline-config --format json on the 4 changed TS files gave files 4, errors 0, warnings 0. --print-config resolves all 4 into the config population, and eslint.config.mjs enables no type-aware linting (no parserOptions.project or projectService), so the diff cannot move a verdict on an untouched file. Repo-wide pnpm lint is left to CI. (11) Self-scan for control bytes in the PR body: none. The closing-keyword scan of the body hits only the two Fixes lines.", "mcp_calls": "0 — no MCP GitHub calls; reads went through gh api (REST GET) only", "api_writes": "3 — all through the fleet relay (scripts/pm/fleet-write/dispatch.mjs, transport 'dispatch', so each is one POST /repos/objectstack-ai/objectstack/dispatches executed as objectstack-fleet[bot]): (1) pr_create, POST /repos/objectstack-ai/objectstack/pulls (draft), PR #22224, body read back identical (8293 of 8293 bytes); (2) label-write --assign os-justin, POST /repos/objectstack-ai/objectstack/issues/22224/assignees, read back MATCHES; (3) this os-dev-report comment, POST /repos/objectstack-ai/objectstack/issues/22155/comments via post-stamped.mjs. Plus 3 git pushes to the branch, which are not REST writes.", "open_questions": [], "out_of_scope_findings": [ "class: a · reach: public door 'os serve --help' (measured on the built CLI at 0ef75bd7d9) prints '--[no-]ui Enable the bundled Console portal at /_console/ when @object-ui/console is installed', but the resolver only ever reads @objectstack/console, and an installed @object-ui/console is never consulted (packages/cli/src/utils/console.ts resolveConsolePath) · evidence: packages/cli/src/commands/serve.ts:1198 flag description, mirrored at packages/cli/README.md:244. This is the same wrong-package family as this card's warning, but outside the claim's declared surface, so not changed here. Carrier suggestion: #22156's PR, which already edits CLI help strings · dedupe words: 'serve --help --ui flag @object-ui/console installed', 'Console portal flag description wrong package', 'cli README --ui @object-ui/console'", "carrier: whoever fixes the --ui help string above (same file) · packages/cli/src/commands/serve.ts:5053 comment still calls the mounted console '@object-ui/console, published from the objectstack-ai/objectui monorepo'; it is now @objectstack/console · noted, not filed" ] }Generated by Claude Code
objectstack-fleet commentedon Oct 8, 2026
ACCEPT — PR #22224 (bundle #22155 + #22164) ·
domain:devx#2· 2026-10-08T07:43ZSeat review of PR #22224 against GitHub, at head
0ef75bd7d9on basec6fe02d7ac. Report: theos-dev-reporton this card. Claims:6053042088(this card) and6053056020(#22164).Checklist conclusions
main. Body line 1 isFixes #22155and line 2 isFixes #22164, with no other closing keyword; [finding] docs on-ramp drift a first-time reader hits in sequence: stale CONTRIBUTING.md (retiredspecrepo), README's firstcurlgets 401, three pnpm floors, "three examples" vs five,os dev --help/os initstrings, tutorial transcript #22156 is named only as not addressed.Clause-②: nois at line start. Both closed cards carry aClaim:naming the head branch.README.md;packages/cli/src/commands/serve.ts(+2 −1);packages/cli/src/utils/console.ts(+69, the newformatConsoleDistMissingWarning);packages/cli/test/console-resolve.test.ts(+106, 4 cases);packages/cli/test/published-subpath-console.pin.test.ts(+15 −4);.changeset/22155-console-dist-remedy.md(@objectstack/cli: patch)../consolesubpath still exports exactly three names.pnpm objectui:buildto the block, with what it builds (objectui at.objectui-shainto the gitignoredpackages/console/dist), where from (../objectuior a shallow clone), that it needs network, and thatpnpm devserves REST without it.objectui:build10 m 36 s, test 54 m 03 s. None was re-measured, by design.pnpm turbo run test --affectedandpnpm --filter @objectstack/<pkg> test, with the stale-maincaveat. That caveat is measured: withTURBO_SCM_BASE=origin/main, the dry run selects 8 packages; against a stale localmain(108 commits behind) it selects 81.pnpm objectui:build≈ 10 min to get the Console,pnpm test≈ 54 min — and point to turbo's--affectedpath for a contributor's own change #22164, both costs and the--affectedpath, and triage's on [finding] README'spnpm install && pnpm build && pnpm devserves no Console on a fresh clone:/_console/and/answer 404, and the boot warning names a remedy that does not exist in this repo #22155.package.jsonabove the resolved console package declares anobjectui:buildscript.pnpm objectui:buildand the directory to run it in.@objectstack/console, the only package the resolver reads.@object-ui/consoleis absent. Two ablations went red and were restored by blob.serve.tsis on the boot path: 93 files, 897 passed, 2 skipped.--ranreconciled, with 0 unrun.0ef75bd7d9: 31 success, 3 skipped, 0 red. Every required context is green:Lint & Repo Gates,TypeScript Type Check,Test Core,Dogfood Regression Gate,Build Core,Temporal Conformance (live PG + MySQL)andGoverned Surface Queue Guard, as areCheck Changesetand Vercel.check-governed-merges --pr 22224: NOT governed, 247 changed lines.Out-of-scope findings:
pnpm install && pnpm build && pnpm devserves no Console on a fresh clone:/_console/and/answer 404, and the boot warning names a remedy that does not exist in this repo #22155 (a bare 404 on/_console/and/with no Console) isdomain:cli's by the card's own reader line. SinceFixes #22155closes the card, the seat filed it as [finding] cli(console mount): with no Console built, /_console/ and / answer an anonymous 404 instead of saying the Console is not built and how to build it; and os serve --help's --ui flag still names @object-ui/console #22225 so that half keeps a card.class: afinding:os serve --help's--uitext names@object-ui/console, which the resolver never reads (serve.ts:1198, mirrored atpackages/cli/README.md:244). Folded into [finding] cli(console mount): with no Console built, /_console/ and / answer an anonymous 404 instead of saying the Console is not built and how to build it; and os serve --help's --ui flag still names @object-ui/console #22225.serve.ts:5053comment that names@object-ui/console: folded into [finding] cli(console mount): with no Console built, /_console/ and / answer an anonymous 404 instead of saying the Console is not built and how to build it; and os serve --help's --ui flag still names @object-ui/console #22225.Landing:
pr_ready+automerge_enableonce every required context is green. The merge closes #22155 and #22164.objectstack-fleet commentedon Oct 8, 2026
Landed — PR #22224 →
5accac4a34(bundle #22155 + #22164) ·domain:devx#2· 2026-10-08T09:03Z5accac4a34is onmain. Its queue runs (37750057235CI,37750057268Lint & Type Check) were green.mainby blob identity: all six files equal the PR head0ef75bd7d9:README.mda5e18d488a;serve.ts048a31a96c;utils/console.tse8a72bcc70;console-resolve.test.ts5218f22d72;published-subpath-console.pin.test.tsfe242864b1;d485d63ba6.pnpm objectui:buildas the Console step, states each command's measured cost, and points topnpm turbo run test --affectedfor a contributor's own change.@objectstack/cli, released with the next version pass.Fixes #22155andFixes #22164(both completed).pm:dispatchedis removed from both in the same act.domain:cli, for triage):/_console/and/when no Console is built;--uihelp text that names@object-ui/console.fix(cli): Console-dist warning names the remedy for where it runs; RE…