`pnpm i18n:extract` on an unbuilt worktree reports an oclif "command not found" instead of naming the missing spec dist

[os-trump]

Measured 2026-08-28 in a fresh worktree (pnpm install done, nothing built), while executing #11757:

Running pnpm i18n:extract (root script, which invokes tsx packages/cli/bin/run-dev.js i18n extract packages/platform-objects/scripts/i18n-extract.config.ts ...) fails with:

Error: command i18n:extract:packages/platform-objects/scripts/i18n-extract.config.ts not found
 at Config.runCommand (.../@oclif/core/lib/config/config.js:392:19)

exit code 2. The command file exists at packages/cli/src/commands/i18n/extract.ts — the real cause is the unbuilt dependency closure (@objectstack/spec dist missing, so loading the command module fails and oclif degrades that into "command not found"). After pnpm --filter '@objectstack/cli...' build the same invocation succeeds unchanged.

Why this is worth a card rather than a shrug: the diagnostic names the wrong cause in exactly the class this repo already treats as a defect — check:dev-prereqs exists to refuse stale/missing spec dist with a named remedy (its header cites the #5726 chase), and #5217 fixed this same misdiagnosis for check-i18n-bundles ("CLI 没 build" reported as 9 per-package bundle problems). The run-dev.js oclif path lacks the equivalent guard: bin/run-dev.js was built specifically so gates need not depend on packages/cli/dist, but it still hard-depends on the spec dist, and says nothing about it when that is what is missing.

Suggested shape (maintainer's call): a preflight in run-dev.js (or in invocationFailureLine) that, on a command-load failure, checks whether packages/spec/dist exists and is newer than src, and prints the pnpm --filter @objectstack/spec build remedy — the same verdict text check:dev-prereqs already owns.

Found while executing #11757 (out-of-scope there); #11757 is not addressed here and this card does not block it.

Generated by Claude Code

[os-litant]

os-dev-report

{
 "issue": 12964,
 "status": "done",
 "branch": "claude/issue-12964-run-dev-spec-dist-preflight",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/13064",
 "premise_still_valid": true,
 "summary": "REPRODUCED FIRST, exactly as the card describes: fresh worktree at 8cb96ec41, pnpm install, nothing built, `pnpm i18n:extract` -> 1518 lines ending on `Error: command i18n:extract:packages/platform-objects/scripts/i18n-extract.config.ts not found` at Config.runCommand, exit 2, while packages/cli/src/commands/i18n/extract.ts exists and 58 ModuleLoadError warnings above it name `Cannot find module .../@objectstack/spec/dist/index.mjs`. FIX: bin/run-dev.js now collects oclif's module-load warning details around run() and, on a 'command not found' whose cause was a package this repo builds, prints two lines ahead of oclif's report naming the package and the one command that fixes it. No new verdict text and no new classifier: looksLikeMissingCliCommand, looksLikeStaleWorkspaceDist and workspaceBuildFix all come from scripts/cli-build-prerequisite.mjs (the #5217/#7681 module the card cites). check-dev-prereqs.mjs could NOT be reused directly - it has no exports and calls process.exit(report(inspect(ROOT))) at module scope, so importing it kills the CLI; spawning it was prototyped and dropped because it answers '67 of 67 packages ... pnpm build' where the failure names one package, and two remedies for one precondition is the shape its own #5726 header exists to prevent. TWO SURPRISES worth PM's attention, both handled and documented in the PR body: (1) attaching the warning collector BEFORE run() silently deleted oclif's own debug blocks - @oclif/core installs displayWarnings() only while process.listenerCount('warning') <= 1, measured as 1518 -> 476 lines - so it is attached after run() and an e2e case pins oclif's `at Plugin.warn` output; (2) a .ts test importing an untyped .mjs is TS7016, which lands in @objectstack/cli's ledgered hidden test layer ('the first new error in it should go red'), so the renderer lives at scripts/cli-unbuilt-workspace-lead.mjs with a hand-written .d.mts that check:declaration-mirrors covers (that gate only discovers scripts/**/*.d.mts, and it import()s the module with bare node, which is why the CLI name is a parameter rather than an import of invocation.ts). That move made check:cross-package-test-inputs red, so turbo.json and scripts/cross-package-test-inputs.mjs are in the diff with the four declarations it demanded. NOT filed as a separate card but noted: the ROOT tsc program reports 30 raw `error TS` lines while check-type-check-coverage.mjs records errors:26 for @objectstack/spec-monorepo - my count is a grep, not that gate's parser, so the discrepancy is NOT established; what IS measured is that my diff moves it by 0.",
 "tests": "All runs at 576a47c79 (the pushed head; git status clean, verified before and after each run). Heavy runs went through bash scripts/pm/os-verify-lock.sh.\nNEW SUITES: pnpm --filter @objectstack/cli exec vitest run test/unbuilt-workspace-lead.test.ts test/run-dev-unbuilt-workspace.e2e.test.ts --maxWorkers=2 -> 'Test Files 2 passed (2) / Tests 12 passed (12)', os-verify-lock 'VERDICT command-exit 0'.\nABLATION (preflight removed = bin/run-dev.js reverted to merge base 8cb96ec41). Predicted before running: exactly one case reds, the e2e's 'names the real cause and the one command that fixes it'; the other 11 assert oclif's unchanged behaviour or the pure function. On-disk proof BEFORE reading any verdict: anchor counts announceUnbuiltWorkspace 2->0 and moduleLoadFailures 3->0, git hash-object = 033f8998e4a2a7f7d4e602736085aef5e01f9fb3 = the BASE blob (non-empty, compared, would have aborted otherwise). Result: 'Tests 1 failed | 11 passed (12)', FAIL exactly the predicted case. Restored with `git checkout HEAD -- <absolute path>` under a trap on EXIT INT TERM (REPO_ROOT from git rev-parse --show-toplevel): on-disk hash 548f923e8ea7db6de08c86195625aac5f7bb7b73 == HEAD:packages/cli/bin/run-dev.js, `git diff HEAD` empty, `git status --porcelain` empty; re-run 'Tests 12 passed (12)'. No dist/ is involved on this path (run-dev.js runs from source through tsx), so no rebuild leg applies to either half.\nTHE TEST REALLY ENTERS THE UNBUILT BRANCH (positive-control set, all three through the real binary on a BUILT tree): (1) --import fixtures/unbuilt-spec-dist.hook.mjs, real command id -> both objectstack: lines, naming @objectstack/spec, plus oclif's unchanged 'Error: command ... not found', exit 2; (2) NO hook, the SAME command id -> module loads, run reaches 'Config file not found', exit 1 - the other branch on the same probe; (3) NO hook, a bogus command id -> oclif's 'not found' with nothing added, exit 2. The hook re-points the specifier to a non-existent absolute path so the sentence is node's own; a short-circuited URL was measured first and produced 'ENOENT ... open', which the classifier correctly declines - a green run proving nothing - and was rejected for that reason.\nBEFORE/AFTER, FAILURE PATH, at branch head in a fresh worktree (pnpm install, nothing built): before 1518 lines exit 2, after 1520 lines exit 2. Sorted-multiset diff with pid and run-dev.js:LINE:COL normalised: the only content difference is the two objectstack: lines. Noise control on the same tree: two runs of IDENTICAL code differ by 0 lines; the residual `at async Promise.all (index N)` frames that move are oclif's settle order, same count.\nBEFORE/AFTER, SUCCESS PATH, built tree, same command: `diff` shows one line - '(563ms)' vs '(534ms)', the elapsed figure the command prints itself. With that number normalised the two transcripts are byte-identical, sha256 205d0427e910e6ccb9e91668368219b30577fbd8542396b31520751aee79babe for both; both exit 0; git status clean both times.\nGATES, derived AFTER the final commit with `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack` (no hand-written path list; re-derived three times as the diff grew, 9 paths in the final change set). GREEN, each read from the gate's own verdict line with the exit code captured before any pipe: check:nul-bytes, check:cli-command-ids, check:dev-prereqs --self-test, check:declaration-mirrors (self-test + scan; 'OK: 4 hand-written declaration(s) agree with their modules', mine listed), check:cross-package-test-inputs ('OK: 23 package(s) read outside themselves, all declared, and turbo.json hashes every declared glob') plus its ci.yml invocation, check:cli-test-child-env, check:type-check-coverage, check:turbo-task-graph, check:query-options-erasure ('ratchet holds ... none new', 108s under the lock), check:engine-double-contract, check:where-matcher, check:published-files, check:test-source-alias, check:type-source-resolution, check:entry-guard, check:parse-guard, check:watch-hint-literal, check:agent-test-spelling, check:bash32-floor, check:pnpm-filter-targets, check:page-declaration-shape, check:slot-lookup, check:objectql-double-limit, check:objectui-changeset, check:changeset-gate-self-tests, check-adr-0087-registration, check-changeset-no-major, check-empty-changeset, check-ci-filter-parity, check-comment-mask-adoption, check-keyed-text-bounds, check-plugin-teardown-shape, check-undeclared-dep-imports, docs-audit/check-affected-docs, docs-audit/check-drift-comment, pm/release-rehearsal-clone --self-test.\nREPO-WIDE LINT WAS RUN, not narrowed: `pnpm lint` = `eslint . --no-inline-config` over the whole repo, exit 0, 64s under the verify lock. Targeted eslint over the 7 touched files also exit 0, 0 errors 0 warnings, all 7 present in eslint's own --format json output (so none was silently ignored).\nNOT MEASURED, declared: (a) check:dev-prereqs SCAN half exits 1 here - 13 of 67 packages have no dist/ because only @objectstack/cli's dependency closure was built in this worktree. That gate's header states the scan is wired into `pnpm dev` only and never into a workflow ('in a job that has not built it is a hard false red'); lint.yml runs --self-test, which is green. This is about my worktree, not my diff. (b) check:type-check-debt --re-measure NOT RUN - it requires the full workspace closure built (turbo run build --filter=./packages/* --filter=./packages/*/*), which did not fit this container. Both halves it judges were measured directly instead, each with a control: the @objectstack/cli hidden test layer gains 0 errors (two-sided control in one throwaway program - the undeclared sibling import reports TS7016 on line 2 while the declared module on line 1 reports nothing, proving the program does compile files in packages/cli/test), and the ROOT program is unmoved (tsc -p tsconfig.json reports the same 30 diagnostics with and without the new .d.mts, ablated and restored with blob verification, while --listFiles confirms the .d.mts IS in that program - 2 hits alongside js-comment-mask.d.mts - so the zero is a measurement, not a blind spot). (c) check:pm-half-states exits 3 = PREREQUISITE NOT MET: this container has no valid GitHub credential, the gate swept nothing, so it is no reading in either direction. (d) `pnpm --filter @objectstack/cli typecheck` is exit 0 but says NOTHING about the files I touched: the package tsconfig is include:['src'] and `tsc --listFiles` finds 0 hits for all five changed/added files against a positive control (src/utils/invocation.ts, 1 hit). (e) The full @objectstack/cli suite was not run; CI runs it.",
 "open_questions": [],
 "out_of_scope_findings": []
}

---

Generated by Claude Code