@logictan/dsh-config-manager 0.1.60

package/lib/core/plugin-cli.js

@@ -0,0 +1,497 @@
+/**
+ * dsh plugin CLI 通道（方案A 主机侧实现，M1）。
+ *
+ * 本模块是唯一的子进程启动点：把「安装 / 更新 profile 插件」转成官方
+ * `dsh plugin --profile <name> <args…>` 调用（dsh CLI 内部转发 pnpm，并在
+ * 成功后 reconcile dsh.profile.bundles），以及从 profile 文件实时读取已装
+ * 插件清单（不依赖 web 专用 pluginMarketplace / pluginInventory 服务）。
+ *
+ * 设计对齐：
+ *  - dsh 官方实现 @deepseek-ai/dsh/lib/plugin-*.js（runPlugin / reconcilePlugins /
+ *    exportsPatch 的 bundle 判定语义）；
+ *  - dshmarket src/dsh-cli.ts（dshArgv / spawnShim / killTree / spawnEnv）与
+ *    src/profile.ts（readInstalled / readInstalledVersion / hasDshManifest）。
+ *
+ * 只依赖 node 内置模块，零 DSH 运行时依赖（M5 的 TDD 可直接单测本模块）。
+ */
+import { spawn } from 'node:child_process';
+import { readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { atomicWriteFileSync } from '../utils/atomic-write.js';
+/* ------------------------------------------------------------ profile 文件 */
+/**
+ * dsh 出厂自带的 in-box bundle（profile 模板自身安装的层）：唯一从「已装
+ * 插件清单」中隐藏的名字。社区插件可以合法地发布在官方 scope 下，因此不能
+ * 按 scope 整段过滤（dshmarket #28 的结论）。
+ */
+export const INBOX_BUNDLES = new Set([
+    '@deepseek-ai/dsh-base',
+    '@deepseek-ai/dsh-web-app',
+    '@deepseek-ai/dsh-headless',
+]);
+/**
+ * profile 名合法性校验，与 dsh-app-boot 的 resolveProfileDir 一致：拒绝空名、
+ * 路径分隔符与保留名，防止 join(home, 'profiles', name) 越界。
+ */
+export function validateProfileName(profile) {
+    if (profile === ''
+        || profile.includes('/') || profile.includes('\\')
+        || profile === '.' || profile === '..' || profile === 'node_modules') {
+        throw new Error(`invalid profile name ${JSON.stringify(profile)}`);
+    }
+    return profile;
+}
+/** Profile 目录：$DSH_HOME/profiles/<name>（homeDir 由宿主 resolveDshHome() 解析）。 */
+export function resolveProfileDir(homeDir, profile) {
+    return join(homeDir, 'profiles', validateProfileName(profile));
+}
+/**
+ * 从启动参数解析 profile 名：`--profile <name>` → 缺省 'web'。与宿主 apply 时的
+ * resolveProfileName 同源（config 覆盖仅 apply 处有；报告/适配器场景用本函数即可）。
+ * argv 参数化便于测试；缺省读当前进程 argv。
+ * 宽容语义：缺值 / 值以 '-' 开头 / 校验非法 → 一律回退 'web'。消息构建路径
+ * （applyItem 失败分支、补行等）绝不允许因 profile 名抛错破坏非致命 warning；
+ * 且 launcher 在启动时已拒绝非法 profile，此分支实际不可达。
+ */
+export function resolveProfileNameFromArgv(argv = process.argv.slice(2)) {
+    const at = argv.indexOf('--profile');
+    if (at === -1)
+        return 'web';
+    const value = argv[at + 1];
+    if (value === undefined || value === '' || value.startsWith('-'))
+        return 'web';
+    try {
+        return validateProfileName(value);
+    }
+    catch {
+        return 'web';
+    }
+}
+/** 读 profile package.json；不可读（未初始化 / 损坏）返回 null。 */
+export function readProfileManifest(profileDir) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(profileDir, 'package.json'), 'utf8'));
+        return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** 写回 profile package.json（2 空格缩进 + 尾换行，与 dsh-app-boot 一致；原子写防半装损坏）。 */
+export function writeProfileManifest(profileDir, manifest) {
+    atomicWriteFileSync(join(profileDir, 'package.json'), `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o644 });
+}
+/** 真实已装的依赖（in-box bundles 过滤掉）：name → 声明的版本 spec。 */
+export function readInstalled(profileDir) {
+    const manifest = readProfileManifest(profileDir);
+    const installed = {};
+    for (const [name, spec] of Object.entries(manifest?.dependencies ?? {})) {
+        if (!INBOX_BUNDLES.has(name))
+            installed[name] = spec;
+    }
+    return installed;
+}
+/** node_modules/<name>/package.json 里实际落盘的版本；未装 / 不可读为 null。 */
+export function readInstalledVersion(profileDir, name) {
+    try {
+        const manifest = JSON.parse(readFileSync(join(profileDir, 'node_modules', name, 'package.json'), 'utf8'));
+        return typeof manifest.version === 'string' && manifest.version !== '' ? manifest.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** 包的 package.json 是否声明 dsh.bundle.patch（即它是一个 bundle / profile 层）。 */
+export function hasDshBundlePatch(pkgDir) {
+    try {
+        const manifest = JSON.parse(readFileSync(join(pkgDir, 'package.json'), 'utf8'));
+        return manifest.dsh?.bundle?.patch !== undefined;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 维护 dsh.profile.bundles 与已装依赖一致（语义对齐官方 plugin 命令的
+ * reconcilePlugins，按「已装状态」而非依赖 diff 判定）：
+ *  - 声明 dsh.bundle.patch 的依赖必须出现在 bundles（追加在依赖顺序尾部）；
+ *  - bundles 中「曾是依赖、但不再是（移除或版本不再声明 patch）」的条目移出；
+ *  - in-box bundles 不是依赖，永远不碰。
+ * 仅在确有变化时写回 package.json。返回是否写回。
+ */
+export function reconcileBundles(profileDir) {
+    const manifest = readProfileManifest(profileDir);
+    if (manifest === null)
+        return false;
+    const dependencies = Object.keys(manifest.dependencies ?? {});
+    const dependencySet = new Set(dependencies);
+    const bundles = manifest.dsh?.profile?.bundles;
+    const plugins = Array.isArray(bundles) ? [...bundles] : [];
+    let changed = false;
+    for (const name of dependencies) {
+        if (INBOX_BUNDLES.has(name))
+            continue;
+        const isBundle = hasDshBundlePatch(join(profileDir, 'node_modules', name));
+        if (isBundle && !plugins.includes(name)) {
+            plugins.push(name);
+            changed = true;
+        }
+    }
+    for (const name of [...plugins]) {
+        const wasDependency = dependencySet.has(name);
+        const stillBundle = dependencySet.has(name) && hasDshBundlePatch(join(profileDir, 'node_modules', name));
+        if (wasDependency && !stillBundle) {
+            plugins.splice(plugins.indexOf(name), 1);
+            changed = true;
+        }
+    }
+    if (!changed)
+        return false;
+    manifest.dsh = {
+        ...manifest.dsh,
+        profile: { ...manifest.dsh?.profile, bundles: plugins },
+    };
+    writeProfileManifest(profileDir, manifest);
+    return true;
+}
+/**
+ * 中止安装后清理半装状态（用户「跳过当前插件」）：移除 profile package.json 中的
+ * 依赖行 + reconcile bundles + 删 node_modules/<pkg>。
+ *
+ * 目的：pnpm add 被中途 kill 后，package.json 可能已声明依赖但 node_modules 不完整，
+ * 直接启动 DSH 会因缺包而失败。本函数把 manifest 恢复为「该插件未安装」的一致状态，
+ * 消除「声明了依赖但没装全」的启动风险。pnpm-lock.yaml 不触碰（运行时不被读取，
+ * 下次安装 pnpm 自行对齐）。尽力而为：任何失败不抛错，由调用方记录告警。
+ */
+export function cleanupAbortedInstall(profileDir, pkg) {
+    const manifest = readProfileManifest(profileDir);
+    if (manifest !== null) {
+        const deps = manifest.dependencies ?? {};
+        if (Object.prototype.hasOwnProperty.call(deps, pkg)) {
+            delete deps[pkg];
+            manifest.dependencies = deps;
+            writeProfileManifest(profileDir, manifest);
+        }
+        // 若 pkg 曾是 bundle 成员且已非依赖 → 从 bundles 移除
+        reconcileBundles(profileDir);
+    }
+    try {
+        rmSync(join(profileDir, 'node_modules', pkg), { recursive: true, force: true });
+    }
+    catch {
+        // 尽力而为：目录可能不存在或正被占用，忽略
+    }
+}
+/** 实时读 profile 已装插件清单（先 reconcile bundles，再逐依赖取版本/bundle 属性）。 */
+export function listInstalledPlugins(homeDir, profile) {
+    const dir = resolveProfileDir(homeDir, profile);
+    reconcileBundles(dir);
+    const out = [];
+    const installed = readInstalled(dir);
+    for (const name of Object.keys(installed)) {
+        const isBundle = hasDshBundlePatch(join(dir, 'node_modules', name));
+        out.push({
+            name,
+            version: readInstalledVersion(dir, name) ?? '',
+            // 文件视图无法区分 patch 行禁用：依赖即视为启用（与旧 marketplace 视图一致）。
+            enabled: true,
+            isBundle,
+            // 直接依赖的 bundle 自己就是 profile 层；普通依赖不属于任何聚合 bundle。
+            inBundles: isBundle ? [name] : [],
+            // 声明依赖 spec 原样保留：github:/file:/link: 等非 registry 来源导入时按此安装。
+            spec: installed[name],
+        });
+    }
+    // issue #28：仅通过 `dsh.profile.bundles` 声明的层（不在 dependencies 里）此前**完全不可见**，
+    // 于是「明明装了、备份里却是空的」。reconcileBundles 对这类条目是**保留**的（它的移除条件
+    // 要求该名字曾是依赖），所以它们确实会被 DSH 挂载，清单来源必须与之一致。
+    const manifest = readProfileManifest(dir);
+    const declaredBundles = manifest?.dsh?.profile?.bundles;
+    for (const name of Array.isArray(declaredBundles) ? declaredBundles : []) {
+        if (INBOX_BUNDLES.has(name))
+            continue;
+        if (Object.prototype.hasOwnProperty.call(installed, name))
+            continue; // 已在依赖清单里
+        out.push({
+            name,
+            version: readInstalledVersion(dir, name) ?? '',
+            enabled: true,
+            isBundle: true,
+            // 直接声明的层自己就是 profile 层
+            inBundles: [name],
+            // 无依赖声明 → 无 spec：导入时按裸包名安装（与 registry 依赖同语义）
+        });
+    }
+    return out;
+}
+/* --------------------------------------------------------------- CLI 通道 */
+/** 15 分钟默认上限（慢网络 + git 安装），可用环境变量覆盖（CI/测试）。 */
+const INSTALL_TIMEOUT_MS = Number(process.env.DSH_CONFIG_MANAGER_INSTALL_TIMEOUT_MS) || 15 * 60 * 1000;
+/**
+ * 非 registry 来源的依赖 spec 前缀：这些来源必须把 spec 原样交给 pnpm add，
+ * 裸包名在 registry 上查不到（fetch-404 → 幽灵依赖拖垮整个 profile 的安装）。
+ * 版本区间（^x / x.y.z）与裸包名走默认语义：npm 最新版（官方机制，见 §34.17 设计决策）。
+ */
+const NON_REGISTRY_SPEC = /^(github:|gitlab:|bitbucket:|git\+|file:|link:|workspace:|https?:)/i;
+/** 安装目标：非 registry spec 按 spec 安装；其余按裸包名（npm 最新版）。 */
+export function installSpecFor(pkg, spec) {
+    if (spec !== undefined && spec !== '' && NON_REGISTRY_SPEC.test(spec))
+        return spec;
+    return pkg;
+}
+/** Windows 的 npm/corepack/pnpm/dsh 都是 .cmd 垫片：Node 直接 spawn 无法启动（ENOENT/EINVAL）。 */
+const winCmdShim = process.platform === 'win32';
+/**
+ * 子进程环境：CI=true 让 pnpm v10+ 在无 TTY 时立即行动或失败，而不是卡在
+ * 静默交互提示；macOS GUI 启动不继承 shell PATH，补上常见 bin 目录（dshmarket #32）。
+ */
+function spawnEnv() {
+    if (process.platform === 'win32')
+        return { ...process.env, CI: 'true' };
+    const parts = (process.env.PATH ?? '').split(':').filter((part) => part !== '');
+    for (const bin of ['/opt/homebrew/bin', '/usr/local/bin', `${process.env.HOME ?? ''}/.local/bin`]) {
+        if (bin !== '' && !parts.includes(bin))
+            parts.push(bin);
+    }
+    return { ...process.env, CI: 'true', PATH: parts.join(':') };
+}
+/**
+ * 重放启动当前宿主进程的 dsh CLI：
+ *  - process.argv[1] 是 dsh 入口（全局 bin / 源码启动的 bin.ts / bin.js）→ 用
+ *    当前 Node 重新执行该入口（execArgv 原样保留，cwd 靠近入口保持相对导入可解析）；
+ *  - 否则退回 PATH 上的 `dsh`（Windows 是 .cmd，需经 shell）。
+ */
+export function dshArgv() {
+    const entry = process.argv[1];
+    if (entry !== undefined && /[\\/](?:bin\.(?:js|ts)|dsh)$/.test(entry)) {
+        const abs = resolve(entry);
+        return { file: process.execPath, args: [...process.execArgv, abs], cwd: dirname(abs), viaShell: false };
+    }
+    return { file: 'dsh', args: [], cwd: undefined, viaShell: winCmdShim };
+}
+/** cmd.exe 视为语法字符（即使在一个 token 内）。 */
+const CMD_METACHARS = /[\s"&|<>^()%!]/;
+/** 为一个 argv token 构造 cmd.exe 命令行引用（需要引用的 token 用双引号包裹并加倍内部引号）。 */
+export function quoteCmdArg(arg) {
+    if (!CMD_METACHARS.test(arg))
+        return arg;
+    return `"${arg.replace(/"/g, '""')}"`;
+}
+/** 由 argv 构造 cmd.exe 命令行（仅 Windows 垫片路径使用）。 */
+export function cmdCommandLine(argv) {
+    return argv.map(quoteCmdArg).join(' ');
+}
+/** cmd.exe 解析结果（仅 Windows 垫片路径使用）。 */
+const COMSPEC = process.env.ComSpec ?? 'cmd.exe';
+/**
+ * 启动命令：Windows .cmd 垫片经 cmd.exe /d /s /c 显式构造的命令行（避开 Node
+ * 弃用的 shell:true + argv 组合，DEP0190）；其余直接 shell:false 启动。
+ */
+function spawnShim(file, args, options) {
+    const { viaShell = false, ...spawnOptions } = options;
+    if (!viaShell || process.platform !== 'win32') {
+        return spawn(file, [...args], { ...spawnOptions, shell: false });
+    }
+    return spawn(COMSPEC, ['/d', '/s', '/c', `"${cmdCommandLine([file, ...args])}"`], {
+        ...spawnOptions,
+        shell: false,
+        windowsVerbatimArguments: true,
+    });
+}
+/**
+ * 杀掉子进程整棵进程树：Windows 的 kill() 只终止包装进程、pnpm 子进程还活着，
+ * 用 taskkill /T /F；POSIX 子进程独立进程组启动（detached），先 SIGTERM 组、
+ * 5 秒后 SIGKILL 兜底。
+ */
+export function killTree(child) {
+    if (process.platform === 'win32' && child.pid !== undefined) {
+        try {
+            spawn('taskkill', ['/pid', String(child.pid), '/t', '/f'], { stdio: 'ignore', windowsHide: true });
+            return;
+        }
+        catch {
+            /* fall through to plain kill */
+        }
+    }
+    const signalTree = (signal) => {
+        if (child.pid === undefined)
+            return;
+        try {
+            process.kill(-child.pid, signal);
+        }
+        catch {
+            try {
+                child.kill(signal);
+            }
+            catch { /* already gone */ }
+        }
+    };
+    signalTree('SIGTERM');
+    const escalate = setTimeout(() => signalTree('SIGKILL'), 5000);
+    escalate.unref?.();
+}
+/**
+ * 运行 `dsh plugin --profile <profile> <pluginArgs…>`：
+ * cwd=profile 目录、CI 环境、windowsHide、pipe 输出、15 分钟超时杀进程树。
+ * 永远 resolve（不 throw），由调用方判定成败。
+ *
+ * signal：可选 AbortSignal。中止时立即 killTree 杀掉整棵进程树（dsh 包装 + pnpm 孙进程），
+ * 结果标记 aborted=true（调用方据此判定「用户跳过/取消」，而非失败）。
+ */
+export function runDshPlugin(profileDir, profile, pluginArgs, timeoutMs = INSTALL_TIMEOUT_MS, signal) {
+    const { file, args, viaShell } = dshArgv();
+    return new Promise((resolvePromise) => {
+        const child = spawnShim(file, [...args, 'plugin', '--profile', profile, ...pluginArgs], {
+            cwd: profileDir,
+            env: spawnEnv(),
+            stdio: ['ignore', 'pipe', 'pipe'],
+            windowsHide: true,
+            viaShell,
+            // POSIX 下独立进程组，超时/取消可一次杀掉 dsh 包装进程 + pnpm 孙进程。
+            detached: process.platform !== 'win32',
+        });
+        let stdout = '';
+        let stderr = '';
+        let timedOut = false;
+        let aborted = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            killTree(child);
+        }, timeoutMs);
+        const onAbort = () => {
+            aborted = true;
+            clearTimeout(timer);
+            killTree(child);
+        };
+        if (signal !== undefined) {
+            if (signal.aborted)
+                onAbort();
+            else
+                signal.addEventListener('abort', onAbort, { once: true });
+        }
+        child.stdout?.on('data', (chunk) => {
+            stdout = (stdout + chunk.toString()).slice(-256 * 1024);
+        });
+        child.stderr?.on('data', (chunk) => {
+            stderr = (stderr + chunk.toString()).slice(-64 * 1024);
+        });
+        child.on('error', (error) => {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+            resolvePromise({ exitCode: 127, timedOut: false, aborted, stdout, stderr, spawnError: error.message });
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+            resolvePromise({ exitCode: code, timedOut, aborted, stdout, stderr });
+        });
+    });
+}
+/**
+ * 瞬时网络故障判定：pnpm 的 5xx 拉取码、meta 拉取放弃、以及穿透 dsh 包装的
+ * 原始 socket 错误。永久的形态（404、鉴权）刻意排除——重试只会加倍等坏消息。
+ */
+export function isTransientDshPluginFailure(output) {
+    return /ERR_PNPM_FETCH_5\d\d|ERR_PNPM_META_FETCH_FAIL|FetchError|ECONNRESET|ETIMEDOUT|EAI_AGAIN|ENETUNREACH|socket hang up|network timeout/i.test(output);
+}
+/**
+ * 把一次失败的 dsh plugin 调用的合并输出映射到已知失败模式。
+ * @param output - stdout+stderr 合并文本。
+ * @returns 分类结果；未识别返回 null（调用方展示原始摘要）。
+ */
+export function classifyDshPluginFailure(output) {
+    if (output.includes('ERR_PNPM_PUBLIC_HOIST_PATTERN_DIFF')) {
+        return {
+            code: 'hoist-pattern-diff',
+            recoverable: true,
+            message: 'profile 的 node_modules 由旧版 pnpm 创建，与当前 pnpm 的默认配置不兼容；在 profile 目录执行一次 pnpm install 重建后重试 / this profile\'s node_modules was created by a different pnpm major; rebuild it (pnpm install) before retrying',
+        };
+    }
+    if (output.includes('ERR_PNPM_ADDING_TO_ROOT')) {
+        return {
+            code: 'adding-to-root',
+            recoverable: true,
+            message: 'profile 是 pnpm workspace，当前 dsh CLI 转发未带 -w 被 pnpm 拒绝；可手动执行 dsh plugin --profile <name> add -w <pkg> / pnpm refused to add at a workspace root (missing -w); run dsh plugin --profile <name> add -w <pkg> by hand',
+        };
+    }
+    if (/--workspace-root may only be used inside a workspace/i.test(output)) {
+        return {
+            code: 'not-a-workspace',
+            recoverable: false,
+            message: 'profile 目录不是 pnpm workspace，却传入了 -w，因此被 pnpm 拒绝 / -w was passed but the profile is not a pnpm workspace, so pnpm refused the operation',
+        };
+    }
+    if (output.includes('ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION') || output.includes('ERR_PNPM_NO_MATURE_MATCHING_VERSION')) {
+        return {
+            code: 'release-age-violation',
+            recoverable: true,
+            message: 'profile 里有刚发布不久的插件版本，pnpm 的安全等待期检查拒绝了本次改动（即使改的是别的插件）；等待发布期满，或临时以 --config.minimumReleaseAge=0 重试 / a recently-published plugin version in this profile trips pnpm\'s fresh-release safety check, blocking any change (even to other plugins); wait for the release to mature, or retry once with --config.minimumReleaseAge=0',
+        };
+    }
+    if (output.includes('ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED') || /git-hosted package "[^"]+" needs to execute build scripts/i.test(output)) {
+        return {
+            code: 'git-build-blocked',
+            recoverable: false,
+            message: '该 git 插件需要在安装时执行构建脚本，被 pnpm 的 allowBuilds 白名单拦截；把 pnpm 提示的包名加入 profile 的 pnpm-workspace.yaml 的 allowBuilds 后重试 / this git-hosted plugin needs to run its build script at install time, which pnpm blocks until allowed — add the exact package pnpm printed to allowBuilds in the profile\'s pnpm-workspace.yaml, then re-run',
+        };
+    }
+    // issue #35：pnpm-workspace.yaml 的 patchedDependencies 指向不存在的 patch 文件时，
+    // pnpm 会在**任何** add 上失败（含与补丁无关的插件）。此时逐条报「插件装不上」是误导——
+    // 真正要修的是缺失的 patch 文件或那条声明。
+    if (/Failed to read patch file|patch file .*does not exist/i.test(output)) {
+        // 路径可能含盘符冒号（C:\...），故按整行取、再切掉尾随的 ':' 或 ': <错误文本>'
+        const raw = /Failed to read patch file\s+([^\r\n]+)/i.exec(output)?.[1]?.trim();
+        const file = raw === undefined ? undefined : raw.split(/:\s/)[0]?.replace(/:\s*$/, '').trim();
+        const zh = file === undefined ? '' : `（${file}）`;
+        const en = file === undefined ? '' : ` (${file})`;
+        return {
+            code: 'patch-file-missing',
+            recoverable: false,
+            message: `profile 的 pnpm-workspace.yaml 声明了 patchedDependencies，但对应的 patch 文件不存在${zh}；pnpm 因此拒绝任何安装（含与补丁无关的插件）。把缺失的 patch 文件放回 profile 的 patches/ 目录，或从 pnpm-workspace.yaml 删除该条目后重试 / the profile's pnpm-workspace.yaml declares patchedDependencies but the patch file is missing${en}; pnpm then refuses every install (even unrelated plugins). Put the patch file back under the profile's patches/ directory, or remove that entry from pnpm-workspace.yaml and retry`,
+        };
+    }
+    if (output.includes('ERR_PNPM_FETCH_404')) {
+        const pkg = /GET\s+\S*\/([^/\s]+):/.exec(output)?.[1]?.replace(/%2[Ff]/g, '/');
+        const zh = pkg === undefined ? '' : `（${pkg}）`;
+        const en = pkg === undefined ? '' : ` (${pkg})`;
+        return {
+            code: 'fetch-404',
+            recoverable: false,
+            message: `有一个依赖在 registry 上不存在${zh}，pnpm 拒绝任何安装操作；它可能是之前失败操作残留在 profile package.json 里的幽灵依赖（手动删除该行），也可能是需要登录的私有包 / a dependency cannot be resolved from the registry${en}; pnpm refuses every install while it is present — it may be a ghost entry left in the profile's package.json by an earlier failed operation (remove that line by hand), or a private package needing registry credentials`,
+        };
+    }
+    if (isTransientDshPluginFailure(output)) {
+        return {
+            code: 'transient-network',
+            recoverable: true,
+            message: '拉取依赖时网络临时失败（安装会重放整个依赖树，任何一个既有依赖抖动都会中断本次操作）；稍后直接重试通常即可 / a transient network failure while fetching dependencies (installs replay the whole dependency tree, so any existing dependency can hiccup); a plain retry usually succeeds',
+        };
+    }
+    if (output.includes('pnpm not found on PATH')) {
+        return {
+            code: 'pnpm-missing',
+            recoverable: false,
+            message: '找不到 pnpm（dsh 转发 pnpm 失败）：请先安装 pnpm（npm install -g pnpm 或 corepack enable pnpm），然后重试 / pnpm is not on PATH (dsh forwards to pnpm): install pnpm (npm install -g pnpm or corepack enable pnpm) and retry',
+        };
+    }
+    return null;
+}
+/** 安装失败 → 分类后的双语可读 Error；未识别则保留 stderr 尾部摘要。 */
+export function installErrorFor(pkg, result) {
+    if (result.spawnError !== undefined && /ENOENT|EINVAL/.test(result.spawnError)) {
+        return new Error(`无法启动 dsh CLI（${result.spawnError}）：请确认 dsh 已安装且在 PATH 上，然后重试安装 ${pkg} / cannot start dsh CLI (${result.spawnError}): make sure dsh is installed and on PATH, then retry installing ${pkg}`);
+    }
+    if (result.timedOut) {
+        return new Error(`安装 ${pkg} 超时（进程已终止，默认 15 分钟）：请检查网络或稍后重试 / install ${pkg} timed out (process killed, default 15 min): check your network and retry later`);
+    }
+    const output = `${result.stderr}\n${result.stdout}`;
+    const failure = classifyDshPluginFailure(output);
+    if (failure !== null) {
+        return new Error(`安装 ${pkg} 失败（${failure.code}）：${failure.message}`);
+    }
+    const tail = (result.stderr.trim().split('\n').slice(-8).join('\n')
+        || result.stdout.trim().split('\n').slice(-8).join('\n')
+        || '无输出');
+    return new Error(`dsh plugin 安装 ${pkg} 失败（exit ${String(result.exitCode)}）：${tail}`);
+}
+//# sourceMappingURL=plugin-cli.js.map

