@luolingp/request-doctor 0.0.0-stage → 0.11.1

package/lib/install-bundle.js

@@ -0,0 +1,199 @@
+// 装一个远程的插件，不管它的版本检查过不过。
+//
+// 管理器的安装路径是 pnpm 加一次版本检查：检查不过就抛 incompatible-version，
+// 顺手把 profile 回滚。远程包的字节在检查之前就落地了，所以没法像本地目录那样
+// 提前改好 manifest——只能在管理器放弃之后，自己把这件事做完。
+//
+// 这里做的事就是 pnpm add 该做的：取包、取依赖、放进 node_modules、登记为 bundle。
+// 差别只有一处：装之前先按当前运行时把声明对齐，装完再把兼容环境建好。
+import { existsSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { alignManifest, installCompatEnvironment, readJson } from './compat-env.js';
+import { fetchPackage, listVersions } from './package-fetch.js';
+import { satisfies } from './semver.js';
+import { safeCompare } from './version-search.js';
+import { cachePackage, resolveClosure } from './version-repair.js';
+
+// 一次性最多装这么多个依赖。正常插件几个，多了说明依赖树异常。
+const MAX_DEPENDENCIES = 24;
+
+// 把 "name"、"name@1.2.3"、"@scope/name@^1.0.0" 拆成包名和范围。
+export function parseInstallSpec(spec) {
+  if (typeof spec !== 'string') return undefined;
+  const text = spec.trim();
+  if (text === '' || text.startsWith('-')) return undefined;
+  // 本地路径、git 地址、tarball 走别的路，这里只认注册表写法。
+  if (/^(?:file:|link:|git|https?:)/.test(text) || /[\\/]/.test(text.replace(/^@[^/]+\/[^/]+/, ''))) return undefined;
+
+  const scoped = text.startsWith('@');
+  const at = text.indexOf('@', scoped ? 1 : 0);
+  if (at < 0) return { name: text, range: undefined };
+  return { name: text.slice(0, at), range: text.slice(at + 1) };
+}
+
+// 选一个版本：满足范围的最新版本；范围没写就取最新。
+export function chooseVersion(versions, range) {
+  const usable = versions.filter((version) => typeof version === 'string' && version !== '');
+  if (usable.length === 0) return undefined;
+  const ordered = [...usable].sort(safeCompare).reverse();
+  if (range === undefined) return ordered[0];
+  return ordered.find((version) => satisfies(version, range) === true) ?? ordered[0];
+}
+
+// 把一个远程插件装进 profile。
+//
+// 不做部分成功：中途任何一步失败都把这个包整个删掉，like pnpm 回滚一样，
+// 不给 profile 留下一半装好的东西。
+export async function installRemoteBundle(input) {
+  const parsed = parseInstallSpec(input.spec);
+  if (parsed === undefined) return { installed: false, reason: '不是注册表里的包名，无法远程安装' };
+
+  const { name, range } = parsed;
+  if (typeof input.profileDir !== 'string' || input.profileDir === '') {
+    return { installed: false, reason: '拿不到 profile 目录' };
+  }
+
+  const versions = await listVersions(name);
+  const version = chooseVersion(versions, range);
+  if (version === undefined) return { installed: false, reason: `注册表里找不到 ${name}` };
+
+  const target = join(input.profileDir, 'node_modules', ...name.split('/'));
+  try {
+    rmSync(target, { recursive: true, force: true });
+    const fetched = await fetchPackage(name, version, target);
+    if (!fetched.ok) return { installed: false, reason: fetched.error ?? '下载失败' };
+
+    // 不是 bundle 的包登记进去会让加载器出错，跟管理器自己的 not-bundle 判断一致。
+    const fetchedManifest = readJson(join(target, 'package.json'));
+    if (fetchedManifest?.dsh?.bundle === undefined) {
+      rmSync(target, { recursive: true, force: true });
+      return { installed: false, reason: `${name}@${version} 不是 bundle 插件：清单里没有 dsh.bundle` };
+    }
+
+    const dependencies = await installDependencies(target, input);
+    const requirements = declaredRangesOf(target);
+    // 声明对齐到当前运行时。管理器读的就是这份 manifest，对齐了它的检查才过得去。
+    const served = {};
+    for (const declared of Object.keys(requirements)) served[declared] = input.runtimeVersion;
+    alignManifest({ pluginDir: target, versions: served, runtimeVersion: input.runtimeVersion });
+
+    // 插件到底 import 了什么，得读它的源码才知道。没有这个只能建空环境，
+    // 装上了也起不来——缺的垫片一个都没建。
+    const imports = input.imports ?? discoverImports(target, input);
+    const environment = installCompatEnvironment({
+      pluginDir: target,
+      profileDir: input.profileDir,
+      requirements,
+      imports,
+      runtimeVersion: input.runtimeVersion,
+      resolveDir: input.resolveDir,
+    });
+    return {
+      installed: true,
+      name,
+      version,
+      path: target,
+      environment: environment.status,
+      // 环境没建成时把原因带出去，用户才知道卡在哪一环。
+      environmentReason: environment.error,
+      missing: environment.missing ?? [],
+      dependencies,
+    };
+  } catch (error) {
+    rmSync(target, { recursive: true, force: true });
+    return { installed: false, reason: String(error) };
+  }
+}
+
+// 读出新装插件的导入表。
+//
+// 调用方传了探测函数就用它；没传就退回「按声明的 DSH 依赖建垫片」——
+// 声明过的包一定是它要用的，给它们建齐，至少不会因为少一层垫片而 import 失败。
+function discoverImports(target, input) {
+  if (typeof input.factsOf === 'function' && typeof input.entryOf === 'function') {
+    try {
+      const manifest = readJson(join(target, 'package.json'));
+      const entry = input.entryOf(target, manifest ?? {});
+      if (entry !== undefined) {
+        const facts = input.factsOf(target, entry);
+        if (facts?.imports instanceof Map) return facts.imports;
+      }
+    } catch {
+      // 探测失败就退回声明
+    }
+  }
+  const map = new Map();
+  for (const declared of Object.keys(declaredRangesOf(target))) map.set(declared, []);
+  return map;
+}
+
+// 读出插件自己声明的 DSH 依赖范围。对齐声明时要用它当依据。
+function declaredRangesOf(dir) {
+  const manifest = readJson(join(dir, 'package.json'));
+  if (manifest === undefined) return {};
+  const found = {};
+  for (const source of [manifest.peerDependencies, manifest.dependencies]) {
+    for (const [name, range] of Object.entries(source ?? {})) {
+      if (name.startsWith('@deepseek-ai/') && found[name] === undefined) found[name] = range;
+    }
+  }
+  return found;
+}
+
+// 把包自己的运行时依赖也放进 profile。
+//
+// 不装的话，它 import 的兄弟包要么找不到，要么落到别的版本上。
+//
+// 可选依赖一并处理：它们通常带平台判断，缺了不一定报错，但装上的体验才是完整的。
+// 装不上就算了——可选的本义就是可以没有。
+async function installDependencies(target, input) {
+  const manifest = readJson(join(target, 'package.json'));
+  if (manifest === undefined) return [];
+
+  const installed = [];
+  const queue = [
+    ...Object.entries(manifest.dependencies ?? {}),
+    ...Object.entries(manifest.optionalDependencies ?? {}),
+  ];
+  const optional = new Set(Object.keys(manifest.optionalDependencies ?? {}));
+  const seen = new Set();
+  while (queue.length > 0 && installed.length < MAX_DEPENDENCIES) {
+    const [name, range] = queue.shift();
+    if (seen.has(name)) continue;
+    seen.add(name);
+
+    const destination = join(input.profileDir, 'node_modules', ...name.split('/'));
+    if (existsSync(join(destination, 'package.json'))) continue;
+
+    const versions = await listVersions(name);
+    const version = chooseVersion(versions, /^[\d.]/.test(range) ? range : undefined);
+    if (version === undefined) {
+      // 可选依赖取不到是正常的：它可能只对别的平台发布。
+      if (optional.has(name) === false) installed.push(`${name}（取不到版本）`);
+      continue;
+    }
+    if ((await fetchPackage(name, version, destination)).ok) installed.push(`${name}@${version}`);
+  }
+  return installed;
+}
+
+// 把包登记进 profile 的 bundle 列表。
+//
+// 只登记这一处：DSH 的 bundle 列表和 dependencies 是两回事，现有 profile 里就有
+// 一半 bundle 不在 dependencies 里。写 dependencies 反而会让下次 pnpm 操作去核对它。
+export function registerBundle(profileDir, name) {
+  const path = join(profileDir, 'package.json');
+  const manifest = readJson(path);
+  if (manifest === undefined) return { registered: false, reason: '读不到 profile 清单' };
+
+  const bundles = manifest.dsh?.profile?.bundles;
+  if (!Array.isArray(bundles)) return { registered: false, reason: 'profile 清单里没有 bundle 列表' };
+  if (bundles.includes(name)) return { registered: true, changed: false };
+
+  bundles.push(name);
+  writeFileSync(path, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+  return { registered: true, changed: true };
+}
+
+// 供外部复用：闭包取包。
+export { cachePackage, resolveClosure };

package/lib/install-rescue.js

@@ -0,0 +1,161 @@
+// 让「版本不匹配」的插件装得上。
+//
+// 管理器把兼容性检查放在安装流程里，对不上的包直接拒掉，profile 原样回滚。用户看到的
+// 就是那句「不兼容，可能崩溃或丢数据」，然后什么都没装上。
+//
+// 它自己留了一个正当出口：版本豁免。先按它的规则授权，让它把包装完（依赖、构建脚本仍由
+// pnpm 处理），装完再把声明对齐、把兼容环境建好。跑的是当前实现，声明说的也是当前版本，
+// 风险是真的被消掉了，不是被绕过。
+//
+// 为什么不在 installBundle 上套一层？试过了，不行：远程方法在装饰期就被抓成一个按对象
+// 取值的访问器快照，插件侧无论改实例还是改原型，都进不了调用链。授权是它公开支持的那
+// 条路，也是失败信息里点名指出的那条。
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { alignManifest, installCompatEnvironment } from './compat-env.js';
+import { installRemoteBundle, parseInstallSpec, registerBundle } from './install-bundle.js';
+
+// 从安装失败里取出「哪个包的哪个版本」。
+export function refusedPackageOf(error) {
+  const first = error?.incompatible?.[0];
+  if (first?.name !== undefined && first?.version !== undefined) {
+    return { name: first.name, version: first.version, runtimeVersion: first.runtimeVersion };
+  }
+  // 有些路径只给一句 message，那就退回从 spec 里认。
+  const fromSpec = parseInstallSpec(error?.spec);
+  if (fromSpec === undefined) return undefined;
+  return { name: fromSpec.name, version: fromSpec.range, runtimeVersion: undefined };
+}
+
+// 装一个注册表里的包：先授权，再让管理器装，最后补上兼容形态。
+export async function installWithExemption(input) {
+  const parsed = parseInstallSpec(input.spec);
+  if (parsed === undefined) return { installed: false, reason: '不是注册表里的包名' };
+
+  const facts = input.probe.runtimeFacts();
+  const profileDir = facts.profileDir ?? '';
+  const runtimeVersion = input.runtimeVersion ?? facts.runtimeVersion ?? '';
+  if (profileDir === '' || runtimeVersion === '') {
+    return { installed: false, reason: '拿不到 profile 目录或运行时版本' };
+  }
+
+  // 已经装着的包不用再装一遍。用户多半是想「让它能用」——就地修好就行。
+  if (isPresent(profileDir, parsed.name)) {
+    input.record('install-present', `${parsed.name} 已经在 profile 里，就地修复`);
+    return finish(input, parsed.name, profileDir, runtimeVersion);
+  }
+
+  // 版本可能没写。这种时候先让管理器去解析，它会告诉我们实际是哪个版本。
+  const first = await attemptInstall(input, input.spec);
+  if (first.ok) return finish(input, parsed.name, profileDir, runtimeVersion);
+
+  // 管理器说「已经装了」也走就地修复：用户要的是能用，不是再装一次。
+  if (first.error?.code === 'already-installed') {
+    return finish(input, parsed.name, profileDir, runtimeVersion);
+  }
+
+  const refused = refusedPackageOf(first.error) ?? { name: parsed.name, version: parsed.range };
+  if (refused.version === undefined) {
+    return { installed: false, reason: first.error?.message ?? '安装失败，且拿不到具体版本' };
+  }
+  const granted = await grantExemption(input, refused, runtimeVersion);
+  if (granted === false) return { installed: false, reason: '版本豁免授权失败' };
+
+  const second = await attemptInstall(input, input.spec);
+  if (second.ok) return finish(input, refused.name, profileDir, runtimeVersion);
+  return installByHand(input, facts, profileDir, runtimeVersion);
+}
+
+// 按管理器自己的规则授权。这是它给的出口，不是我们绕过去。
+async function grantExemption(input, refused, runtimeVersion) {
+  const packageVersion = `${refused.name}@${refused.version}`;
+  try {
+    await input.pluginManager?.setVersionExemption?.(packageVersion, runtimeVersion, true, true);
+    input.record('install-exemption', `已为 ${packageVersion} 授权运行在 ${runtimeVersion}`);
+    return true;
+  } catch (failure) {
+    input.record('install-exemption-failed', `${packageVersion} 授权失败：${String(failure)}`);
+    return false;
+  }
+}
+
+// 管理器那条路彻底走不通时自己装。
+async function installByHand(input, facts, profileDir, runtimeVersion) {
+  const byHand = await installRemoteBundle({
+    spec: input.spec,
+    profileDir,
+    runtimeVersion,
+    resolveDir: input.probe.runtimeDirOf(facts),
+    factsOf: input.factsOf,
+    entryOf: input.entryOf,
+  });
+  if (!byHand.installed) return { installed: false, reason: byHand.reason ?? '安装失败' };
+  registerBundle(profileDir, byHand.name);
+  return finish(input, byHand.name, profileDir, runtimeVersion);
+}
+
+// 这个包是不是已经躺在 profile 里了。
+function isPresent(profileDir, name) {
+  try {
+    return readFileSync(join(profileDir, 'node_modules', ...name.split('/'), 'package.json'), 'utf8') !== '';
+  } catch {
+    return false;
+  }
+}
+
+// 装一次，把失败收成结果而不是抛出去。
+async function attemptInstall(input, spec) {
+  try {
+    const result = await input.pluginManager.installBundle(spec);
+    return { ok: result?.application !== 'failed', result, error: result?.error };
+  } catch (error) {
+    return { ok: false, error };
+  }
+}
+
+// 装完之后的收尾：声明对齐、环境建好、启用。
+async function finish(input, name, profileDir, runtimeVersion) {
+  const facts = input.probe.runtimeFacts();
+  const dir = join(profileDir, 'node_modules', ...name.split('/'));
+
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+  } catch {
+    return { installed: false, reason: `${name} 装完之后读不到清单` };
+  }
+
+  // 运行时自己发布的声明全部对齐到当前版本。管理器读的就是这份 manifest。
+  const served = {};
+  for (const key of Object.keys(manifest.peerDependencies ?? {})) {
+    if (/^@deepseek-ai\/dsh(?:[-/]|$)/.test(key)) served[key] = runtimeVersion;
+  }
+  const aligned = alignManifest({ pluginDir: dir, versions: served, runtimeVersion });
+  if (aligned.status === 'failed') {
+    input.record('install-align-failed', `${name} 对齐失败：${aligned.error}`);
+  }
+
+  const environment = installCompatEnvironment({
+    pluginDir: dir,
+    profileDir,
+    requirements: manifest.peerDependencies ?? {},
+    imports: new Map(),
+    runtimeVersion,
+    resolveDir: input.probe.runtimeDirOf(facts),
+  });
+
+  try {
+    await input.pluginManager?.setBundleEnabled?.(name, true);
+  } catch {
+    // 重载失败不影响已经装好的东西
+  }
+
+  input.record('install', `${name} 已装好，环境 ${environment.status}`);
+  return {
+    installed: true,
+    name,
+    version: manifest.version,
+    path: dir,
+    environment: environment.status,
+  };
+}

package/lib/install-support.js

@@ -0,0 +1,206 @@
+// 让本来装不上的插件能装上。
+//
+// pluginManager.installBundle 先跑 pnpm，然后拿新包自己的 manifest 做版本检查，
+// 对不上就抛 incompatible-version。抛的时候只回滚 package.json 和 pnpm-lock.yaml，
+// 包其实已经躺在 node_modules 里了，但永远不会被选中——看起来就是安装失败，什么都没装上。
+//
+// 正确做法不是等检查失败后再去绕过它，那时候 profile 已经回滚了。而是在管理器读 manifest
+// 之前，就让检查按它自己的规则通过：把兼容环境准备好，这样它读到的声明确实满足当前运行时。
+//
+// 环境建在插件目录里，并留一个标记记录做过什么，装失败时可以原样撤回。
+import { existsSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { alignManifest, installCompatEnvironment, readJson, removeCompatEnvironment, restoreManifest } from './compat-env.js';
+
+// 准备好的环境在这儿等安装落地。
+export const STAGING_DIR = '.request-doctor-staging';
+
+// 判断一个安装参数指向的是本地目录还是远程包。
+//
+// 参数可能是包名、file: 或 link: 路径、git 地址或者 tarball。只有本地目录能在安装前
+// 先看一眼，也只有这种情况才能提前准备环境——远程包的字节还没落到盘上。
+export function classifySpec(spec, profileDir) {
+  if (typeof spec !== 'string') return { kind: 'remote' };
+  const text = spec.trim();
+  const local = /^(?:file:|link:)?(?:\.{0,2}\/|[A-Za-z]:[\\/]|\/)/.test(text);
+  if (!local) return { kind: 'remote' };
+  const path = text.replace(/^(?:file:|link:)/, '');
+  const absolute = /^[A-Za-z]:[\\/]|^\//.test(path) ? path : join(profileDir, path);
+  return existsSync(join(absolute, 'package.json')) ? { kind: 'local', dir: absolute } : { kind: 'remote' };
+}
+
+// 在本地插件装上来之前，先给它把兼容环境备好。
+//
+// 就地改目标目录（安装时会从这里链接），留一个标记记下改了什么，装失败了能撤回。
+export function prepareForInstall(input) {
+  const checked = inspectCandidate(input);
+  if (checked.reason !== undefined) return checked;
+
+  const { dir, requirements, imports } = checked;
+  resetPreviousAttempt(dir);
+
+  const result = installCompatEnvironment({
+    pluginDir: dir,
+    profileDir: input.profileDir,
+    requirements,
+    imports,
+    runtimeVersion: input.runtimeVersion,
+    resolveDir: input.resolveDir,
+  });
+
+  // 缺符号的包要先取真实旧版本，那是异步的，这一步只对齐声明把安装放行，
+  // 环境交给后续扫描去建——扫描里能等网络。
+  if (result.status === 'needs-old-version') {
+    const deferred = deferEnvironment({ dir, requirements, runtimeVersion: input.runtimeVersion });
+    if (deferred.prepared === true) {
+      const names = result.needed.map((item) => `@`).join(', ');
+      return { ...deferred, reason: `已放行安装；环境需要真实旧版本 ，由后续扫描取回后建立` };
+    }
+    return deferred;
+  }
+  if (result.status === 'refused' && onlyMissingRuntimePackages(result.missing)) {
+    return deferEnvironment({ dir, requirements, runtimeVersion: input.runtimeVersion });
+  }
+  if (result.status === 'refused') {
+    // 环境建不全，但安装本身不该被拦下来。
+    //
+    // 被拒绝通常是因为某个符号在当前运行时里改名或者没了。那是运行期的问题：
+    // 插件装上之后能正常加载，真的用到那个符号时才会报错，而且报得清楚。
+    // 卡在安装这一步，用户连插件都看不到，反而更难判断。
+    // 所以这里只对齐声明放行，缺什么一并带回去告诉用户。
+    const deferred = deferEnvironment({ dir, requirements, runtimeVersion: input.runtimeVersion });
+    if (deferred.prepared === true) {
+      return {
+        ...deferred,
+        missing: result.missing,
+        reason: `${result.error}；已放行安装，这些符号要等插件真正用到时才会报错`,
+      };
+    }
+    return deferred;
+  }
+  if (result.status !== 'installed') {
+    return { prepared: false, dir, reason: result.error ?? `environment could not be built (${result.status})` };
+  }
+  return finalizePreparation({ dir, packages: result.packages, runtimeVersion: input.runtimeVersion });
+}
+
+// 动笔写任何东西之前，先把目标目录验一遍。
+// 返回两种结果：拒绝的理由，或者建环境需要的那几样东西。
+function inspectCandidate(input) {
+  const classified = classifySpec(input.spec, input.profileDir);
+  if (classified.kind !== 'local' || classified.dir === undefined) {
+    return {
+      prepared: false,
+      reason: 'only a local directory can be inspected before it is installed; a registry package is downloaded by the manager itself',
+    };
+  }
+  const dir = classified.dir;
+  const manifest = readJson(join(dir, 'package.json'));
+  if (manifest === undefined) return { prepared: false, dir, reason: 'package.json is unreadable' };
+
+  const requirements = input.unmetPeers?.(manifest, input.runtimeVersion) ?? {};
+  if (Object.keys(requirements).length === 0) {
+    return { prepared: false, dir, reason: 'the package already declares requirements this runtime satisfies' };
+  }
+  const entry = input.entryOf?.(dir, manifest);
+  if (entry === undefined) return { prepared: false, dir, reason: 'the package declares no resolvable entry module' };
+
+  const facts = input.factsOf?.(dir, entry);
+  if (facts === undefined || facts.imports.size === 0) {
+    return { prepared: false, dir, reason: 'the package imports no DSH package, so no environment can be built for it' };
+  }
+  return { dir, requirements, imports: facts.imports };
+}
+
+// 把上一次尝试留下的东西清干净。
+// 旧垫片留着会被当成这次建的，后面判断就全错了。
+function resetPreviousAttempt(dir) {
+  if (existsSync(join(dir, STAGING_DIR))) rmSync(join(dir, STAGING_DIR), { recursive: true, force: true });
+  removeCompatEnvironment(dir);
+}
+
+// 判断被拒绝的原因是不是清一色「profile 里看不见运行时的包」。
+// 运行时装在归档里时就是这个情况。安装检查只看 manifest，所以光对齐声明就够了。
+function onlyMissingRuntimePackages(missing) {
+  return missing.every((entry) => /not installed in the profile/.test(entry));
+}
+
+// 只对齐声明，环境留给下一轮扫描去建。
+function deferEnvironment(input) {
+  const aligned = alignManifest({
+    pluginDir: input.dir,
+    versions: Object.fromEntries(Object.keys(input.requirements).map((pkg) => [pkg, input.runtimeVersion])),
+    runtimeVersion: input.runtimeVersion,
+  });
+  if (aligned.status === 'failed') {
+    restoreManifest(input.dir);
+    return { prepared: false, dir: input.dir, reason: aligned.error ?? 'the manifest could not be aligned' };
+  }
+  writeFileSync(
+    join(input.dir, STAGING_DIR),
+    `${JSON.stringify({ runtimeVersion: input.runtimeVersion, packages: [], deferred: true, requirements: input.requirements }, null, 2)}\n`,
+    'utf8',
+  );
+  return {
+    prepared: true,
+    dir: input.dir,
+    packages: [],
+    deferred: true,
+    requirements: input.requirements,
+    reason: 'declaration aligned so the install can proceed; the environment is built by the next scan',
+  };
+}
+
+// 环境建好后，把声明对齐到它实际服务的版本，并记下这次准备。
+// 管理器读的是包自己的 manifest，不写这一笔，环境明明在那儿，安装照样被拒。
+function finalizePreparation(input) {
+  const aligned = alignManifest({
+    pluginDir: input.dir,
+    versions: Object.fromEntries(input.packages.map((pkg) => [pkg, input.runtimeVersion])),
+    runtimeVersion: input.runtimeVersion,
+  });
+  if (aligned.status === 'failed') {
+    abandonPreparation(input.dir);
+    return { prepared: false, dir: input.dir, reason: aligned.error ?? 'the manifest could not be aligned' };
+  }
+  writeFileSync(
+    join(input.dir, STAGING_DIR),
+    `${JSON.stringify({ runtimeVersion: input.runtimeVersion, packages: input.packages }, null, 2)}\n`,
+    'utf8',
+  );
+  return { prepared: true, dir: input.dir, packages: input.packages };
+}
+// 读一下还没处理完的准备标记。
+export function readStagedPreparation(dir) {
+  return readJson(join(dir, STAGING_DIR));
+}
+
+// 环境已经有了，回去把准备标记清掉。
+export function clearStagedPreparation(dir) {
+  try {
+    rmSync(join(dir, STAGING_DIR), { force: true });
+  } catch {
+    /* retried on the next scan */
+  }
+}
+
+// 安装没成的话，把准备过的痕迹原样撤掉。
+export function abandonPreparation(dir) {
+  const staging = join(dir, STAGING_DIR);
+  if (!existsSync(staging)) return false;
+  removeCompatEnvironment(dir);
+  // 这次安装对齐过 manifest，现在把原来的还回去，失败的尝试不该在候选目录里留下痕迹。
+  restoreManifest(dir);
+  try {
+    rmSync(staging, { force: true });
+  } catch {
+    /* reported through the return value */
+  }
+  return true;
+}
+
+// 管理器装完之后，确认准备还在不在。
+// 它会换掉目录（file: 安装是拷贝不是链接），那样环境就没了，得从装好的那份重建。
+export function preparationSurvived(dir) {
+  return existsSync(join(dir, STAGING_DIR));
+}