dsh-config-manager 0.1.12 → 0.1.13

package/src/core/analyzer.ts

@@ -67,6 +67,19 @@ interface AnalyzedBundle extends Bundle {
   adapterIssues: string[];
 }
 
+/** m1：每完成一个计划项的进度回调信息（Host 侧 run 状态更新用） */
+export interface PlanItemProgress {
+  adapter: SectionId;
+  /** 已处理计划项序号（1 起，含 skip/warning 信息项） */
+  index: number;
+  /** 将实际执行的计划项总数（APPLY_ORDER 内各项合计） */
+  total: number;
+  /** 该项最终状态（ok/skipped/warning/failed） */
+  status?: ExecutedItem['status'];
+  /** 当前计划项 id（非敏感） */
+  detail?: string;
+}
+
 export class Analyzer {
   private readonly ctx: HostContext;
   private readonly adapters: ConfigAdapter[];
@@ -361,7 +374,14 @@ export class Analyzer {
   async executeImportPlan(
     zipPath: string,
     plan: ImportPlan,
-    opts: { confirm?: boolean; secretInputs?: Record<string, string>; decryptedCredentials?: Map<string, string>; rollbackOnError?: boolean } = {},
+    opts: {
+      confirm?: boolean;
+      secretInputs?: Record<string, string>;
+      decryptedCredentials?: Map<string, string>;
+      rollbackOnError?: boolean;
+      /** m1：每完成一个计划项调用（真实进度埋点；不传则无埋点） */
+      onItem?: (info: PlanItemProgress) => void;
+    } = {},
   ): Promise<ImportResult> {
     const bundle = await this.loadBundle(zipPath);
     const analyzed = await this.analyzeBundle(bundle);
@@ -405,12 +425,27 @@ export class Analyzer {
       list.push(item);
       byAdapter.set(item.adapter, list);
     }
+    const totalItems = APPLY_ORDER.reduce((sum, id) => sum + (byAdapter.get(id)?.length ?? 0), 0);
+    let itemIndex = 0;
 
     for (const adapterId of APPLY_ORDER) {
       const adapter = this.adapters.find((a) => a.id === adapterId);
       if (!adapter) continue;
       for (const item of byAdapter.get(adapterId) ?? []) {
         const outcome = await this.applyOne(adapter, item, importCtx);
+        // m1 埋点：每完成一个计划项上报（真实进度；onItem 抛错不得中断导入）
+        itemIndex += 1;
+        try {
+          opts.onItem?.({
+            adapter: item.adapter,
+            index: itemIndex,
+            total: totalItems,
+            status: outcome.executed.status,
+            detail: item.id,
+          });
+        } catch {
+          // 埋点回调失败不影响导入执行（进度是尽力而为）
+        }
         executed.push(outcome.executed);
         // 仅硬失败计入 anyFailed（warning 属非致命：目标不可达等，不触发回滚，§34.17）
         if (outcome.executed.status === 'failed') anyFailed = true;
@@ -429,6 +464,8 @@ export class Analyzer {
         store: this.snapshotStore,
         adapters: this.adapters,
       });
+      // M1：回滚完成 → 快照标记 rolled-back（元数据写失败只告警，不影响回滚结论）
+      await this.markSnapshotStatus(snapshot.id, 'rolled-back');
       this.ctx.log.warn(`导入失败，已回滚（${rollbackReport.full ? '完整' : '部分'}）`, {
         failed: executed.filter((e) => e.status === 'failed').map((e) => e.itemId),
       });
@@ -462,6 +499,9 @@ export class Analyzer {
       .filter((s) => !importCtx.decryptedCredentials?.has(s.ref) && !importCtx.secretInputs[s.ref])
       .map((s) => s.ref);
 
+    // M1：导入成功 → 快照标记 done（元数据写失败只告警，不改变导入结论）
+    await this.markSnapshotStatus(snapshot.id, 'done');
+
     return {
       ok: true, // 单项失败已如实记录在 executed；无未捕获异常即完成
       executed,
@@ -473,6 +513,15 @@ export class Analyzer {
     };
   }
 
+  /** 快照状态标记（M1）：成功→done / 失败回滚→rolled-back。元数据写失败只告警不抛错。 */
+  private async markSnapshotStatus(id: string, status: 'done' | 'rolled-back'): Promise<void> {
+    try {
+      await this.snapshotStore.updateStatus(id, status);
+    } catch (err) {
+      this.ctx.log.warn(`快照 ${id} 状态标记 ${status} 失败: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
   private async applyOne(
     adapter: ConfigAdapter,
     item: PlanItem,

package/src/core/backup.ts

@@ -12,13 +12,67 @@ import { parseJsonSafe } from '../utils/json.ts';
 import { sha256Hex } from '../utils/hashing.ts';
 import type { SectionId } from '../schema/types.ts';
 import type {
-  ConfigAdapter, HostContext, ImportPlan, PlanItem, Snapshot,
-  SnapshotEntry, SnapshotStore, SnapshotTarget,
+  ConfigAdapter, HostContext, HostFileBackup, ImportPlan, PlanItem, Snapshot,
+  SnapshotEntry, SnapshotStatus, SnapshotStore, SnapshotTarget,
 } from './types.ts';
 
 /** 导入将实际写入的目标 kinds（这些项才需要快照） */
 const EXECUTABLE_KINDS = new Set(['Create', 'Update', 'Install', 'MissingSecret', 'MissingDependency']);
 
+/**
+ * 需要整文件备份的宿主关键文件（相对 $DSH_HOME）：
+ *  - settings.yaml（DSH 配置主存储；不存在时探测 settings.json）
+ *  - cordis.patch.yml（用户 patch 层）
+ *  - profiles/<profile>/cordis.patch.yml（profile patch 层，宿主暴露 profile 时）
+ */
+const HOST_FILE_CANDIDATES: ReadonlyArray<{ relPath: string }> = [
+  { relPath: 'settings.yaml' },
+  { relPath: 'settings.json' },
+  { relPath: 'cordis.patch.yml' },
+];
+
+/**
+ * 宿主整文件备份（M1）：探测存在性，存在的文件字节进 blobs Map 由 store.save 落盘，
+ * 全部候选（含 existed:false）登记进 hostFileBackups，供 M2 restore 整文件还原。
+ */
+async function backupHostFiles(
+  ctx: HostContext,
+  blobs: Map<string, Uint8Array>,
+): Promise<HostFileBackup[]> {
+  const candidates = [...HOST_FILE_CANDIDATES];
+  if (ctx.profile !== undefined && ctx.profile !== '') {
+    candidates.push({ relPath: `profiles/${ctx.profile}/cordis.patch.yml` });
+  }
+
+  const backups: HostFileBackup[] = [];
+  for (const { relPath } of candidates) {
+    // settings.yaml 与 settings.json 互斥：主存储存在时不再探测 json 备选
+    if (relPath === 'settings.json' && backups.some((b) => b.relPath === 'settings.yaml' && b.existed)) {
+      continue;
+    }
+    let existed = false;
+    try {
+      existed = await ctx.fs.exists(relPath);
+    } catch (err) {
+      ctx.log.warn(`快照探测宿主文件失败 ${relPath}: ${err instanceof Error ? err.message : String(err)}`);
+      existed = false;
+    }
+    if (!existed) {
+      backups.push({ relPath, blobPath: '', existed: false });
+      continue;
+    }
+    const blobPath = `blobs/host/${crypto.randomUUID()}`;
+    try {
+      blobs.set(blobPath, await ctx.fs.readFile(relPath));
+      backups.push({ relPath, blobPath, existed: true });
+    } catch (err) {
+      ctx.log.warn(`快照读取宿主文件失败 ${relPath}: ${err instanceof Error ? err.message : String(err)}`);
+      backups.push({ relPath, blobPath: '', existed: false });
+    }
+  }
+  return backups;
+}
+
 /** 文件类分区的目标基准目录（相对 homeDir；pluginFiles 的 ref 已是完整相对路径） */
 const FILE_BASES: Partial<Record<SectionId, string>> = {
   skills: 'skills',
@@ -152,11 +206,25 @@ export async function createSnapshot(opts: CreateSnapshotOptions): Promise<Snaps
     }
   }
 
+  // 3) 宿主整文件备份（M1）：settings.yaml/settings.json + 用户/ profile 层 cordis.patch.yml
+  const hostFileBackups = await backupHostFiles(ctx, blobs);
+
+  // 4) 导入前插件清单（M2 restore 撤销插件对比基准；读取失败不阻断快照）
+  let beforePlugins: Snapshot['beforePlugins'] = [];
+  try {
+    beforePlugins = await ctx.plugins.listInstalled();
+  } catch (err) {
+    ctx.log.warn(`快照登记插件清单失败: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
   const snapshot: Snapshot = {
     id: crypto.randomUUID(),
     createdAt: new Date().toISOString(),
     sourceZip,
     entries,
+    status: 'pending',
+    beforePlugins,
+    hostFileBackups,
   };
   // file 条目登记 snapshotId，回滚读 blob 时定位快照目录
   for (const entry of snapshot.entries) {
@@ -209,4 +277,12 @@ export class FileSnapshotStore implements SnapshotStore {
     if (!target.startsWith(dir)) throw new Error(`快照 blob 路径越界: ${blobPath}`);
     return fs.readFile(target);
   }
+
+  /** 标记快照生命周期状态：重写 <dir>/<id>/snapshot.json（保留其余字段）。 */
+  async updateStatus(id: string, status: SnapshotStatus): Promise<void> {
+    const file = path.join(this.snapshotDir(id), 'snapshot.json');
+    const snapshot = parseJsonSafe(await fs.readFile(file, 'utf8')) as Snapshot;
+    snapshot.status = status;
+    await fs.writeFile(file, JSON.stringify(snapshot, null, 2));
+  }
 }

package/src/core/exporter.ts

@@ -20,6 +20,15 @@ import type {
   ExportSection, HostContext, SecretScanner, SensitiveHit,
 } from './types.ts';
 
+/** m1：每导出一个分区前的进度回调信息（Host 侧 run 状态更新用；section = adapter id） */
+export interface SectionProgress {
+  section: string;
+  /** 当前分区序号（1 起） */
+  index: number;
+  /** 选中分区总数 */
+  total: number;
+}
+
 export interface ExporterOptions {
   ctx: HostContext;
   adapters: ConfigAdapter[];
@@ -30,6 +39,8 @@ export interface ExporterOptions {
   /** 插件自身版本（manifest.exporter.version） */
   exporterVersion?: string;
   now?: () => Date;
+  /** m1：每导出一个分区前调用（真实进度埋点；不传则无埋点） */
+  onSection?: (info: SectionProgress) => void;
 }
 
 /** 缺省 SecretScanner：递归黑名单字段剥离（字段名大小写不敏感；二进制/Uint8Array 原样跳过） */
@@ -76,6 +87,7 @@ export class Exporter {
   private readonly encryption: EncryptionProvider | null;
   private readonly exporterVersion: string;
   private readonly now: () => Date;
+  private readonly onSection: ((info: SectionProgress) => void) | undefined;
 
   constructor(opts: ExporterOptions) {
     this.ctx = opts.ctx;
@@ -84,6 +96,7 @@ export class Exporter {
     this.encryption = opts.encryption ?? null;
     this.exporterVersion = opts.exporterVersion ?? '0.1.0';
     this.now = opts.now ?? (() => new Date());
+    this.onSection = opts.onSection;
   }
 
   /**
@@ -108,8 +121,16 @@ export class Exporter {
     const included: ExportReport['included'] = [];
     const excluded: SectionId[] = this.adapters.filter((a) => !selected.includes(a.id)).map((a) => a.id);
 
+    // m1 埋点：每导出一个分区前上报真实进度（onSection 抛错不得中断导出）
+    let sectionIndex = 0;
     for (const adapter of this.adapters) {
       if (!selected.includes(adapter.id)) continue;
+      sectionIndex += 1;
+      try {
+        this.onSection?.({ section: adapter.id, index: sectionIndex, total: selected.length });
+      } catch {
+        // 埋点回调失败不影响导出本身（进度是尽力而为）
+      }
       let section: ExportSection;
       try {
         section = await adapter.export(this.ctx, options);

package/src/core/importer.ts

@@ -10,6 +10,7 @@
  */
 import type { ZipArchive, ZipSafetyLimits } from '../utils/zip.ts';
 import { Analyzer } from './analyzer.ts';
+import type { PlanItemProgress } from './analyzer.ts';
 import type {
   ConfigAdapter, HostContext, ImportAnalysis, ImportDecisions, ImportPlan,
   ImportResult, SnapshotStore,
@@ -35,6 +36,8 @@ export interface ExecuteOptions {
   decryptedCredentials?: Map<string, string>;
   /** 任一项失败立即整体回滚（默认 false：单项失败如实记录并继续其余项） */
   rollbackOnError?: boolean;
+  /** m1：每完成一个计划项的进度回调（透传给 Analyzer；不传则无埋点） */
+  onItem?: (info: PlanItemProgress) => void;
 }
 
 export class Importer {
@@ -61,6 +64,7 @@ export class Importer {
       secretInputs: opts.secretInputs,
       decryptedCredentials: opts.decryptedCredentials,
       rollbackOnError: opts.rollbackOnError,
+      onItem: opts.onItem,
     });
   }
 }

package/src/core/index.ts

@@ -16,6 +16,11 @@ export {
   type CreateSnapshotOptions, type FileSnapshotStoreOptions,
 } from './backup.ts';
 export { rollback, type RollbackOptions } from './rollback.ts';
+export {
+  planRestore, restore, listSnapshots,
+  type RestoreAction, type RestoreActionKind, type RestoreOptions,
+  type RestorePlan, type RestoreReport, type SnapshotMeta,
+} from './restore.ts';
 export {
   computeCompatibility, describeCompatibility, describeSchemaStatus,
   validateSections,