@logictan/dsh-config-manager 0.1.60

package/src/core/undo.ts

@@ -0,0 +1,116 @@
+/**
+ * 撤销 / 重做语义（Phase 1 P0-2）。
+ *
+ * 与竞品 dsh-undo-savepoint 的语义对齐（其「撤销不会撤销掉自己」的等价物在本仓库
+ * 由两处保证：`pre-restore` 快照自身不参与候选，以及恢复后按内容指纹做回声抑制）：
+ *
+ *  自动快照在变更**之后**采集，因此「最新快照」通常等于当前状态。
+ *  真实撤销 = 回退到与当前状态**内容不同**的最新快照（跳过等于当前状态的那些）。
+ *  全部相同 → 明确返回「没有可撤销的变化」，而不是做一次空操作。
+ *
+ * 重做的护栏：撤销时先落一个 `pre-restore` 快照记录「撤销前状态」；
+ * 一旦其后产生任何更新的快照（= 用户又改了），重做即失效——避免把用户的
+ * 新改动覆盖回旧状态。
+ *
+ * 本模块是**纯规划**：不读盘、不写盘、不碰 adapter。执行侧见 config-snapshot.ts。
+ */
+import { statesEqual, type ConfigState } from './config-state.ts';
+
+/** 快照种类。pre-restore 为撤销/还原自身的记账快照，永不作为撤销目标。 */
+export type ConfigSnapshotKind = 'manual' | 'auto' | 'undo' | 'pre-restore' | 'baseline';
+
+/** 规划所需的最小快照视图（携带其采集到的状态） */
+export interface UndoCandidate {
+  id: string;
+  createdAt: string;
+  kind: ConfigSnapshotKind;
+  /** 该快照采集时的配置状态（缺省 = 旧格式快照，无法参与内容比对） */
+  state?: ConfigState;
+  /** pre-restore 是否已被重做消费 */
+  consumed?: boolean;
+}
+
+export type UndoPlan =
+  | { kind: 'undo'; targetId: string; skippedNewer: number; reason: 'content-differs' }
+  | { kind: 'none'; reason: 'no-snapshots' | 'already-at-state' };
+
+export type RedoPlan =
+  | { kind: 'redo'; targetId: string; reason: 'unconsumed-pre-restore' }
+  | { kind: 'none'; reason: 'no-pre-restore' | 'superseded-by-newer-change' };
+
+/** 按 createdAt 倒序（新→旧）；同刻按 id 稳定排序保证确定性。 */
+export function sortNewestFirst<T extends { createdAt: string; id: string }>(items: readonly T[]): T[] {
+  return [...items].sort((a, b) => {
+    if (a.createdAt !== b.createdAt) return a.createdAt < b.createdAt ? 1 : -1;
+    return a.id < b.id ? 1 : a.id > b.id ? -1 : 0;
+  });
+}
+
+/** 可作为撤销目标/状态基准的快照（剔除 pre-restore 与无 state 的旧格式） */
+function comparableCandidates(snapshots: readonly UndoCandidate[]): UndoCandidate[] {
+  return sortNewestFirst(snapshots).filter((s) => s.kind !== 'pre-restore' && s.state !== undefined);
+}
+
+/**
+ * 规划一次撤销：返回第一个内容与 current 不同的快照。
+ * `skippedNewer` = 跳过的「与当前状态相同」的更新快照数（通常 ≥1，因为自动快照
+ * 落在变更之后）。
+ */
+export function planUndo(current: ConfigState, snapshots: readonly UndoCandidate[]): UndoPlan {
+  const candidates = comparableCandidates(snapshots);
+  if (candidates.length === 0) return { kind: 'none', reason: 'no-snapshots' };
+  for (let i = 0; i < candidates.length; i++) {
+    const candidate = candidates[i]!;
+    if (!statesEqual(current, candidate.state!)) {
+      return { kind: 'undo', targetId: candidate.id, skippedNewer: i, reason: 'content-differs' };
+    }
+  }
+  return { kind: 'none', reason: 'already-at-state' };
+}
+
+/** 是否存在可撤销的变化（供 UI 按钮可用性；等价于 planUndo 是否命中）。 */
+export function canUndo(current: ConfigState, snapshots: readonly UndoCandidate[]): boolean {
+  return planUndo(current, snapshots).kind === 'undo';
+}
+
+/**
+ * 规划一次重做：取最新的未消费 pre-restore。
+ * 若其后存在任何更新的快照（含未消费的 pre-restore）→ superseded-by-newer-change。
+ */
+export function planRedo(snapshots: readonly UndoCandidate[]): RedoPlan {
+  const ordered = sortNewestFirst(snapshots);
+  const pre = ordered.find((s) => s.kind === 'pre-restore' && s.consumed !== true);
+  if (pre === undefined) return { kind: 'none', reason: 'no-pre-restore' };
+  const superseded = ordered.some(
+    (s) => s.createdAt > pre.createdAt && (s.kind !== 'pre-restore' || s.consumed !== true),
+  );
+  if (superseded) return { kind: 'none', reason: 'superseded-by-newer-change' };
+  return { kind: 'redo', targetId: pre.id, reason: 'unconsumed-pre-restore' };
+}
+
+/** 是否存在可重做的撤销（供 UI 按钮可用性）。 */
+export function canRedo(snapshots: readonly UndoCandidate[]): boolean {
+  return planRedo(snapshots).kind === 'redo';
+}
+
+/**
+ * 撤销后需要标记为「已被跨过」的快照 id 列表。
+ * 语义：撤销回退到 targetId 之后，比 targetId 更新、且内容等于**撤销前状态**的那些
+ * 快照，代表的是被撤销掉的那一步；重做回到撤销前状态后应清除该标记。
+ * 返回 targetId 之后（更旧侧不涉及）需要标记的 id。
+ */
+export function steppedIds(
+  snapshots: readonly UndoCandidate[],
+  targetId: string,
+  beforeState: ConfigState,
+): string[] {
+  const target = snapshots.find((s) => s.id === targetId);
+  if (target === undefined) return [];
+  return snapshots
+    .filter((s) => s.kind !== 'pre-restore'
+      && s.id !== targetId
+      && s.createdAt > target.createdAt
+      && s.state !== undefined
+      && statesEqual(s.state, beforeState))
+    .map((s) => s.id);
+}

