healProfilesModuleFallback() 遇到损坏的 package.json 时抛裸 SyntaxError，不带文件路径

[Fable-Forge]

TL;DR (EN) — When any dependency package.json in the resolution walk is corrupt,
healProfilesModuleFallback() throws a bare SyntaxError: Unexpected end of JSON input
with no indication of which file failed. With ~600 package.json files in the tree,
this is very hard to diagnose. Please rethrow with the offending path.

环境

• @deepseek-ai/dsh-app-boot@0.1.0-rc.6
• Node.js v24.19.0，Windows 11 (10.0.26200)

现象

healProfilesModuleFallback() 会沿依赖树逐个读取 package.json。
其中任意一个文件损坏（内容被截断 / 变成 0 字节），抛出的是裸的 JSON 解析错误，
完全不提是哪个文件：

SyntaxError: Unexpected end of JSON input
    at JSON.parse (<anonymous>)
    at healProfilesModuleFallback (...\@deepseek-ai\dsh-app-boot\lib\index.js:430:19)
    at prepareProfile (...\@deepseek-ai\dsh\lib\profile-boot-*.js:141:2)
    at composeProfile (...\profile-boot-*.js:167:18)
    at runProfile (...\profile-boot-*.js:221:19)
    at ...\@deepseek-ai\dsh\lib\bin.js:133:9

相关代码

@deepseek-ai/dsh-app-boot/lib/index.js 的 healProfilesModuleFallback()：

// :425 附近 —— installAnchor 自身
const appManifest = JSON.parse(readFileSync(installAnchor, "utf8"));
...
// :430 附近 —— 遍历依赖时
const manifestPath = join(dir, "package.json");
queue.push({
  anchor: manifestPath,
  manifest: JSON.parse(readFileSync(manifestPath, "utf8")),   // <- 这里
});

两处 JSON.parse(readFileSync(...)) 都没有把路径带进错误。

期望

抛出的错误里包含出错文件的绝对路径，例如：

Error: dsh: failed to parse package manifest
       C:\...\_npx\<hash>\node_modules\node-pty\package.json
       (file may be truncated or corrupt): Unexpected end of JSON input

同一文件里的 readProfileManifest() 已经做得很好（failed to read profile manifest ${path}），
建议这里保持一致：

function parseManifest(path) {
  let raw;
  try { raw = readFileSync(path, "utf8"); }
  catch (error) { throw new Error(`dsh: failed to read manifest ${path}: ${String(error)}`); }
  try { return JSON.parse(raw); }
  catch (error) { throw new Error(`dsh: failed to parse manifest ${path} (truncated or corrupt?): ${error.message}`); }
}

影响

我们排查一次真实故障时，这条错误是第一个岔路口。当时依赖树里约有 600 个
package.json，报错不指名文件，只能自己写脚本逐个扫 0 字节文件才定位到
是 node-pty/package.json 等 6 个文件被环境（透明加密 DLP）弄坏了。
带上路径的话，这一步大概能省掉半小时以上。

相关

这三件事是同一次故障排查里发现的：

• Recoverable startup mode for incompatible optional plugins #2920 —— 单个插件导入失败会终止整个进程（我在那边补了确定性复现）
• `dsh web` 在插件树加载完成前就对外提供 HTTP，外部无法判断“真的起好了” #3320 —— HTTP 先于插件树加载完成就对外服务，外部无法判断就绪

[GCSimba]

Thanks @Fable-Forge for the precise report and reproduction direction.

I reproduced both forms on master at 141eb6fef83422698aef7a981029e843e8161534: a malformed installation anchor manifest and a malformed transitive dependency manifest both escape healProfilesModuleFallback() as a bare SyntaxError, without the path of the corrupt package.json.

The fallback walker parses manifests at two points with inline JSON.parse(readFileSync(...)) calls. In a large installation closure, the parser message alone cannot identify which artifact needs repair.

I prepared a narrow patch that:

• routes both parsing sites through one private readPackageManifest() helper;
• keeps readFileSync() outside the parse try block, so native filesystem errors retain Node's path and error code;
• wraps only JSON.parse() failures with an absolute manifest path and parser detail;
• preserves the original SyntaxError as cause; and
• covers the installation anchor and a nested dependency independently through the public fallback-healing entry point.

Fork commit: d5ccb6197f985dbe1b1dbab8040c4052f7d750d4

Branch: codex/fix-profile-fallback-manifest-diagnostics

Validation:

• pnpm exec vitest run packages/boot/app-boot/tests/profile.spec.ts --coverage --coverage.include='packages/boot/app-boot/src/profile.ts' — 16/16 tests passed; profile.ts reached 100% statements, branches, functions, and lines.
• pnpm run build — passed.
• pnpm run lint — passed.
• pnpm run doc-sync — 27 of 28 checks passed; only the symlink verifier was blocked on this Windows checkout by EPERM while inspecting existing repository symlinks.
• Repository commit and pre-push hooks completed successfully.

