fix(cli): make serve's host importer reachable from anywhere, and sweep for the class

[os-elon]

Fixes#10769

serve.ts reaches app-declared optional packages through createHostImporter,
which anchors resolution at the app being served. The helper was bound as a
const partway down one very long boot method, so it existed only below its
own binding — and a load written above that point is not a compile error.
The author simply writes a bare import(), which resolves against the CLI's own
realpath and works fine in a dev checkout where everything is hoisted into one
node_modules. It breaks only in a real distribution layout, at boot, in
production. That is how it reached a published EE image, twice:

• cloud#1013 — binding below the auth block; cost the enterprise
  @objectstack/organizations load, so every walled-posture deployment hit the
  ADR-0093 D5 fail-fast and exited 1.
• cli: serve's dynamic cluster-driver import cannot resolve app-declared @objectstack/service-cluster* — EE multi-node OS_CLUSTER_DRIVER=redis dies at boot #10645 — binding below the cluster block; OS_CLUSTER_DRIVER=redis died at
  boot with Cannot find package '@objectstack/service-cluster', and compose's
  service_completed_successfully took the whole stack down with it.

PR #10765 hoisted the binding above the cluster block, which addressed that
instance and left the class open: the next load added above the new line
reproduces it exactly, and no author has any reason to know where that line is.

1. Structural — the hazard is now unrepresentable

importFromHost is a module-scope function declaration. A function
declaration is hoisted over the entire module, so every line of serve.ts
reaches it in any order: "above the definition" is no longer a state this file
can be in, and there is no line number for a future author to have to know.

The underlying importer is memoised per host root, so one boot still shares a
single host require, exactly as the one mid-function const did. hostRoot
stays where it was for its other readers; the helper defaults to the same
process.cwd(), and there is no process.chdir anywhere in packages/cli/src.

2. Detection — the scan is widened to the whole class

serve-cluster-host-resolution.test.ts scanned the cluster pair. It now sweeps
every app-declarable optional load, classified mechanically rather than
from a hand-kept list: a package is app-declarable exactly when
packages/cli's own package.json does not declare it — which is precisely the
set a bare import() from the CLI cannot resolve except by accident of workspace
hoisting. A newly added optional package is therefore covered the moment it is
added, with nobody having to remember this test exists.

The sweep reads code only. serve.ts discusses import() in prose throughout its
comments (including the note describing this very defect), and a naive scan
matches that prose — 4 of 46 raw matches were comments. A comment stripper that
preserves byte offsets removes them, and is itself pinned in both directions.