package/src/core/validator.ts

@@ -0,0 +1,84 @@
+/**
+ * 整体校验与兼容性评分（规范 §18 完整性 / §30 兼容性评分 / 导入后校验）。
+ */
+import { validateManifest } from '../schema/manifest.ts';
+import { validateSectionData } from '../schema/config.ts';
+import { canImport, describeVersion } from '../schema/versions.ts';
+import type { SectionId } from '../schema/types.ts';
+import type { CompatibilityInput, CompatibilityScore, ValidationResult } from './types.ts';
+
+export { validateManifest } from '../schema/manifest.ts';
+export { validateSectionData } from '../schema/config.ts';
+
+/** 校验 ZIP 内分区数据集合（空对象=合法）；返回合并的校验结果 */
+export function validateSections(
+  sections: ReadonlyMap<SectionId, unknown>,
+): ValidationResult {
+  const issues: ValidationResult['issues'] = [];
+  for (const [sectionId, data] of sections) {
+    const sectionIssues = validateSectionData(sectionId, data);
+    for (const issue of sectionIssues) {
+      issues.push({ ...issue, path: `${sectionId}:${issue.path}` });
+    }
+  }
+  return { valid: issues.every((i) => i.severity !== 'error'), issues };
+}
+
+function parseVersion(v: string): { major: number; minor: number; patch: number; pre: number } {
+  const m = /^(\d+)\.(\d+)(?:\.(\d+))?(?:-(?:rc\.?)?(\d+))?/i.exec(v);
+  if (!m) return { major: 0, minor: 0, patch: 0, pre: 0 };
+  return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3] ?? 0), pre: Number(m[4] ?? Infinity) };
+}
+
+/** 版本比较：-1=a<b，0=相等，1=a>b（预发布 < 正式版） */
+function compareVersions(a: ReturnType<typeof parseVersion>, b: ReturnType<typeof parseVersion>): -1 | 0 | 1 {
+  for (const k of ['major', 'minor', 'patch'] as const) {
+    if (a[k] !== b[k]) return a[k] < b[k] ? -1 : 1;
+  }
+  if (a.pre !== b.pre) return a.pre < b.pre ? -1 : 1;
+  return 0;
+}
+
+/**
+ * 兼容性评分（规则驱动，不凭感觉）：
+ *  unsupported — schema 超出本插件支持范围（过高/过低）
+ *  partial     — 跨平台、分区缺失、或备份 DSH 比目标新
+ *  good        — 备份 DSH 比目标旧（向后兼容）且其余正常
+ *  excellent   — 同平台、无缺失、schema 支持
+ */
+export function computeCompatibility(input: CompatibilityInput): CompatibilityScore {
+  if (!canImport(input.schemaVersion)) return 'unsupported';
+
+  let score: CompatibilityScore = 'excellent';
+
+  if (input.sourcePlatform !== input.targetPlatform) score = 'partial';
+  if (input.missingSections.length > 0) score = 'partial';
+
+  const src = parseVersion(input.sourceDsh);
+  const tgt = parseVersion(input.targetDsh);
+  const cmp = compareVersions(src, tgt);
+  if (cmp > 0) {
+    // 备份来自更新的 DSH → 可能有目标版本不认识的配置
+    score = 'partial';
+  } else if (cmp < 0) {
+    // 备份来自更旧的 DSH → 目标向后兼容
+    score = 'good';
+  }
+
+  return score;
+}
+
+/** 兼容性得分的可读描述（UI 报告用） */
+export function describeCompatibility(score: CompatibilityScore): string {
+  switch (score) {
+    case 'excellent': return 'Excellent — 完美兼容（同平台、无缺失、schema 支持）';
+    case 'good': return 'Good — 兼容（旧版备份导入新版 DSH）';
+    case 'partial': return 'Partial — 部分兼容（跨平台/分区缺失/版本超前，需人工确认）';
+    case 'unsupported': return 'Unsupported — 不受支持（schema 超出范围）';
+  }
+}
+
+/** 用 describeVersion 生成 schema 状态的用户可读说明 */
+export function describeSchemaStatus(schemaVersion: number): string {
+  return describeVersion(schemaVersion);
+}