Successful traversal, dependency ordering, symlink ownership, exports, and profile formats are unchanged. The patch does not attempt to repair or delete a corrupt installed manifest; it only makes the existing fatal diagnostic actionable. I left it as a fork commit because the project's contribution guide currently does not accept external pull requests.

AI-assisted repository audit and implementation; I reviewed the source, reproduced the failure, and ran every validation listed above. The commit records Codex <noreply@openai.com> as a co-author.

[denial123789]

I turned this failure mode into a preservation-first operator runbook: https://sandbaseai.github.io/deepseek-harness-handbook/corrupt-package-json-profile-boot.html

The guide adds a read-only recursive scanner that follows pnpm directory symlinks, deduplicates real targets, and prints every malformed manifest with its path, size, and parser error. It then routes each bad path to its actual repair owner: selected global distribution, exact _npx cache closure, one profile dependency, source checkout, or an external DLP/endpoint/storage writer.

Two operational points are worth keeping alongside the upstream diagnostic patch:

1. preserve the bad files, stack, executable, version, registry, timestamps, and hashes before cleaning a cache or reinstalling;
2. replace the exact owning closure through its original channel instead of copying a manifest from another version or filling an empty file with {}. Multiple unrelated truncations, or corruption that returns after a clean reinstall, should be treated as evidence of an external writer.

The runbook finishes with an isolated exact-version probe, profile/runtime acceptance gates, cold-restart rescan, and the source diagnostic contract for wrapping only JSON parse failures while retaining native filesystem errors.

Canonical guide: https://github.com/sandbaseai/deepseek-harness-handbook/blob/main/docs/en/troubleshooting/corrupt-package-json-profile-boot.md

[argszero]

Verified at rc.8 (141eb6fef8) — the report is precise and @GCSimba's patch shape is right (keep readFileSync outside the parse try, wrap only JSON.parse with the absolute path + parser detail, preserve the original as cause). One addition from a repo-wide sweep of app-boot:

There is a third bare JSON.parse(readFileSync(...)) call site the patch should cover. The reported two are packages/boot/app-boot/src/profile.ts:227 (install anchor) and :247 (dependency walk). But :390 has the same shape for bundle package manifests:

const bundleManifest = JSON.parse(readFileSync(join(packageDir, 'package.json'), 'utf8')) as ProfileManifest

This runs when a profile declares dsh.profile.bundles (manifest.dsh?.profile?.bundles ?? [], :387-388 → resolveBundleDir → read bundle package.json). A corrupt bundle manifest (e.g. a truncated @deepseek-ai/dsh-<bundle>/package.json in the install closure — same DLP/transient-writer corruption class the reporter hit) escapes as the same bare SyntaxError: Unexpected end of JSON input with no path, one layer deeper into the boot sequence than the two reported sites.

So the readPackageManifest() helper should route all three sites (:227, :247, :390) — the bundle path is easy to miss because it sits under the bundles.map(...) layer rather than the direct fallback walker. (Also profile.ts:267 reads a manifest via readProfileManifest which already wraps the path — that one's fine.)

Operational note for the reporter's DLP hypothesis: denial123789's runbook already covers the preservation-first workflow; the third call site just means the diagnostic now pinpoints which of the ~600 manifests failed without a manual scan in the bundle layer too.

[GCSimba]

Thanks @argszero — confirmed. The bundle manifest read in loadProfile() was the third sibling path, and the first patch missed it.

I appended a follow-up commit instead of rewriting the already-linked commit. It:

• routes the resolved bundle package manifest through the same private readPackageManifest() helper;
• adds a regression through the public loadProfile() entry point with a corrupt installed bundle manifest, asserting both the absolute path and preserved SyntaxError cause; and
• broadens the bilingual README and existing Agent Note from fallback healing to all three package-manifest reads during profile boot.

Follow-up commit: d471b7741287f806daa11369795b44cce5264d6b

Branch: codex/fix-profile-fallback-manifest-diagnostics

Validation after the follow-up:

• the new regression failed before the production change with the bare parser message and passed afterward;
• the owning test file passed 17/17, with profile.ts at 100% statements, branches, functions, and lines;
• pnpm run build and pnpm run lint passed;
• commit and pre-push hooks passed, including the host build and TypeScript contract check; and
• pnpm run doc-sync passed 27/28 gates; the remaining Windows-only failure is the repository's symlink-escape fixture receiving EPERM from symlinkSync.

Thanks for catching the omitted layer before this was handed off upstream.