dsh-config-manager 0.1.0

package/src/core/rollback.ts

@@ -0,0 +1,140 @@
+/**
+ * Rollback（规范 §17 / 设计 §8.2）：导入失败时逆序执行快照条目的补偿动作。
+ *
+ * 诚实原则：
+ *  - 尽力回滚：单项失败不停止其余补偿，最终如实报告 full / partial；
+ *  - credential 值 DSH 永不回读 → existed=true 的凭据无法自动恢复原值，
+ *    如实标记 failed + manualHint（人工补录）；
+ *  - settings 回滚仍走 expectedRevision 乐观锁，避免覆盖导入后用户的新修改。
+ */
+import { resolveFileTarget } from './backup.ts';
+import type {
+  ConfigAdapter, HostContext, RollbackReport, Snapshot, SnapshotEntry, SnapshotStore,
+} from './types.ts';
+
+export interface RollbackOptions {
+  ctx: HostContext;
+  snapshot: Snapshot;
+  store?: SnapshotStore;
+  adapters?: ConfigAdapter[];
+}
+
+/** 逆序补偿单条快照条目；返回 null=成功，否则为失败原因 */
+async function compensateOne(
+  entry: SnapshotEntry,
+  ctx: HostContext,
+  store: SnapshotStore | undefined,
+): Promise<{ reason: string; manualHint?: string } | null> {
+  switch (entry.kind) {
+    case 'settingsNamespace': {
+      try {
+        if (!entry.existed) {
+          // 原目标不存在该 namespace：若导入已创建它，DSH settings 无删除语义 → 无法恢复「不存在」
+          let current: unknown = null;
+          try {
+            current = await ctx.settings.describe(entry.ref);
+          } catch {
+            current = null;
+          }
+          if (current === null) return null; // 本来就没有且未创建 → 无需恢复
+          return {
+            reason: '该 namespace 由导入创建，DSH settings 无删除语义',
+            manualHint: `namespace "${entry.ref}" 需人工删除或合并`,
+          };
+        }
+        // 用当前 revision 作乐观锁基准：读时即锁，冲突则如实失败（不覆盖并发修改）
+        const current = await ctx.settings.describe(entry.ref);
+        await ctx.settings.replace(entry.ref, entry.before, current.revision);
+        return null;
+      } catch (err) {
+        return { reason: err instanceof Error ? err.message : String(err), manualHint: `settings namespace "${entry.ref}" 需人工核对` };
+      }
+    }
+    case 'credential': {
+      if (entry.existed) {
+        // 值不可回读：无法自动恢复原值
+        return {
+          reason: 'DSH 不回读凭据值，无法自动恢复',
+          manualHint: `凭据 "${entry.ref}" 请人工重新填写`,
+        };
+      }
+      try {
+        await ctx.credentials.unset(entry.ref);
+        return null;
+      } catch (err) {
+        return { reason: err instanceof Error ? err.message : String(err) };
+      }
+    }
+    case 'patchLine': {
+      try {
+        const file = entry.ref.split('\u0000')[0] ?? 'cordis.patch.yml';
+        const lineId = entry.ref.includes('\u0000') ? entry.ref.split('\u0000')[1]! : entry.ref;
+        await ctx.patchFile.applyPatchChanges(file, [
+          { lineId, raw: entry.before, action: entry.before === null ? 'remove' : 'update' },
+        ]);
+        return null;
+      } catch (err) {
+        return { reason: err instanceof Error ? err.message : String(err), manualHint: `patch 行 "${entry.ref}" 需人工核对` };
+      }
+    }
+    case 'file': {
+      try {
+        const abs = resolveFileTarget(ctx, entry.adapter, entry.ref);
+        if (entry.existed && entry.copiedTo && store) {
+          const data = await store.readBlob(entry.snapshotId ?? '', entry.copiedTo);
+          await ctx.fs.writeFile(abs, data);
+        } else if (!entry.existed) {
+          // 原文件不存在 → 删除导入写入的文件
+          if (await ctx.fs.exists(abs)) await ctx.fs.remove(abs);
+        }
+        return null;
+      } catch (err) {
+        return { reason: err instanceof Error ? err.message : String(err), manualHint: `文件 "${entry.ref}" 需人工恢复` };
+      }
+    }
+    case 'workspaceRecord': {
+      try {
+        if (entry.before === null) {
+          await ctx.workspace.removeRecord?.(entry.ref);
+        } else {
+          await ctx.workspace.writeRecord(entry.before as never);
+        }
+        return null;
+      } catch (err) {
+        return { reason: err instanceof Error ? err.message : String(err), manualHint: `workspace "${entry.ref}" 需人工核对` };
+      }
+    }
+    default:
+      return { reason: `未知快照条目类型 ${entry.kind}` };
+  }
+}
+
+/** 回滚：逆序补偿全部条目；返回诚实报告（full / partial） */
+export async function rollback(opts: RollbackOptions): Promise<RollbackReport> {
+  const { ctx, snapshot, store, adapters } = opts;
+  const restored: string[] = [];
+  const failed: RollbackReport['failed'] = [];
+
+  // 逆序遍历；adapter 自带的 rollback? 优先，否则引擎通用补偿
+  const entries = [...snapshot.entries].reverse();
+  for (const entry of entries) {
+    const adapter = adapters?.find((a) => a.id === entry.adapter);
+    let error: { reason: string; manualHint?: string } | null = null;
+    if (adapter?.rollback) {
+      try {
+        await adapter.rollback([entry], ctx);
+      } catch (err) {
+        error = { reason: err instanceof Error ? err.message : String(err) };
+      }
+    } else {
+      error = await compensateOne(entry, ctx, store);
+    }
+    if (error === null) {
+      restored.push(`${entry.adapter}:${entry.ref}`);
+    } else {
+      failed.push({ item: `${entry.adapter}:${entry.ref}`, reason: error.reason, manualHint: error.manualHint });
+    }
+  }
+
+  return { full: failed.length === 0, restored, failed };
+}