fix(cli): os doctor stops guessing the installed-package ledger directory when the authority export is missing (#5996)

[os-project-manager]

Fixes #5996

诚实定性:加固诊断边界,不是修活缺陷

DEFAULT_INSTALLED_PACKAGES_DIR 在所有已发布版本中都存在,被删掉的 ?? 从未真正触发过——本 PR 不修复任何今日用户可踩到的缺陷。它加固的是 #5644 划出的那条边上的最后一格:#5644 把「装了但加载不了」(present but unloadable)从静默里拆出来,这里补上「加载了但不被认得」(loaded but unrecognizable)。

三件一组(立单人定义,缺一不可)

1. 去掉 ?? 兜底(readInstalledPackageEntries())。该导出是「ledger 目录叫什么」的唯一权威(PD Add comprehensive test suite for Zod schema validation #12:producer 是契约,consumer 不得用 ?? 容忍);同一函数两行之下就是 LocalManifestSource.list() 静默丢弃损坏的 ledger 条目 —— 已装应用在 boot 时消失、在控制台列表里缺席,且没有任何一条日志 #5413 留下的、明令禁止这种写法的注释。现在导出在 path.join() 之前做类型检查——顺带退役了旧注释记录的误报路径(非字符串导出曾被 config catch 吸收、误报为 "Could not load config for analysis")。
2. 导出缺失 → 具名报告行 installedPackageLedgerDirAuthorityMissingCheck(installedPackageLedgerReaderFailureCheck 的近亲):"The installed-package ledger reader does not declare the ledger directory (installed packages NOT checked)"。该状态下 doctor 不读任何猜测目录;报告行里也刻意不出现任何路径——doctor 刚失去的正是那个知识,与 os doctor 把「cloud-connection 没装」和「装了但加载不了」当成同一件事 —— ledger 目录在场也照打 clean bill(#5412 假 PASS 的上一层) #5644 拒绝其 option B 同理。D5e advisory 同步扣下 ✓ Unique scope(ledgerReadingIsComplete 计入第四种不完整)。
3. installedPackageLedgerSkippedEntriesCheck 的 fix 引用真实 dir:reading 现在携带解析出的目录(InstalledPackageLedgerReading.dir,权威导出读取成功即在),fix 里 Under 后引用它,取代写死的 Under .objectstack/installed-packages/: 字面量——那句字面量就是同一个猜测的 prose 版。

前提核验(origin/main e39dd66e7)

• ?? 仍在 packages/cli/src/commands/doctor.ts L988;
• 导出仍在 packages/cloud-connection/src/index.ts L41(值在 local-manifest-source.ts L163);
• 前提成立,无移动/改名。@objectstack/cloud-connection 本 PR 未动。

反向验证(方向先于运行记录)

预测(先写入 scratchpad 再跑):临时回滚两处(恢复 ?? 与字面量)后,新增 11 例中 5 红 6 绿——2 个 skipped 单元例、2 个 authority e2e、1 个 resolved-dir e2e 变红;6 个直接调用新 check 函数的单元例保持绿(它们钉措辞与形状,不钉可达性;可达性由 e2e 钉,此排除如实记录)。

实测:完全一致——11 tests | 5 failed,红的正是预测的 5 例。方向承载者是「fake LocalManifestSource 构造计数 = 0」与「guessed listing 的产物(invoice.code / broken.json / skipped 行)不得出现在报告里」;单靠 ✓ Unique scope 缺席不能承载方向(guessed 目录里有 global unique 时 advisory 自己也会扣掉它),测试注释里写明了这一排除。

测试与门禁(全部本地实测)

• 新增 doctor-ledger-dir-authority.test.ts:11/11 绿(单元 8 + e2e 3)。e2e 走 doctor 既有的 loader-seam 动态 import 替身惯用法(../utils/optional-package.js + vi.resetModules + fresh import),模拟「加载成功但无该导出/导出非字符串」的模块形状;resolved-dir e2e 走真实 @objectstack/cloud-connection,带 doctor-ledger-read-failure.test.ts 整块 7 条在 origin/main 上就是红的 —— os doctor 对坏 ledger 一行都不报，#5413/#5424 的报告面测不出来 #5612 preflight。
• pnpm --filter @objectstack/cli test:95 files / 988 tests 全绿,exit 0。
• pnpm --filter @objectstack/cli typecheck:exit 0。
• pnpm lint(全仓 eslint . --no-inline-config):exit 0。
• lint.yml 的 check:* 家族逐项本地跑过,35 项全 PASS(slot-lookup、query-options-erasure、verify-stand-in、nul-bytes、doc-authoring、docs-audit-scope、role-word、quick-reference-counts、adr-anchors、org-identifier、authz-resolver、service-providers、route-envelope、error-code-casing、wildcard-fallthrough、meta-type-normalized、init-service-contract、durability-log-level、startup-registry-verdict、objectui-changeset、release-notes、release-body、node-version、workflow-status-functions、shard-attestation、published-files、engine-double-contract、resume-authority-declared、merge-driver、spec-parsed-alias、type-check-coverage、stall-guard、skill-frame-sync、skill-compatibility、driver-conformance)。spec 未动,生成物门禁不受影响。

变更面

• packages/cli/src/commands/doctor.ts(唯一源码文件)
• packages/cli/src/commands/doctor-ledger-dir-authority.test.ts(新)
• .changeset/doctor-ledger-dir-authority.md(@objectstack/cli patch——新报告行是用户可见的诊断面扩展,故有 changeset,无需 skip-changeset)

范围外发现(PD #10)

• CLI 里仍有两处把 DEFAULT_INSTALLED_PACKAGES_DIR 的取值复述成字面量(#5996 三件套之外的残留) #6643:两处残留的字面量复述(installedPackageLedgerFailureCheck 的 fix、package/install.ts 的提示 prose),观察类,留 finding,未在本 PR 顺手扩。

🤖 Generated with Claude Code

https://claude.ai/code/session_017uFVNMmTxLpmfQYiuKM1Yx

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 8, 2026 8:23am

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/cli.

21 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/ai/skills-reference.mdx (via packages/cli)
• content/docs/api/client-sdk.mdx (via @objectstack/cli)
• content/docs/api/data-flow.mdx (via @objectstack/cli)
• content/docs/api/environment-routing.mdx (via @objectstack/cli)
• content/docs/api/error-catalog.mdx (via @objectstack/cli)
• content/docs/automation/hook-bodies.mdx (via packages/cli)
• content/docs/deployment/backup-restore.mdx (via @objectstack/cli)
• content/docs/deployment/cli.mdx (via @objectstack/cli)
• content/docs/deployment/self-hosting.mdx (via @objectstack/cli)
• content/docs/deployment/validating-metadata.mdx (via packages/cli)
• content/docs/getting-started/your-first-project.mdx (via @objectstack/cli)
• content/docs/kernel/runtime-services/data-service.mdx (via @objectstack/cli)
• content/docs/kernel/runtime-services/index.mdx (via packages/cli)
• content/docs/permissions/authentication.mdx (via @objectstack/cli)
• content/docs/plugins/index.mdx (via @objectstack/cli)
• content/docs/plugins/packages.mdx (via @objectstack/cli)
• content/docs/protocol/kernel/plugin-spec.mdx (via @objectstack/cli)
• content/docs/protocol/kernel/realtime-protocol.mdx (via @objectstack/cli)
• content/docs/releases/implementation-status.mdx (via @objectstack/cli)
• content/docs/releases/v16.mdx (via @objectstack/cli)
• content/docs/releases/v17.mdx (via @objectstack/cli)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.