package/src/core/verify-recovery.ts

@@ -0,0 +1,265 @@
+/**
+ * Phase 5 Post-Recovery Verification（§6）。
+ *
+ * 职责：recovery/rollback 完成后，验证目标状态与 trusted snapshot 匹配。
+ * 核心不变量（VERIFIED）：**No recovery/rollback may be considered complete until the
+ * target state is verified to match the trusted snapshot** —— 验证失败不能 COMMITTED。
+ *
+ * 关键规则（§6.2 / §6.3 / §11.1）：
+ *  - **verify 时刻重验**：不信任 execute 时「已校验过」的结论（TOCTOU 窗口，快照可能被替换）。
+ *    本函数在 verify 时刻重跑完整 `validateSnapshotForRestore`（含 symlink + provenance +
+ *    env binding + `requireOperationBound=true`），并从磁盘重读 snapshot.json 作为权威。
+ *  - **只消费 TRUSTED_OPERATION_SNAPSHOT**：非 operation-bound（TRUSTED_MANUAL_LOCAL /
+ *    LEGACY_REQUIRES_CONFIRMATION）一律拒绝，绝不当作 MATCH。
+ *  - **verdict 语义严格区分**：
+ *      MATCH            目标状态与 snapshot 完全匹配
+ *      PARTIAL_MATCH    核心可验证状态匹配，但存在无法可靠验证的部分（如凭据值不可回读）
+ *      MISMATCH         能确定目标状态仍不同于 snapshot（文件 hash 不匹配 / 应删仍存在 /
+ *                       plugin/settings 明确不同）
+ *      VERIFICATION_ERROR 验证过程本身无法可靠完成（快照重验失败 / fs 读错误 / 异常）
+ *    绝不把 VERIFICATION_ERROR 降级成 PARTIAL_MATCH。
+ *  - 输出结构兼容 Step 2 的 `recoveryVerification`（verdict/details[]/manualHints[]/at）；
+ *    details/manualHints 写入 journal 前由调用方过 `redactJournalText`（本函数只产出文本，
+ *    不含 secret 值——凭据值不可回读，settings 只比对不输出值）。
+ *
+ * 本模块为纯函数（fs 经 node:fs + HostContext 门面注入），可独立测试。
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+
+import { resolveFileTarget } from './backup.ts';
+import { validateSnapshotForRestore } from './restore.ts';
+import type { RecoveryVerification, RecoveryVerificationVerdict } from './journal.ts';
+import type { HostContext, Snapshot } from './types.ts';
+import type { SectionId } from '../schema/types.ts';
+
+export interface VerifyRecoveryOptions {
+  /** 快照根目录（<snapshotsDir>，<snapshotDir> 的直接父级）。 */
+  snapshotsRoot: string;
+  /** 当前环境指纹（必须与 snapshot binding 一致，否则 WRONG_ENVIRONMENT）。 */
+  environmentFingerprint: string;
+  /** 期望的 operationId（journal.operationId）。快照 operationId 必须与之双向一致，否则 WRONG_OPERATION。 */
+  expectedOperationId?: string;
+}
+
+/** 越界防御：abs 必须等于 homeDir 或在 homeDir 之内 */
+function isWithinHome(homeDir: string, abs: string): boolean {
+  const root = path.resolve(homeDir);
+  return abs === root || abs.startsWith(root + path.sep);
+}
+
+/** 绝对路径 → 相对 homeDir（跨平台归一为 / 分隔；越界返回空串） */
+function toRelPath(homeDir: string, abs: string): string {
+  if (!isWithinHome(homeDir, abs)) return '';
+  return path.relative(homeDir, abs).split(path.sep).join('/');
+}
+
+/** 快照目录内 blob 绝对路径（防 snapshot.json 里伪造 ../ 越界读） */
+function blobAbs(snapshotDir: string, blobPath: string): string {
+  const abs = path.resolve(snapshotDir, blobPath);
+  if (!isWithinHome(snapshotDir, abs)) throw new Error(`blob 路径越界: ${blobPath}`);
+  return abs;
+}
+
+/** Uint8Array 字节级相等 */
+function bufEq(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  return true;
+}
+
+/** file 类条目的目标绝对路径（复用 backup.ts 的基准目录规则；仅读 homeDir） */
+function resolveFileAbs(homeDir: string, adapter: SectionId, ref: string): string {
+  return resolveFileTarget({ homeDir } as unknown as HostContext, adapter, ref);
+}
+/**
+ * Post-recovery verification（§6.4）。
+ *
+ * @param snapshot 被恢复 operation 的 journal 引用快照（id + binding 用于定位与交叉校验；
+ *                 实际校验以磁盘重读为准，不信任内存对象）。
+ * @param ctx      HostContext（homeDir / fs / settings / plugins 门面）。
+ * @param opts     snapshotsRoot + environmentFingerprint。
+ */
+export async function verifyRecovery(
+  snapshot: Snapshot,
+  ctx: HostContext,
+  opts: VerifyRecoveryOptions,
+): Promise<RecoveryVerification> {
+  const details: string[] = [];
+  const manualHints: string[] = [];
+  const at = new Date().toISOString();
+  const snapshotDir = path.join(opts.snapshotsRoot, snapshot.id);
+
+  // 1) verify 时刻重验快照（TOCTOU）：重跑完整 validateSnapshotForRestore，requireOperationBound=true。
+  //    只接受 TRUSTED_OPERATION_SNAPSHOT；任何其它 verdict（含 TRUSTED_MANUAL_LOCAL / LEGACY）→ VERIFICATION_ERROR。
+  const val = await validateSnapshotForRestore(snapshotDir, opts.snapshotsRoot, {
+    environmentFingerprint: opts.environmentFingerprint,
+  });
+  if (val.verdict !== 'TRUSTED_OPERATION_SNAPSHOT') {
+    return {
+      verdict: 'VERIFICATION_ERROR',
+      details: [`快照重验失败: ${val.verdict}${val.reason ? ` — ${val.reason}` : ''}`],
+      manualHints: [],
+      at,
+    };
+  }
+  details.push('快照重验通过（TRUSTED_OPERATION_SNAPSHOT）');
+
+  // 2) 从磁盘重读 snapshot.json 作为权威（不信任传入的 snapshot 对象，防 execute→verify 间替换）。
+  let diskSnapshot: Snapshot;
+  try {
+    const raw = await fs.readFile(path.join(snapshotDir, 'snapshot.json'), 'utf8');
+    diskSnapshot = JSON.parse(raw) as Snapshot;
+  } catch (err) {
+    return { verdict: 'VERIFICATION_ERROR', details: [...details, `snapshot.json 重读失败: ${err instanceof Error ? err.message : String(err)}`], manualHints: [], at };
+  }
+
+  // 3) environment binding（validateSnapshotForRestore 已查，此处双保险）
+  if (diskSnapshot.environmentFingerprint && diskSnapshot.environmentFingerprint !== opts.environmentFingerprint) {
+    return { verdict: 'VERIFICATION_ERROR', details: [...details, 'environmentFingerprint 不匹配（WRONG_ENVIRONMENT）'], manualHints: [], at };
+  }
+
+  // 3b) operation binding（journal.operationId ↔ snapshot.operationId 双向一致；WRONG_OPERATION 拒绝）
+  if (opts.expectedOperationId !== undefined && diskSnapshot.operationId !== opts.expectedOperationId) {
+    return { verdict: 'VERIFICATION_ERROR', details: [...details, `operationId 不匹配（WRONG_OPERATION）: snapshot=${diskSnapshot.operationId ?? '(无)'} expected=${opts.expectedOperationId}`], manualHints: [], at };
+  }
+
+  let mismatch = false;
+  let unverifiable = false;
+
+  // 4) host files（hostFileBackups）：existed=true 应存在且内容 hash 匹配 blob；existed=false 应不存在。
+  //    经 ctx.fs（HostContext 注入，homeDir 相对）读写，与 rollback.ts 一致。
+  for (const backup of diskSnapshot.hostFileBackups ?? []) {
+    const rel = backup.relPath;
+    if (backup.existed) {
+      if (backup.blobPath === '') {
+        unverifiable = true;
+        details.push(`host file 无 blob 信息: ${rel}`);
+        continue;
+      }
+      if (!(await ctx.fs.exists(rel))) {
+        mismatch = true;
+        details.push(`host file 缺失: ${rel}`);
+        continue;
+      }
+      let blob: Uint8Array;
+      try {
+        blob = await fs.readFile(blobAbs(snapshotDir, backup.blobPath));
+      } catch {
+        unverifiable = true;
+        details.push(`host file blob 读取失败: ${rel}`);
+        continue;
+      }
+      const current = await ctx.fs.readFile(rel);
+      if (!bufEq(current, blob)) {
+        mismatch = true;
+        details.push(`host file 内容不匹配: ${rel}`);
+      } else {
+        details.push(`host file 匹配: ${rel}`);
+      }
+    } else {
+      // snapshot expects absent → target 必须不存在（删除动作失败 → 残留被检测）
+      if (await ctx.fs.exists(rel)) {
+        mismatch = true;
+        details.push(`应删除目标仍存在: ${rel}`);
+      } else {
+        details.push(`删除目标已不存在: ${rel}`);
+      }
+    }
+  }
+
+  // 5) file 类条目（entries kind='file'）：existed=true 应存在且内容匹配 blob；existed=false 应不存在。
+  for (const entry of diskSnapshot.entries ?? []) {
+    if (entry.kind !== 'file') continue;
+    const rel = toRelPath(ctx.homeDir, resolveFileAbs(ctx.homeDir, entry.adapter, entry.ref));
+    if (rel === '') {
+      unverifiable = true;
+      details.push(`file 路径越界: ${entry.adapter}:${entry.ref}`);
+      continue;
+    }
+    if (entry.existed && entry.copiedTo) {
+      if (!(await ctx.fs.exists(rel))) {
+        mismatch = true;
+        details.push(`file 缺失: ${entry.adapter}:${entry.ref}`);
+        continue;
+      }
+      let blob: Uint8Array;
+      try {
+        blob = await fs.readFile(blobAbs(snapshotDir, entry.copiedTo));
+      } catch {
+        unverifiable = true;
+        details.push(`file blob 读取失败: ${entry.adapter}:${entry.ref}`);
+        continue;
+      }
+      const current = await ctx.fs.readFile(rel);
+      if (!bufEq(current, blob)) {
+        mismatch = true;
+        details.push(`file 内容不匹配: ${entry.adapter}:${entry.ref}`);
+      } else {
+        details.push(`file 匹配: ${entry.adapter}:${entry.ref}`);
+      }
+    } else if (!entry.existed) {
+      if (await ctx.fs.exists(rel)) {
+        mismatch = true;
+        details.push(`应删除 file 目标仍存在: ${entry.adapter}:${entry.ref}`);
+      } else {
+        details.push(`删除 file 目标已不存在: ${entry.adapter}:${entry.ref}`);
+      }
+    }
+  }
+
+  // 6) plugin state（best-effort）：导入期间新增插件应被移除。可精确验证 → 纳入 MATCH 判断；
+  //    无法可靠验证（无基线 / listInstalled 失败）→ PARTIAL_MATCH + manualHint。
+  const beforePlugins = diskSnapshot.beforePlugins;
+  if (beforePlugins === undefined) {
+    unverifiable = true;
+    details.push('快照无 beforePlugins 基线，插件状态不可验证');
+    manualHints.push('插件状态无法自动验证（快照无基线），请人工确认已装插件');
+  } else {
+    try {
+      const current = await ctx.plugins.listInstalled();
+      const beforeNames = new Set(beforePlugins.map((p) => p.name));
+      const added = current.filter((p) => !beforeNames.has(p.name));
+      if (added.length > 0) {
+        mismatch = true;
+        details.push(`导入期间新增插件未移除: ${added.map((p) => p.name).join(', ')}`);
+      } else {
+        details.push('插件状态匹配（无新增插件）');
+      }
+    } catch {
+      unverifiable = true;
+      details.push('插件状态无法验证（listInstalled 失败）');
+      manualHints.push('插件状态无法自动验证（listInstalled 失败），请人工确认已装插件');
+    }
+  }
+
+  // 7) settings（best-effort）：settingsNamespace 条目 before 值应与当前 settings 一致。
+  const settingsEntries = (diskSnapshot.entries ?? []).filter((e) => e.kind === 'settingsNamespace');
+  for (const entry of settingsEntries) {
+    try {
+      const current = await ctx.settings.describe(entry.ref);
+      if (!isDeepStrictEqual(current.value, entry.before)) {
+        mismatch = true;
+        details.push(`settings 不匹配: ${entry.ref}`);
+      } else {
+        details.push(`settings 匹配: ${entry.ref}`);
+      }
+    } catch {
+      unverifiable = true;
+      details.push(`settings 无法验证: ${entry.ref}`);
+      manualHints.push(`settings 无法自动验证（${entry.ref}），请人工确认`);
+    }
+  }
+
+  // 8) verdict：MISMATCH 优先（能确定目标状态不同）；其次 PARTIAL_MATCH（存在不可验证项）；否则 MATCH。
+  if (mismatch) return { verdict: 'MISMATCH', details, manualHints, at };
+  if (unverifiable) return { verdict: 'PARTIAL_MATCH', details, manualHints, at };
+  return { verdict: 'MATCH', details, manualHints, at };
+}
+
+/** 便捷：把 RecoveryVerification 映射为 journal 终态（供 verify 路由单次原子 update 使用）。 */
+export function recoveryTerminalState(verdict: RecoveryVerificationVerdict): 'ROLLED_BACK' | 'RECOVERED' | 'NEEDS_ATTENTION' {
+  if (verdict === 'MATCH' || verdict === 'PARTIAL_MATCH') return 'ROLLED_BACK';
+  return 'NEEDS_ATTENTION';
+}