Skip to content

[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

@objectstack-fleet

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 :3000

On 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:

  1. 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 inside objectstack-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/), and pnpm check:console-sha` already prints exactly that line one step earlier. The two messages disagree on the same boot.
  2. The absence is not loud at the HTTP surface. With no Console, GET / returns 404 with an empty body and GET /_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 port

Boot 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 fine

For 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:build is the extra step (and that it needs network or a ../objectui checkout), matching examples.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 bare ENDPOINT_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

  1. objectstack-fleet commented on Oct 8, 2026

    @objectstack-fleet
    ContributorAuthor

    Path: the road — start: a contributor sees the Console | 缺项 | P2

    Triage: first grade, bug · priority:p2 · domain:devx · area:devpath · pm:queue (finding removed). Direction: the README names the Console step, and the boot warning names a remedy that exists

    Triage 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.md is that lane's; the warning text is declared to domain:cli cross-lane. Read on main ec8f37c890.

  2. objectstack-fleet commented on Oct 8, 2026

    @objectstack-fleet
    ContributorAuthor

    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_01VF48aw8RPG6wzDnMgp6rtw
    Account: os-justin (the seat's linked user as GET /user answers it; the cards' assignee)
    Branch: claude/issue-22155-readme-contributor-path (new, cut from origin/main 6ed0c0f3e5)
    Worktree: objectstack-issue-22155
    Domain: domain:devx
    Seat: domain:devx#2
    Cards closed by the one PR: #22155 (p2, this anchor) and #22164 (p3, the maintainer's ③; a pointer claim is on that card).
    File surface:

  3. objectstack-fleet commented on Oct 8, 2026

    @objectstack-fleet
    ContributorAuthor

    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

  4. objectstack-fleet commented on Oct 8, 2026

    @objectstack-fleet
    ContributorAuthor

    ACCEPT — PR #22224 (bundle #22155 + #22164) · domain:devx#2 · 2026-10-08T07:43Z

    Seat review of PR #22224 against GitHub, at head 0ef75bd7d9 on base c6fe02d7ac. Report: the os-dev-report on this card. Claims: 6053042088 (this card) and 6053056020 (#22164).

    Checklist conclusions

    • Shape: draft PR to main. Body line 1 is Fixes #22155 and line 2 is Fixes #22164, with no other closing keyword; [finding] docs on-ramp drift a first-time reader hits in sequence: stale CONTRIBUTING.md (retired spec repo), README's first curl gets 401, three pnpm floors, "three examples" vs five, os dev --help / os init strings, tutorial transcript #22156 is named only as not addressed. Clause-②: no is at line start. Both closed cards carry a Claim: naming the head branch.
    • Files (+238 −9):
      • README.md;
      • packages/cli/src/commands/serve.ts (+2 −1);
      • packages/cli/src/utils/console.ts (+69, the new formatConsoleDistMissingWarning);
      • 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).
      • The helper and its tests sit inside the claim's "minimum code that decides which remedy to name". The pin edit records the new export as internal, so the published ./console subpath still exports exactly three names.
    • README, read in the diff:
    • CLI: the warning now picks one remedy by whether the nearest package.json above the resolved console package declares an objectui:build script.
      • In the framework repo it names pnpm objectui:build and the directory to run it in.
      • Elsewhere it names a reinstall of @objectstack/console, the only package the resolver reads.
      • The 4 cases each have a control, and every case asserts @object-ui/console is absent. Two ablations went red and were restored by blob.
      • A live boot in the framework context printed the new line.
    • Tests and gates:
      • CLI build and typecheck: exit 0.
      • Unit tier: 263 files, 3878 tests passed.
      • Integration tier, run locally because serve.ts is on the boot path: 93 files, 897 passed, 2 skipped.
      • Gates: 68 derived over the actual diff (the dispatch's 53 plus 15 the changeset and tests bring in), 68 run, all exit 0. --ran reconciled, with 0 unrun.
    • CI at head 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) and Governed Surface Queue Guard, as are Check Changeset and Vercel. check-governed-merges --pr 22224: NOT governed, 247 changed lines.

    Out-of-scope findings:

    Landing: pr_ready + automerge_enable once every required context is green. The merge closes #22155 and #22164.

  5. objectstack-fleet commented on Oct 8, 2026

    @objectstack-fleet
    ContributorAuthor

    Landed — PR #22224 → 5accac4a34 (bundle #22155 + #22164) · domain:devx#2 · 2026-10-08T09:03Z

    • Merged through the merge queue at 2026-10-08T09:01Z. The squash commit 5accac4a34 is on main. Its queue runs (37750057235 CI, 37750057268 Lint & Type Check) were green.
    • Verified on main by blob identity: all six files equal the PR head 0ef75bd7d9:
      • README.md a5e18d488a;
      • serve.ts 048a31a96c;
      • utils/console.ts e8a72bcc70;
      • console-resolve.test.ts 5218f22d72;
      • published-subpath-console.pin.test.ts fe242864b1;
      • the changeset d485d63ba6.
    • Effect:
      • README "Hack on the framework" names pnpm objectui:build as the Console step, states each command's measured cost, and points to pnpm turbo run test --affected for a contributor's own change.
      • The CLI's "Console dist not found" warning names the remedy that works where it runs: a patch for @objectstack/cli, released with the next version pass.
    • Closed by Fixes #22155 and Fixes #22164 (both completed). pm:dispatched is removed from both in the same act.
    • Not done here, carried by [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 (domain:cli, for triage):
      • the bare 404 on /_console/ and / when no Console is built;
      • the --ui help text that names @object-ui/console.
  6. added a commit that references this issue on Oct 9, 2026
    5accac4
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

area:devpathThe road — create, dev, verify, publish/install, connect an agent, iteratebugSomething isn't workingdomain:devxpriority:p2Medium: important, M3

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions