dsh-config-manager 0.1.0

package/src/ui/import-wizard.test.ts

@@ -0,0 +1,128 @@
+/**
+ * import-wizard 测试（m6-ui）：
+ *  - 步骤状态机 select→analyzing→compatibility→preview→importing→result
+ *  - 显式 rollbackOnError（场景 E 默认 true）
+ *  - Preview 摘要（§10）
+ *  - confirm 安全阀、进度事件、reset
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { ImportWizard } from './import-wizard.ts';
+import { MockImportPort, makeAnalysis, makeImportResult, makePlan } from './test-helpers.ts';
+
+test('import-wizard: selectZip 进入 compatibility 并保存 analysis', async () => {
+  const port = new MockImportPort();
+  const wiz = new ImportWizard({ port });
+  assert.equal(wiz.currentStep, 'select');
+
+  const analysis = await wiz.selectZip('C:\\backup\\dsh-config.zip');
+  assert.equal(port.analyzeCalls, 1);
+  assert.equal(analysis.compatibility, 'good');
+  assert.equal(wiz.currentStep, 'compatibility');
+  assert.equal(wiz.snapshot().zipPath, 'C:\\backup\\dsh-config.zip');
+});
+
+test('import-wizard: 分析失败进入 errors 并抛出', async () => {
+  const port = new MockImportPort();
+  port.analysis = makeAnalysis({ valid: false, errors: ['备份完整性校验失败'] });
+  const wiz = new ImportWizard({ port });
+  await assert.rejects(() => wiz.selectZip('x.zip'), /完整性/);
+  assert.equal(wiz.snapshot().errors.length, 1);
+});
+
+test('import-wizard: confirmCompatibility 生成计划并进入 preview', async () => {
+  const port = new MockImportPort();
+  const wiz = new ImportWizard({ port });
+  await wiz.selectZip('x.zip');
+  const plan = await wiz.confirmCompatibility();
+  assert.equal(wiz.currentStep, 'preview');
+  assert.ok(plan.items.length > 0);
+  assert.equal(port.planCalls.length, 1);
+});
+
+test('import-wizard: Preview 摘要统计（§10 数值化）', async () => {
+  const port = new MockImportPort();
+  const wiz = new ImportWizard({ port });
+  await wiz.selectZip('x.zip');
+  await wiz.confirmCompatibility();
+  const s = wiz.previewSummary();
+  assert.equal(s.willChange, 5); // Create×3 + Update×1 + Install×1（Skip/MissingSecret 不计）
+  assert.equal(s.pluginsToInstall, 1);
+  assert.equal(s.mcpAdds, 1);
+  assert.equal(s.prompts, 1);
+  assert.equal(s.conflicts, 0);
+  assert.equal(s.secretsNeeded, 1);
+  assert.equal(s.needsRestart, true);
+});
+
+test('import-wizard: execute 默认显式传 rollbackOnError=true（场景 E）', async () => {
+  const port = new MockImportPort();
+  const wiz = new ImportWizard({ port });
+  await wiz.selectZip('x.zip');
+  await wiz.confirmCompatibility();
+  const result = await wiz.execute({ confirm: true });
+
+  assert.equal(result.ok, true);
+  assert.equal(wiz.currentStep, 'result');
+  assert.equal(port.executeCalls.length, 1);
+  assert.equal(port.executeCalls[0]!.confirm, true);
+  assert.equal(port.executeCalls[0]!.rollbackOnError, true, '默认整体回滚');
+});
+
+test('import-wizard: 用户可选 rollbackOnError=false（单项失败继续 §34.17）', async () => {
+  const port = new MockImportPort();
+  const wiz = new ImportWizard({ port });
+  await wiz.selectZip('x.zip');
+  await wiz.confirmCompatibility();
+  await wiz.execute({ confirm: true, rollbackOnError: false });
+  assert.equal(port.executeCalls[0]!.rollbackOnError, false);
+});
+
+test('import-wizard: confirm=false 拒绝执行（core 安全阀透传）', async () => {
+  const port = new MockImportPort();
+  const wiz = new ImportWizard({ port });
+  await wiz.selectZip('x.zip');
+  await wiz.confirmCompatibility();
+  await assert.rejects(() => wiz.execute({ confirm: false }), /未确认/);
+  assert.equal(port.executeCalls.length, 0);
+});
+
+test('import-wizard: secretInputs 仅内存传递', async () => {
+  const port = new MockImportPort();
+  const wiz = new ImportWizard({ port });
+  await wiz.selectZip('x.zip');
+  await wiz.confirmCompatibility();
+  wiz.setSecretInputs({ K1: 'sk-xxx' });
+  await wiz.execute({ confirm: true });
+  assert.equal(port.executeCalls[0]!.secretInputs?.['K1'], 'sk-xxx');
+});
+
+test('import-wizard: 失败且回滚时发出 rolling-back 进度事件', async () => {
+  const port = new MockImportPort();
+  port.result = makeImportResult({
+    ok: false,
+    rollback: { full: true, restored: ['settings:a'], failed: [] },
+  });
+  const events: string[] = [];
+  const wiz = new ImportWizard({ port, onProgress: (e) => events.push(e.stage) });
+  await wiz.selectZip('x.zip');
+  await wiz.confirmCompatibility();
+  const result = await wiz.execute({ confirm: true });
+  assert.equal(result.ok, false);
+  assert.ok(events.includes('rolling-back'));
+  assert.ok(events.includes('done'));
+});
+
+test('import-wizard: reset 清空状态回 select', async () => {
+  const port = new MockImportPort();
+  const wiz = new ImportWizard({ port });
+  await wiz.selectZip('x.zip');
+  await wiz.confirmCompatibility();
+  await wiz.execute({ confirm: true });
+  wiz.reset();
+  const snap = wiz.snapshot();
+  assert.equal(snap.step, 'select');
+  assert.equal(snap.zipPath, null);
+  assert.equal(snap.plan, null);
+  assert.equal(snap.result, null);
+});

package/src/ui/import-wizard.ts

@@ -0,0 +1,208 @@
+/**
+ * Import 向导状态机（规范 §9/§10/§28，m6-ui）。
+ *
+ * 步骤：Select ZIP → Analyzing → Compatibility → Import Preview → Resolve Conflicts
+ *       → Path Mapping → Secrets → Importing → Result。
+ *
+ * 关键安全/正确性约束：
+ *  - analyzeImport / createImportPlan 零写入（Dry Run 复用，规范 §10）；
+ *  - executeImportPlan 必须 confirm=true（core 安全阀），UI 在用户点「确认导入」后传入；
+ *  - **显式传 rollbackOnError**：场景 E（§36）要求导入中途失败整体回滚，
+ *    本向导默认 rollbackOnError=true，UI 可在执行前让用户选择（true=整体回滚 / false=单项失败继续 §34.17）；
+ *  - 秘密补录值仅内存（secretInputs），绝不落日志/落盘。
+ */
+import type {
+  GlobalConflictStrategy, ImportAnalysis, ImportDecisions, ImportPlan, ImportResult,
+  PathMapping, PlanItem,
+} from '../core/types.ts';
+import type { ImportPort, ImportPreviewSummary, ImportStep, ProgressListener, WizardSnapshot } from './types.ts';
+import { IMPORT_STAGES, ProgressTracker } from './progress.ts';
+import { formatActionableError, toActionableError } from './errors.ts';
+
+export interface ImportWizardOptions {
+  port: ImportPort;
+  onProgress?: ProgressListener;
+  /** 默认回滚策略（场景 E：true=整体回滚；UI 可在执行前覆盖） */
+  defaultRollbackOnError?: boolean;
+}
+
+export class ImportWizard {
+  private readonly port: ImportPort;
+  private readonly onProgress: ProgressListener | undefined;
+  private readonly tracker: ProgressTracker;
+  private step: ImportStep = 'select';
+  private zipPath: string | null = null;
+  private analysis: ImportAnalysis | null = null;
+  private plan: ImportPlan | null = null;
+  private result: ImportResult | null = null;
+  private rollbackOnError: boolean;
+  private errors: string[] = [];
+  private decisions: ImportDecisions = {
+    strategy: 'merge',
+    resolutions: {},
+    pathMappings: [],
+  };
+  private secretInputs: Record<string, string> = {};
+
+  constructor(opts: ImportWizardOptions) {
+    this.port = opts.port;
+    this.onProgress = opts.onProgress;
+    this.tracker = new ProgressTracker(IMPORT_STAGES, this.onProgress);
+    this.rollbackOnError = opts.defaultRollbackOnError ?? true;
+  }
+
+  /** 当前状态快照（React 绑定 / 测试断言用） */
+  snapshot(): WizardSnapshot {
+    return {
+      step: this.step,
+      zipPath: this.zipPath,
+      analysis: this.analysis,
+      plan: this.plan,
+      result: this.result,
+      rollbackOnError: this.rollbackOnError,
+      errors: [...this.errors],
+    };
+  }
+
+  get currentStep(): ImportStep {
+    return this.step;
+  }
+
+  /** 步骤 1-2：选 ZIP → Analyzing → Compatibility（analyzeImport 零写入） */
+  async selectZip(path: string): Promise<ImportAnalysis> {
+    this.zipPath = path;
+    this.step = 'analyzing';
+    this.tracker.emit('validating');
+    this.errors = [];
+    try {
+      this.analysis = await this.port.analyzeImport(path);
+      this.tracker.emit('checking-compatibility');
+      if (!this.analysis.valid) {
+        // 分析失败（完整性/schema/兼容性）：错误进 errors，UI 停在失败态
+        this.errors.push(...this.analysis.errors.map((e) => formatActionableError(toActionableError(new Error(e)))));
+        throw new Error(this.analysis.errors.join('; ') || '备份分析失败');
+      }
+      this.step = 'compatibility';
+      return this.analysis;
+    } catch (err) {
+      // 仅当尚未记录分析错误时才追加（避免重复）
+      if (this.errors.length === 0) {
+        this.errors.push(formatActionableError(toActionableError(err)));
+      }
+      throw err;
+    }
+  }
+
+  /** 步骤 3→4：用户确认兼容性后进入 Preview（Dry Run：用当前决策生成计划摘要，零写入） */
+  async confirmCompatibility(): Promise<ImportPlan> {
+    if (this.analysis === null || this.zipPath === null) {
+      throw new Error('尚未完成分析，请先选择备份文件');
+    }
+    this.plan = await this.port.createImportPlan(this.zipPath, this.decisions);
+    this.step = 'preview';
+    return this.plan;
+  }
+
+  /** 更新全局冲突策略（merge/replace/skipExisting，规范 §11） */
+  setStrategy(strategy: GlobalConflictStrategy): void {
+    this.decisions = { ...this.decisions, strategy };
+  }
+
+  /** 设置逐项冲突决策（keepCurrent/useImported/review） */
+  setResolutions(resolutions: Record<string, 'keepCurrent' | 'useImported' | 'review'>): void {
+    this.decisions = { ...this.decisions, resolutions };
+  }
+
+  /** 设置路径映射（§12） */
+  setPathMappings(mappings: PathMapping[]): void {
+    this.decisions = { ...this.decisions, pathMappings: mappings };
+  }
+
+  /** 设置秘密补录值（仅内存，绝不持久化） */
+  setSecretInputs(inputs: Record<string, string>): void {
+    this.secretInputs = inputs;
+  }
+
+  /** Preview 摘要（规范 §10 数值化；基于当前 plan 与 analysis） */
+  previewSummary(): ImportPreviewSummary {
+    const items = this.plan?.items ?? [];
+    const analysis = this.analysis;
+    const count = (kinds: PlanItem['kind'][]): number =>
+      items.filter((i) => kinds.includes(i.kind)).length;
+    return {
+      willChange: count(['Create', 'Update', 'Install', 'Conflict']),
+      unchanged: count(['Skip']),
+      settingsUpdates: count(['Create', 'Update']),
+      pluginsInstalled: analysis?.pluginSummary.installed ?? 0,
+      pluginsToInstall: count(['Install']),
+      mcpAdds: items.filter((i) => i.adapter === 'mcp' && i.kind === 'Create').length,
+      prompts: items.filter((i) => i.adapter === 'prompts' && i.kind !== 'Skip').length,
+      pathMappingsNeeded: analysis?.pathIssues.length ?? 0,
+      secretsNeeded: this.plan?.missingSecrets.length ?? analysis?.secretCount ?? 0,
+      conflicts: count(['Conflict']),
+      needsRestart: this.plan?.needsRestart ?? false,
+    };
+  }
+
+  /** 冲突项（供 ConflictCollector 使用） */
+  conflictItems(): PlanItem[] {
+    return (this.plan?.items ?? []).filter((i) => i.kind === 'Conflict');
+  }
+
+  /** 设置回滚策略（场景 E 选择；执行前调用） */
+  setRollbackOnError(enable: boolean): void {
+    this.rollbackOnError = enable;
+  }
+
+  /**
+   * 步骤 10-14：确认导入 → 快照 → 执行 → 校验 → 结果。
+   * 用最终决策重建计划（与预览一致），显式传 rollbackOnError。
+   */
+  async execute(opts: { confirm: boolean; rollbackOnError?: boolean }): Promise<ImportResult> {
+    if (this.zipPath === null || this.analysis === null) {
+      throw new Error('尚未完成分析，请先选择备份文件');
+    }
+    if (opts.confirm !== true) {
+      throw new Error('导入未确认：必须确认后才允许修改任何数据');
+    }
+    const rollbackOnError = opts.rollbackOnError ?? this.rollbackOnError;
+    this.step = 'importing';
+    this.tracker.emit('creating-snapshot');
+
+    try {
+      // 用最终决策重建计划（与预览逻辑一致，保证 Dry Run 与真实导入一致）
+      this.plan = await this.port.createImportPlan(this.zipPath, this.decisions);
+      this.tracker.emit('restoring-settings');
+      this.tracker.emit('restoring-plugins');
+      this.tracker.emit('restoring-mcp');
+      this.tracker.emit('validating-config');
+      this.result = await this.port.executeImportPlan(this.zipPath, this.plan, {
+        confirm: true,
+        secretInputs: this.secretInputs,
+        rollbackOnError,
+      });
+      // 失败且已整体回滚（场景 E）→ 报告回滚阶段
+      if (!this.result.ok && this.result.rollback) {
+        this.tracker.emit('rolling-back');
+      }
+      this.tracker.emit('done');
+      this.step = 'result';
+      return this.result;
+    } catch (err) {
+      this.errors.push(formatActionableError(toActionableError(err)));
+      throw err;
+    }
+  }
+
+  /** 重置向导（可复用实例开始新导入） */
+  reset(): void {
+    this.step = 'select';
+    this.zipPath = null;
+    this.analysis = null;
+    this.plan = null;
+    this.result = null;
+    this.errors = [];
+    this.decisions = { strategy: 'merge', resolutions: {}, pathMappings: [] };
+    this.secretInputs = {};
+  }
+}