Vacuity guards (the pattern from PR #10882 — a sweep asserting "nothing is
wrong" passes trivially when it matches nothing):

• floors on sites found, packages resolved, and manifest entries read;
• the four known app-declarable loads asserted by name, which proves the
  resolver still handles all three spellings serve.ts uses (a const binding, a
  template prefix, and the manifest cross-check);
• a stripper guard pinning that prose is removed and that real code survives.

3. One live instance the sweep found

@objectstack/service-i18n was loaded with a bare import(). packages/cli does
not declare it, so an app carrying its own copy could only ever be found by
accident of hoisting — green in a dev checkout, absent on a real install layout.
It is the same defect class as the card, mechanically fixed with the instrument
already established in this file, in a file no other claim holds. Named here
because a fix nobody points at is unreviewable.

createHostImporter is a strict superset of a bare import() for a bare package
name — undeclared falls back to the CLI's own resolution — so the quiet
"i18n not installed, use the kernel fallback" path is unchanged.

Fences

• The createHostRequire 认 NODE_PATH，于是 #4699 立下的「host app 必须自己声明」在 pnpm 工作区里根本没被强制 #4719 declaration gate is untouched. Its pin — "still refuses a package
  the app does not declare (the gate is unchanged)" — is green and unmodified.
  Nothing here widens or relaxes what serve accepts.
• Nothing about what serve binds, listens on, or advertises moves. This
  changes only where a module resolves from, plus what a source scan asserts.
• Nothing under content/docs/releases/; the changeset is the release-notes input.

Two assertions deliberately replaced — please read this as the diff's one judgement call

The scan carried two assertions that pinned the mid-function const shape
itself: that the definition's index is below the cluster block's, and that
const importFromHost = occurs exactly once. The structural half removes that
shape by design, so neither can survive verbatim. They were replaced by
strictly stronger checks, not dropped:

was	is now
definition index is above the cluster use	definition is at module scope (column 0), so it is above every line; a nested or indented declaration fails
exactly one const importFromHost =	exactly one module-scope declaration and exactly one createHostImporter( call; anyconst/let/var importFromHost fails

The old check could only notice a load that had already been placed above the
binding. The new one fails the moment the helper stops being reachable from
everywhere — the cause rather than the symptom. No threshold moved, no baseline
raised, nothing skipped or quarantined. Flagging it explicitly because "the
assertion turned red so I rewrote it" is the shape this repo does not accept, and
a reviewer should confirm the replacement is the stronger reading.

Verification

Union of the derived gate families run on the final commit bb14311793.
node scripts/pm/dispatch-gates.mjs derived the set from the merge-base change
set itself (3 paths) rather than from a hand-written list; all 19 reachable
families exit 0, e.g.

• check-engine-double-contract: OK — 376 pinned, 133 in the DEBT ledger, 2 exempt.
• check-nul-bytes: OK (scanned 6297 text file(s) ... no raw ASCII control bytes).
• where-matcher conformance holds: 275 matcher(s) discovered ... none new.
• OK: 13 package(s) read outside themselves, all declared (cross-package-test-inputs)

The ratchet family needs a built closure, so it was run the way lint.yml does
(turbo build over ./packages/*, then --re-measure), on bb14311793:

• check-type-check-coverage --re-measure: OK — 33 ledger entr(ies) re-measured in 340.5s, 1908 raw tsc error(s) total, none above its recorded number.

This one matters here rather than being boilerplate: @objectstack/cli is in
TEST_DEBT (146 raw errors across 65 files), so its hidden test tree is measured
by this gate and not by pnpm --filter @objectstack/cli typecheck — the new
scanner code in the test file is real TypeScript that this ratchet compiles.

pnpm --filter @objectstack/cli test — 146 files, 1617 tests, all passed.
pnpm --filter @objectstack/cli typecheck — clean. The widened file on its own:
12 passed.

Reverse verification (both legs; the scan's subject is serve.ts read from
source with readFileSync, not through dist/, so no rebuild can stale these
— the only built dependency, @objectstack/types/node, is used by the fixture
tests, which were not ablated):

• reverting the i18n load to a bare import() → 2 red, naming
  serve.ts:1833 import(i18nPkg) → @objectstack/service-i18n;
• turning the module-scope declaration back into a const arrow → 2 red on the
  module-scope and single-importer pins.

Each restore leg was git checkout HEAD -- serve.ts, confirmed byte-identical.

The first run of the second leg came back 3 red, not the 2 predicted — the
extra failure was the stripper guard, which had used function importFromHost(
as its "real code survived" marker and so doubled as a second shape check. That
coupling is fixed in its own commit; the re-run then matched the prediction
exactly.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/cli, touching 4 documentable anchor(s).

16 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json 58563be069a70d09c4d9cc5f522bb27c5f8a78b2.

⛔ 4 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• 1 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 45 of 221 client-bound route-ledger rows — the other 176 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run: node scripts/docs-audit/affected-docs.mjs --bridge-coverage

Coarse fallback — 23 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 58563be069a70d09c4d9cc5f522bb27c5f8a78b2 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 62cca2462a65c53c57283b4022ca53f1e23a82ae — the merge of head bb14311793891c201111620f45e8a910e39effbc into base 58563be069a70d09c4d9cc5f522bb27c5f8a78b2, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 62cca2462a65c53c57283b4022ca53f1e23a82ae && git checkout 62cca2462a65c53c57283b4022ca53f1e23a82ae
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 58563be069a70d09c4d9cc5f522bb27c5f8a78b2 bb14311793891c201111620f45e8a910e39effbc && git checkout -B drift-repro 58563be069a70d09c4d9cc5f522bb27c5f8a78b2 && git merge --no-ff bb14311793891c201111620f45e8a910e39effbc
node scripts/docs-audit/affected-docs.mjs --json 58563be069a70d09c4d9cc5f522bb27c5f8a78b2

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 58563be069a70d09c4d9cc5f522bb27c5f8a78b2 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[github-actions]

⛔ merge queue 构建失败 — 先分诊，再决定要不要重排

队列构建 32510007801 红了。队列跑的是全量套件（PR 侧 CI 只跑 affected 子集），
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

失败的 job（日志抽取，best effort）：

• Console Pin Gate — 失败步骤: Build the Console SPA at the pinned objectui SHA

  ✗ Build failed in 6.22s
  

↳ 失败原因 是判读的关键：超时（Test timed out in … / Hook timed out in …）多半是负载/时序，不是本 PR 的回归；
断言（AssertionError: …）才指向真实的行为改变。两者的 FAIL 行长得一模一样，只有这一行能区分。

跨 PR 相同签名（24h，按失败测试文件聚合）：

• ⚠️本次没有可用的聚合签名（日志里没有能解析出测试文件名的 FAIL 行）—— 这不是「没有同签名的其他 PR」，是这一轮没测到。跨 PR 聚合本次不可用，请手工比对其他 PR 的同类评论。
• ⚠️ 24h 评论账本没读完（超过 5 页仍未读到窗口尽头），所以上面的「不同 PR 数」是下界，不是全量。

历史信号：

• 本 PR 过去 24h 无队列失败记录（首次）。
• 过去 24h 队列共有 43 个失败构建（不含本次）。

分诊清单：

1. 失败测试在本 PR 改动的包里 → 真回归，修 PR。
2. 失败测试与本 PR 无关 → 看上面的「跨 PR 相同签名」；已有汇总 issue ⇒ flaky/环境问题实锤，去那张 issue 上谈，修好前重排只会再烧一轮全队列。
3. 两者都不是 → 可能与同组 PR 语义冲突；等前面的 PR 落地或失败出队后再重排一次即可，不要连续重排。

---

Generated by Claude Code · merge-queue-triage workflow (#4859)