package/lib/core/reconcile.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Reconciler（Phase 3：startup reconciliation）。
+ *
+ * 职责：扫描 active journals → parse/schema 校验（corrupt 隔离）→ 验 environment fingerprint
+ * → 验 Journal→Lock 绑定 → 验快照 → 验 step 指纹 → 外部探测 → 选择推荐 recovery outcome
+ * → 执行（需用户确认的破坏性动作才执行）→ recovery-history → 幂等。
+ *
+ * **Reconciler 不拥有 Environment Lock primitive 实现** —— 通过 Coordinator/port 使用
+ * （release、active≤1、recover 显式流程由宿主/Coordinator 编排）。
+ *
+ * **Startup（Rev 3 P1-NEW-2）不自动 recover stale lock**：
+ *  - 若发现 stale lock + incomplete journal → RECOVERY_REQUIRED / SAFE MODE，不自动 recoverStaleLock；
+ *  - 用户显式确认后才 prove stale → recover → acquire → reconcile。
+ */
+import { JournalStore, type OperationJournal, type JournalStep } from './journal.ts';
+export type StepFingerprintVerdict = 'before-match' | 'after-match' | 'none' | 'unable';
+export type ExternalProbe = 'installed' | 'half-installed' | 'reverse-residue' | 'not-installed' | 'unknown';
+export interface ReconcileProbeHooks {
+    /** 对某 step 的目标做磁盘指纹判定。 */
+    verifyStepFingerprint(step: JournalStep): Promise<StepFingerprintVerdict>;
+    /** 外部步骤（插件/Git/WebDAV）状态探测。 */
+    probeExternal(step: JournalStep): Promise<ExternalProbe>;
+    /**
+     * 快照完整性（id 合法 + snapshot.json 存在 + 必要 blobs 存在 + READY + 属于本 op）。
+     * binding 为 journal 的绑定字段（operationId/ownerInstanceId/environmentFingerprint），
+     * 实现应校验 snapshot 的 manifest binding 与 journal 一致（P1-1：防伪造快照过 snapshotExists）。
+     */
+    snapshotExists(snapshotId: string | null, binding?: {
+        operationId?: string;
+        ownerInstanceId?: string;
+        environmentFingerprint?: string;
+    }): Promise<boolean>;
+}
+export interface ReconcileEnv {
+    environmentFingerprint: string;
+    /** 判定某 journal 是否属于仍存活的 live owner（live op 不可 reconcile/quarantine/move）。 */
+    isLiveOwner(journal: OperationJournal): boolean | Promise<boolean>;
+    /**
+     * P1-A：期望的 crashed-ownership instanceId（= stale environment.lock owner.instanceId）。
+     * 显式 recovery 捕获 stale ownership 证据后传入：active journal 的 ownerInstanceId/lockId
+     * 必须匹配该 crashed ownership，才可作为 trusted transaction 参与 reconcile/rollback/resume；
+     * 否则 → needs-attention（SAFE MODE，不 trusted），防跨 transaction/伪造 journal。
+     */
+    expectedOwnershipInstanceId?: string;
+}
+export interface ReconcileOptions {
+    /** 是否自动隔离 corrupt journal（move 到 quarantine + attention sidecar）。默认 true。 */
+    autoQuarantine?: boolean;
+    /** 是否对 terminal-in-active journal 自动 move 到 completed。默认 true。 */
+    organizeTerminal?: boolean;
+}
+export type ReconcileDecisionKind = 'live' | 'corrupt' | 'env-mismatch' | 'organized' | 'recovered' | 'noop' | 'rollback-recommended' | 'rollback-continue' | 'needs-attention';
+export interface ReconcileDecision {
+    operationId: string;
+    kind: ReconcileDecisionKind;
+    reason: string;
+    snapshotId: string | null;
+}
+/** 汇总结果：是否该进入 SAFE MODE（任一 needs-attention / env-mismatch / corrupt / rollback-recommended）。 */
+export interface ReconcileOutcome {
+    decisions: ReconcileDecision[];
+    safeModeRequired: boolean;
+    /** unresolved（未到 terminal）的 incomplete op id（RECOVERY_REQUIRED 候选）。 */
+    unresolved: string[];
+}
+/**
+ * 分析 active/ 下的所有 journal，返回每个 op 的决策 + 是否需 SAFE MODE。
+ * 只读（除 corrupt quarantine 与 terminal organize / recovery-history 外，不做 data mutation）。
+ */
+export declare function reconcileActive(store: JournalStore, hooks: ReconcileProbeHooks, env: ReconcileEnv, opts?: ReconcileOptions): Promise<ReconcileOutcome>;
+export interface RecoveryExecutorInput {
+    operationId: string;
+    action: 'rollback' | 'resume' | 'dismiss';
+    snapshotId: string | null;
+}
+/** 执行恢复（破坏性动作必须 userConfirm=true 才执行）。 */
+export interface RecoveryExecutorInput {
+    operationId: string;
+    action: 'rollback' | 'resume' | 'dismiss';
+    snapshotId: string | null;
+    /**
+     * 恢复决策（§5.2 引擎映射）：rollback-recommended → restore executor（恢复到 trusted snapshot）；
+     * rollback-continue → rollback executor（续跑中断回滚）。缺省 = rollback-continue（兼容旧调用）。
+     */
+    decision?: 'rollback-recommended' | 'rollback-continue';
+    /** 宿主注入的实际回滚执行器（rollback-continue：续跑中断回滚；破坏性副作用由宿主/Coordinator 执行）。 */
+    performRollback?: (snapshotId: string) => Promise<{
+        full: boolean;
+        failed: string[];
+    }>;
+    /** 宿主注入的 restore 执行器（rollback-recommended：恢复到 trusted snapshot）。 */
+    performRestore?: (snapshotId: string) => Promise<{
+        full: boolean;
+        failed: string[];
+    }>;
+}
+export declare function executeRecovery(store: JournalStore, input: RecoveryExecutorInput, userConfirmed: boolean): Promise<'done' | 'needs-confirmation' | 'failed'>;
+/**
+ * 对 terminal `NEEDS_ATTENTION` journal 重算 recovery 决策（§5.4，Reviewer A 第二轮 P1-2）。
+ *
+ * `reconcileActive` 对 terminal `NEEDS_ATTENTION` journal 恒返回 `needs-attention`
+ * （`NEEDS_ATTENTION` 是 terminal，`rollback-recommended`/`rollback-continue` 只在转换进
+ * NEEDS_ATTENTION 的当次 pass 出现一次）。`GET /recovery/status` 用本函数重算，区分
+ * `rollback-recommended` / `rollback-continue` / `needs-attention`。
+ *
+ * **只读**：不修改 journal，不写 SAFE MODE，不写 recovery-history。
+ */
+export declare function recomputeRecoveryDecision(j: OperationJournal, hooks: Pick<ReconcileProbeHooks, 'snapshotExists'>): Promise<'rollback-continue' | 'rollback-recommended' | 'needs-attention'>;
+export interface StartupInspection {
+    safeModeRequired: boolean;
+    recoveryRequired: boolean;
+    decisions: ReconcileDecision[];
+    unresolved: string[];
+}
+/**
+ * Startup 只读事务状态 + 锁状态扫描（Rev 3 P1-NEW-2）：
+ * 只检测、只读；**不自动 recoverStaleLock、不自动 create journal**。
+ * lockState: 'LOCKED' | 'STALE_LOCK_DETECTED' | 'UNKNOWN_STATE' | 'FREE'
+ */
+export declare function inspectStartup(store: JournalStore, hooks: ReconcileProbeHooks, env: ReconcileEnv, opts: ReconcileOptions, lockState: 'LOCKED' | 'STALE_LOCK_DETECTED' | 'UNKNOWN_STATE' | 'FREE'): Promise<StartupInspection>;