package/src/ui/path-mapping.test.ts

@@ -0,0 +1,67 @@
+/**
+ * path-mapping 测试（m6-ui，规范 §12）：
+ * 单项映射 + 批量前缀映射、preview 替换、toPathMappings 只含已解析、isComplete。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { PathMappingEditor } from './path-mapping.ts';
+import type { PathIssue } from '../core/types.ts';
+
+const ISSUES: PathIssue[] = [
+  { kind: 'missing', value: 'C:\\Users\\alice\\projects\\ops' },
+  { kind: 'platformMismatch', value: 'C:\\Users\\alice\\projects\\dev' },
+  { kind: 'missing', value: '/Users/alice/work' },
+];
+
+test('path-mapping: 从 issues 初始化草稿，全部未解析', () => {
+  const ed = new PathMappingEditor({ issues: ISSUES });
+  assert.equal(ed.all.length, 3);
+  assert.equal(ed.unresolved.length, 3);
+  assert.equal(ed.isComplete, false);
+  assert.equal(ed.toPathMappings().length, 0);
+});
+
+test('path-mapping: 单项映射后 toPathMappings 只含已解析', () => {
+  const ed = new PathMappingEditor({ issues: ISSUES });
+  ed.setMapping('C:\\Users\\alice\\projects\\ops', 'D:\\data\\ops');
+  const mappings = ed.toPathMappings();
+  assert.equal(mappings.length, 1);
+  assert.equal(mappings[0]!.oldPrefix, 'C:\\Users\\alice\\projects\\ops');
+  assert.equal(mappings[0]!.newPrefix, 'D:\\data\\ops');
+  assert.deepEqual(mappings[0]!.appliesTo, []);
+  assert.equal(ed.unresolved.length, 2);
+  assert.equal(ed.isComplete, false);
+});
+
+test('path-mapping: 批量前缀映射聚合到单条 draft', () => {
+  const ed = new PathMappingEditor({ issues: ISSUES });
+  ed.setMapping('C:\\Users\\alice\\', 'C:\\Users\\bob\\');
+  const mappings = ed.toPathMappings();
+  assert.equal(mappings.length, 1);
+  assert.equal(mappings[0]!.oldPrefix, 'C:\\Users\\alice\\');
+  // 三条 issue 中两条以该前缀开头 → 全部视为已解决；/Users/alice/work 未解决
+  assert.equal(ed.unresolved.length, 1);
+});
+
+test('path-mapping: preview 用 applyPrefixMappings 替换', () => {
+  const ed = new PathMappingEditor({ issues: ISSUES });
+  ed.setMapping('C:\\Users\\alice\\', 'C:\\Users\\bob\\');
+  assert.equal(ed.preview('C:\\Users\\alice\\projects\\ops'), 'C:/Users/bob/projects/ops');
+  assert.equal(ed.preview('/Users/alice/work'), '/Users/alice/work');
+});
+
+test('path-mapping: 全部解决后 isComplete 为 true', () => {
+  const ed = new PathMappingEditor({ issues: ISSUES });
+  ed.setMapping('C:\\Users\\alice\\', 'C:\\Users\\bob\\');
+  ed.setMapping('/Users/alice/work', '/home/bob/work');
+  assert.equal(ed.isComplete, true);
+  assert.equal(ed.toPathMappings().length, 2);
+});
+
+test('path-mapping: existing 预置映射可直接复用（oldPrefix 聚合）', () => {
+  const ed = new PathMappingEditor({
+    existing: [{ oldPrefix: 'C:\\Users\\alice\\', newPrefix: 'C:\\Users\\bob\\', appliesTo: ['workspaces', 'mcp'] }],
+  });
+  assert.equal(ed.resolved.length, 1);
+  assert.deepEqual(ed.resolved[0]!.appliesTo, ['workspaces', 'mcp']);
+});

package/src/ui/path-mapping.ts

@@ -0,0 +1,103 @@
+/**
+ * 路径映射编辑器（规范 §12，m6-ui）。
+ *
+ * 两种形态（§12 批量映射优先）：
+ *  - 单项映射：某条具体 PathIssue（如 workspace 绝对路径）→ 新路径；
+ *  - 批量前缀映射：oldPrefix → newPrefix，一次替换全部相关路径。
+ *
+ * 输出 core PathMapping[]：newPrefix 非空的映射才进入执行计划
+ * （core mergePathMappings 只保留已解析映射；未解析项保留在 plan.items 供 UI 提示）。
+ * 应用范围 appliesTo 缺省 []（全部相关分区），与 core applyMappingsToSections 语义一致。
+ */
+import type { PathIssue, PathMapping } from '../core/types.ts';
+import { applyPrefixMappings } from '../utils/paths.ts';
+import type { PathMappingAppliesTo, PathMappingDraft } from './types.ts';
+
+export interface PathMappingEditorOptions {
+  /** 从分析结果得到的路径问题 */
+  issues?: PathIssue[];
+  /** 预置映射（如上次导入可复用的映射） */
+  existing?: PathMapping[];
+}
+
+export class PathMappingEditor {
+  private readonly issues: PathIssue[];
+  private drafts = new Map<string, PathMappingDraft>();
+
+  constructor(opts: PathMappingEditorOptions = {}) {
+    this.issues = opts.issues ?? [];
+    for (const issue of this.issues) {
+      this.drafts.set(issue.value, {
+        oldPrefix: issue.value,
+        newPrefix: issue.mappedTo ?? '',
+        issue,
+        appliesTo: [],
+      });
+    }
+    // 批量映射按 oldPrefix 聚合（一个 oldPrefix 一条 draft）
+    for (const m of opts.existing ?? []) {
+      const prev = this.drafts.get(m.oldPrefix);
+      this.drafts.set(m.oldPrefix, {
+        oldPrefix: m.oldPrefix,
+        newPrefix: m.newPrefix,
+        appliesTo: [...m.appliesTo] as PathMappingAppliesTo[],
+      });
+      void prev;
+    }
+  }
+
+  /** 全部草稿（含未解析） */
+  get all(): PathMappingDraft[] {
+    return [...this.drafts.values()];
+  }
+
+  /** 已解析（newPrefix 非空）的草稿 */
+  get resolved(): PathMappingDraft[] {
+    return this.all.filter((d) => d.newPrefix !== '');
+  }
+
+  /** 未解析的问题（UI 需提示用户选择文件夹；按「是否被已解析映射覆盖」判断，批量前缀映射一次覆盖多条） */
+  get unresolved(): PathIssue[] {
+    const mappings = this.toPathMappings();
+    return (this.issues ?? []).filter((issue) => {
+      const mapped = applyPrefixMappings(issue.value, mappings);
+      return mapped === issue.value;
+    });
+  }
+
+  /** 单项/批量设置映射（oldPrefix 已存在则更新；否则新建批量映射） */
+  setMapping(oldPrefix: string, newPrefix: string, appliesTo: PathMappingAppliesTo[] = []): void {
+    const existing = this.drafts.get(oldPrefix);
+    this.drafts.set(oldPrefix, {
+      oldPrefix,
+      newPrefix,
+      appliesTo,
+      issue: existing?.issue,
+    });
+  }
+
+  /** 对某个具体值应用当前映射，返回替换结果（预览用；无映射则原样返回） */
+  preview(value: string): string {
+    const resolved = this.resolved.map((d) => ({
+      oldPrefix: d.oldPrefix,
+      newPrefix: d.newPrefix,
+      appliesTo: d.appliesTo,
+    }));
+    const mapped = applyPrefixMappings(value, resolved);
+    return typeof mapped === 'string' ? mapped : value;
+  }
+
+  /** 未解析项是否可进入执行（false = 有路径问题未解决） */
+  get isComplete(): boolean {
+    return this.unresolved.length === 0;
+  }
+
+  /** 输出 core PathMapping[]（仅已解析项） */
+  toPathMappings(): PathMapping[] {
+    return this.resolved.map((d) => ({
+      oldPrefix: d.oldPrefix,
+      newPrefix: d.newPrefix,
+      appliesTo: d.appliesTo as PathMapping['appliesTo'],
+    }));
+  }
+}

package/src/ui/progress.test.ts

@@ -0,0 +1,42 @@
+/**
+ * progress 测试（m6-ui，规范 §29）：阶段文案与进度追踪。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { EXPORT_STAGES, IMPORT_STAGES, ProgressTracker, stageText } from './progress.ts';
+
+test('progress: 阶段文案映射（导出/导入/回滚）', () => {
+  assert.equal(stageText('analyzing'), 'Analyzing configuration...');
+  assert.equal(stageText('creating-snapshot'), 'Creating safety snapshot...');
+  assert.equal(stageText('rolling-back'), 'Rolling back...');
+  assert.equal(stageText('restoring-mcp'), 'Restoring MCP...');
+  assert.equal(stageText('done'), 'Done');
+  // 未知阶段回退 id
+  assert.equal(stageText('unknown-phase'), 'unknown-phase');
+});
+
+test('progress: 导出阶段序列完整', () => {
+  assert.deepEqual(EXPORT_STAGES, [
+    'analyzing', 'exporting-settings', 'scanning-secrets', 'exporting-plugins',
+    'creating-archive', 'calculating-checksums', 'done',
+  ]);
+});
+
+test('progress: 导入阶段序列含快照/回滚', () => {
+  assert.ok(IMPORT_STAGES.includes('creating-snapshot'));
+  assert.ok(IMPORT_STAGES.includes('rolling-back'));
+  assert.ok(IMPORT_STAGES.includes('restoring-settings'));
+});
+
+test('progress: tracker 发出事件并带 step/total', () => {
+  const events: { stage: string; step?: number; total?: number }[] = [];
+  const t = new ProgressTracker(IMPORT_STAGES, (e) => events.push(e));
+  t.emit('validating');
+  t.emit('creating-snapshot');
+  t.emit('done');
+  assert.deepEqual(t.events, ['validating', 'creating-snapshot', 'done']);
+  assert.equal(events[0]!.step, 1);
+  assert.equal(events[0]!.total, IMPORT_STAGES.length);
+  assert.equal(events[1]!.step, 3);
+  assert.equal(events[2]!.step, IMPORT_STAGES.length);
+});

package/src/ui/progress.ts

@@ -0,0 +1,90 @@
+/**
+ * 进度阶段文案与进度追踪（规范 §29，m6-ui）。
+ *
+ * 纯文本层：每个阶段 id 有默认文案；未知阶段回退显示 id 本身。
+ * ProgressTracker 供导出/导入控制器在调用 core 前后发出阶段事件（UI 不冻结）。
+ */
+import type { ProgressEvent, ProgressListener } from './types.ts';
+
+/** 导出阶段文案（规范 §29 Export 示例） */
+export const EXPORT_STAGES: readonly string[] = [
+  'analyzing',           // Analyzing configuration...
+  'exporting-settings',  // Exporting settings...
+  'scanning-secrets',    // Scanning secrets...
+  'exporting-plugins',   // Exporting plugins...
+  'creating-archive',    // Creating archive...
+  'calculating-checksums', // Calculating checksums...
+  'done',
+] as const;
+
+/** 导入阶段文案（规范 §29 Import 示例 + 快照/回滚阶段） */
+export const IMPORT_STAGES: readonly string[] = [
+  'validating',          // Validating backup...
+  'checking-compatibility', // Checking compatibility...
+  'creating-snapshot',   // Creating safety snapshot...
+  'restoring-settings',  // Restoring settings...
+  'restoring-plugins',   // Restoring plugins...
+  'restoring-mcp',       // Restoring MCP...
+  'validating-config',   // Validating configuration...
+  'rolling-back',        // Rolling back...（仅失败回滚时）
+  'done',
+] as const;
+
+const STAGE_TEXTS: Record<string, string> = {
+  // export
+  'analyzing': 'Analyzing configuration...',
+  'exporting-settings': 'Exporting settings...',
+  'scanning-secrets': 'Scanning secrets...',
+  'exporting-plugins': 'Exporting plugins...',
+  'creating-archive': 'Creating archive...',
+  'calculating-checksums': 'Calculating checksums...',
+  // import
+  'validating': 'Validating backup...',
+  'checking-compatibility': 'Checking compatibility...',
+  'creating-snapshot': 'Creating safety snapshot...',
+  'restoring-settings': 'Restoring settings...',
+  'restoring-plugins': 'Restoring plugins...',
+  'restoring-mcp': 'Restoring MCP...',
+  'validating-config': 'Validating configuration...',
+  'rolling-back': 'Rolling back...',
+  // common
+  'done': 'Done',
+};
+
+/** 阶段 id → 用户可读文案（未知阶段回退 id） */
+export function stageText(stage: string): string {
+  return STAGE_TEXTS[stage] ?? stage;
+}
+
+/**
+ * 进度追踪器：按给定阶段序列在回调时附带 step/total 序号。
+ * 控制器调用 core 前后 emit()，UI 侧渲染进度条/阶段文字。
+ */
+export class ProgressTracker {
+  private readonly listener: ProgressListener | undefined;
+  private readonly stages: readonly string[];
+  private readonly emitted: string[] = [];
+
+  constructor(stages: readonly string[], listener?: ProgressListener) {
+    this.stages = stages;
+    this.listener = listener;
+  }
+
+  /** 发出某阶段事件（可携带 detail）；未在序列中的阶段 step/total 缺省 */
+  emit(stage: string, detail?: string): void {
+    const idx = this.stages.indexOf(stage);
+    const event: ProgressEvent = {
+      stage,
+      detail,
+      step: idx >= 0 ? idx + 1 : undefined,
+      total: idx >= 0 ? this.stages.length : undefined,
+    };
+    this.emitted.push(stage);
+    this.listener?.(event);
+  }
+
+  /** 已发出阶段的快照（测试与日志用） */
+  get events(): readonly string[] {
+    return [...this.emitted];
+  }
+}