@logictan/dsh-config-manager 0.1.60

package/src/ui/report.ts

@@ -0,0 +1,146 @@
+/**
+ * 报告渲染（规范 §21 导出报告 / §22 导入报告 / §17 回滚报告，m6-ui）。
+ *
+ * 纯文本渲染：输出用户可读的多行文本（未来 React 客户端可直接替换为组件渲染）。
+ * 导入报告按分区统计：从 ExecutedItem.itemId 前缀推断所属分区（与 adapters 的 id 规则一致）。
+ */
+import type { SectionId } from '../schema/types.ts';
+import type {
+  ExecutedItem, ExportReport, ImportResult, RollbackReport,
+} from '../core/types.ts';
+import type { ImportResultAction, ImportSectionStat } from './types.ts';
+import { zhUiT, type UiT } from './i18n.ts';
+
+/* ---------------- §21 导出报告 ---------------- */
+
+export function renderExportReport(report: ExportReport, t: UiT = zhUiT): string {
+  const lines: string[] = [t('report.backupCreated'), ''];
+  lines.push(t('report.included'));
+  for (const { section, counts } of report.included) {
+    const detail = Object.entries(counts)
+      .map(([k, v]) => `${v} ${k}`)
+      .join(', ');
+    lines.push(`  ✓ ${section}${detail !== '' ? ` (${detail})` : ''}`);
+  }
+  lines.push('');
+  if (report.excluded.length > 0) {
+    lines.push(t('report.excluded'));
+    for (const s of report.excluded) lines.push(`  ○ ${s}`);
+    lines.push('');
+  }
+  lines.push(t('report.security'));
+  lines.push(`  ✓ ${t('report.apiKeysExcluded')} ${report.security.secretsExcluded ? t('report.yes') : t('report.no')}`);
+  lines.push(`  ✓ ${t('report.containsSecrets')} ${report.security.containsSecrets ? t('report.yesEncrypted') : t('report.no')}`);
+  lines.push(`  ✓ ${t('report.encrypted')} ${report.security.encrypted ? t('report.yes') : t('report.no')}`);
+  if (report.security.redactedHits > 0) lines.push(`  ⚠ ${t('report.redacted', { count: String(report.security.redactedHits) })}`);
+  lines.push('');
+  lines.push(`${t('report.file')} ${report.file.name} (${formatBytes(report.file.sizeBytes)})`);
+  for (const w of report.warnings) lines.push(`  ⚠ ${w}`);
+  return lines.join('\n');
+}
+
+/* ---------------- §22 导入报告 ---------------- */
+
+/** 从 itemId 前缀推断所属分区（与 adapters id 规则对齐；未知归 'other'） */
+export function sectionFromItemId(itemId: string): SectionId | 'other' {
+  if (itemId.startsWith('settings:')) return 'settings';
+  if (itemId.startsWith('ui:')) return 'ui';
+  if (itemId.startsWith('provider:')) return 'providers';
+  if (itemId.startsWith('plugin:') || itemId.startsWith('patch:')) return 'plugins';
+  if (itemId.startsWith('mcp:')) return 'mcp';
+  if (itemId.startsWith('prompt:')) return 'prompts';
+  if (itemId.startsWith('workspace:')) return 'workspaces';
+  if (itemId.startsWith('secret:')) return 'credentialsStatus';
+  if (itemId.startsWith('skills:')) return 'skills';
+  if (itemId.startsWith('agentPresets:')) return 'agentPresets';
+  if (itemId.startsWith('agentInstructions:')) return 'agentInstructions';
+  if (itemId.startsWith('pluginFiles:')) return 'pluginFiles';
+  if (itemId.startsWith('sessions:')) return 'sessions';
+  return 'other';
+}
+
+/** 按分区聚合执行结果（统计 + 明细） */
+export function importSectionStats(executed: readonly ExecutedItem[]): ImportSectionStat[] {
+  const bySection = new Map<string, ImportSectionStat>();
+  for (const e of executed) {
+    const section = sectionFromItemId(e.itemId);
+    let stat = bySection.get(section);
+    if (!stat) {
+      stat = { section: section as SectionId, ok: 0, skipped: 0, warned: 0, failed: 0, items: [] };
+      bySection.set(section, stat);
+    }
+    if (e.status === 'ok') stat.ok += 1;
+    else if (e.status === 'skipped') stat.skipped += 1;
+    else if (e.status === 'warning') stat.warned += 1;
+    else stat.failed += 1;
+    stat.items.push(e);
+  }
+  return [...bySection.values()];
+}
+
+/** 导入报告渲染（含回滚状态；§22 动作按钮由 suggestedActions 给出） */
+export function renderImportReport(result: ImportResult, t: UiT = zhUiT): string {
+  const lines: string[] = [result.ok ? t('report.importComplete') : t('report.importFailed'), ''];
+  // F4：被删除墓碑过滤的条目提示（用户明确删过、不复活）
+  if ((result.skippedTombstoned?.length ?? 0) > 0) {
+    lines.push(t('report.tombstonedSkipped', { count: String(result.skippedTombstoned!.length) }));
+    lines.push('');
+  }
+  const stats = importSectionStats(result.executed);
+  for (const s of stats) {
+    const parts: string[] = [];
+    if (s.ok > 0) parts.push(`✓ ${s.ok} ${t('report.importedRestored')}`);
+    if (s.skipped > 0) parts.push(`- ${s.skipped} ${t('report.skipped')}`);
+    if (s.warned > 0) parts.push(`⚠ ${s.warned} ${t('report.needAttention')}`);
+    if (s.failed > 0) parts.push(`✗ ${s.failed} ${t('report.failed')}`);
+    lines.push(`${s.section}: ${parts.join(' ') || t('report.noChanges')}`);
+    // 失败/警告项给出可操作原因（§23）
+    for (const it of s.items) {
+      if (it.status === 'failed' || it.status === 'warning') {
+        lines.push(`  ${it.status === 'failed' ? t('report.reason') : t('report.note')}: ${it.message ?? t('report.unknownReason')}`);
+      }
+    }
+  }
+  if (result.missingSecrets.length > 0) {
+    lines.push(`${t('report.secrets')} ⚠ ${t('report.credentialsNeedEntry', { count: String(result.missingSecrets.length) })}`);
+  }
+  if (result.needsRestart) {
+    lines.push(t('report.restartPluginsMcp'));
+  }
+  for (const w of result.warnings) lines.push(`⚠ ${w}`);
+  if (result.rollback) {
+    lines.push('');
+    lines.push(renderRollbackReport(result.rollback, t));
+  }
+  return lines.join('\n');
+}
+
+/** 结果页动作按钮（§22）。报告已内联展示全部失败/警告项的原因与回滚详情（§23），
+ * 不再提供空操作的 Fix Issues / View Details 按钮——仅保留「完成」。 */
+export function suggestedActions(_result: ImportResult): ImportResultAction[] {
+  return ['done'];
+}
+
+/* ---------------- §17 回滚报告 ---------------- */
+
+/** 回滚报告渲染（full / partial + 人工恢复清单） */
+export function renderRollbackReport(rr: RollbackReport, t: UiT = zhUiT): string {
+  if (rr.full) {
+    return t('report.rollbackFull');
+  }
+  const lines = [t('report.rollbackPartial')];
+  lines.push(t('report.rollbackManual'));
+  for (const f of rr.failed) {
+    lines.push(`  - ${f.item}: ${f.reason}${f.manualHint ? ` (${f.manualHint})` : ''}`);
+  }
+  if (rr.restored.length > 0) lines.push(t('report.restored', { count: String(rr.restored.length) }));
+  return lines.join('\n');
+}
+
+/* ---------------- 工具 ---------------- */
+
+export function formatBytes(n: number): string {
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
+  return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+}

package/src/ui/test-helpers.ts

@@ -0,0 +1,184 @@
+/**
+ * UI 层测试辅助（m6-ui）：mock core 调用与样本数据。
+ * 仅供 src/ui/*.test.ts 使用，不参与生产构建语义。
+ */
+import type { Manifest } from '../schema/types.ts';
+import type {
+  ExportReport, ImportAnalysis, ImportDecisions, ImportPlan, ImportResult,
+  PlanItem, RollbackReport,
+} from '../core/types.ts';
+import type { ExportPort } from './export-flow.ts';
+import type { ImportPort } from './types.ts';
+
+/** 样本 manifest（UI 测试不关心真实字段，仅类型占位） */
+export function makeManifest(): Manifest {
+  return {
+    schemaVersion: 1,
+    exporter: { name: 'dsh-config-manager-test', version: '0.0.0' },
+    source: { dshVersion: '0.1.0-rc.6', platform: 'win32', arch: 'x64' },
+    exportedAt: '2026-08-14T12:00:00.000Z',
+    sections: {
+      settings: true, ui: false, providers: false, plugins: false, mcp: false, prompts: false,
+      skills: false, agentPresets: false, agentInstructions: false, workspaces: false, pluginFiles: false,
+      credentialsStatus: false, secrets: false, sessions: false, self: false,
+    },
+    security: { containsSecrets: false, encrypted: false, encryption: null },
+  };
+}
+
+export function makeExportReport(overrides: Partial<ExportReport> = {}): ExportReport {
+  return {
+    included: [
+      { section: 'settings', counts: { namespaces: 3 } },
+      { section: 'plugins', counts: { plugins: 8 } },
+    ],
+    excluded: ['sessions', 'pluginFiles'],
+    security: { secretsExcluded: true, containsSecrets: false, encrypted: false, redactedHits: 2 },
+    file: { name: 'dsh-config-2026-08-14.zip', sizeBytes: 20480 },
+    warnings: [],
+    ...overrides,
+  };
+}
+
+/** 内存 ExportPort mock：记录调用参数，返回固定结果 */
+export class MockExportPort implements ExportPort {
+  calls: { includeSecrets: boolean; only?: string[] }[] = [];
+  result: { zipPath: string; manifest: Manifest; report: ExportReport };
+  constructor(report: ExportReport = makeExportReport()) {
+    this.result = {
+      zipPath: report.file.name,
+      manifest: makeManifest(),
+      report,
+    };
+  }
+  async export(opts: { includeSecrets: boolean; only?: string[] }): Promise<{ zipPath: string; manifest: Manifest; report: ExportReport }> {
+    this.calls.push({ includeSecrets: opts.includeSecrets, only: opts.only });
+    return this.result;
+  }
+}
+
+/* ---------------- Import mock ---------------- */
+
+export function makeAnalysis(overrides: Partial<ImportAnalysis> = {}): ImportAnalysis {
+  return {
+    valid: true,
+    errors: [],
+    warnings: [],
+    compatibility: 'good',
+    sectionsInZip: ['settings', 'plugins', 'mcp', 'prompts'],
+    unsupportedSections: [],
+    unsupportedVersions: [],
+    pluginSummary: { installed: 6, toInstall: 2 },
+    pathIssues: [],
+    secretCount: 3,
+    dependencyIssues: [],
+    encrypted: false,
+    ...overrides,
+  };
+}
+
+export function makePlanItem(overrides: Partial<PlanItem> = {}): PlanItem {
+  return {
+    id: 'settings:general',
+    kind: 'Create',
+    adapter: 'settings',
+    description: '创建设置 general',
+    severity: 'info',
+    ...overrides,
+  };
+}
+
+export function makePlan(overrides: Partial<ImportPlan> = {}): ImportPlan {
+  return {
+    items: [
+      makePlanItem({ id: 'settings:a', kind: 'Update', description: '更新设置 a' }),
+      makePlanItem({ id: 'settings:b', kind: 'Create', description: '创建设置 b' }),
+      makePlanItem({ id: 'plugin:x', kind: 'Install', adapter: 'plugins', description: '安装插件 x' }),
+      makePlanItem({ id: 'plugin:y', kind: 'Skip', adapter: 'plugins', description: '插件 y 已一致' }),
+      makePlanItem({ id: 'prompt:p', kind: 'Create', adapter: 'prompts', description: '创建提示 p' }),
+      makePlanItem({ id: 'mcp:m', kind: 'Create', adapter: 'mcp', description: '创建 MCP m' }),
+      makePlanItem({ id: 'secret:K1', kind: 'MissingSecret', adapter: 'credentialsStatus', description: '凭据 K1 需要补录' }),
+    ],
+    globalStrategy: 'merge',
+    pathMappings: [],
+    missingSecrets: [{ ref: 'K1', required: true }],
+    needsRestart: true,
+    estimatedActions: {
+      settings: 2, ui: 0, providers: 0, plugins: 1, mcp: 1, prompts: 1,
+      skills: 0, agentPresets: 0, agentInstructions: 0, workspaces: 0, pluginFiles: 0,
+      credentialsStatus: 0, secrets: 0, sessions: 0, self: 0,
+    },
+    ...overrides,
+  };
+}
+
+export function makeRollbackReport(overrides: Partial<RollbackReport> = {}): RollbackReport {
+  return {
+    full: false,
+    restored: ['settings:a'],
+    failed: [{ item: 'plugin:x', reason: '安装失败', manualHint: '请手动安装' }],
+    ...overrides,
+  };
+}
+
+export function makeImportResult(overrides: Partial<ImportResult> = {}): ImportResult {
+  return {
+    ok: true,
+    executed: [
+      { itemId: 'settings:a', status: 'ok' },
+      { itemId: 'settings:b', status: 'ok' },
+      { itemId: 'plugin:x', status: 'ok', message: '需要重启生效' },
+      { itemId: 'plugin:y', status: 'skipped' },
+      { itemId: 'prompt:p', status: 'ok' },
+      { itemId: 'mcp:m', status: 'ok' },
+      { itemId: 'secret:K1', status: 'skipped', message: '凭据未提供' },
+    ],
+    needsRestart: true,
+    missingSecrets: ['K1'],
+    warnings: [],
+    rollback: null,
+    snapshotId: 'snap-1',
+    ...overrides,
+  };
+}
+
+/** 内存 ImportPort mock：可编排各阶段返回与调用记录 */
+export class MockImportPort implements ImportPort {
+  analysis: ImportAnalysis;
+  plan: ImportPlan;
+  result: ImportResult;
+  analyzeCalls = 0;
+  planCalls: ImportDecisions[] = [];
+  executeCalls: { confirm: boolean; secretInputs?: Record<string, string>; rollbackOnError: boolean; decryptPassword?: string; plan?: ImportPlan }[] = [];
+
+  constructor(opts: {
+    analysis?: ImportAnalysis;
+    plan?: ImportPlan;
+    result?: ImportResult;
+  } = {}) {
+    this.analysis = opts.analysis ?? makeAnalysis();
+    this.plan = opts.plan ?? makePlan();
+    this.result = opts.result ?? makeImportResult();
+  }
+
+  async analyzeImport(): Promise<ImportAnalysis> {
+    this.analyzeCalls += 1;
+    return this.analysis;
+  }
+  async createImportPlan(_zip: string, decisions: ImportDecisions): Promise<ImportPlan> {
+    this.planCalls.push(decisions);
+    return this.plan;
+  }
+  async decryptArchive(zipPath: string): Promise<{ zipPath: string; refs: string[] }> {
+    // 测试用：把传入路径视为已解锁的明文 ZIP（不真正解密），无内部凭据
+    return { zipPath, refs: [] };
+  }
+  async executeImportPlan(
+    _zip: string,
+    plan: ImportPlan,
+    opts: { confirm: boolean; secretInputs?: Record<string, string>; rollbackOnError: boolean; decryptPassword?: string },
+  ): Promise<ImportResult> {
+    this.executeCalls.push({ ...opts, plan });
+    return this.result;
+  }
+}

package/src/ui/types.ts

@@ -0,0 +1,325 @@
+/**
+ * UI 层共享类型（m6-ui，框架无关）。
+ *
+ * 设计原则（对齐 Docs/design/architecture.md §12.2 与规范 §28/§29）：
+ *  - 本模块为纯 TypeScript 逻辑层，不引入 React / 打包器 / 任何运行时依赖；
+ *  - 未来 React 客户端（src/client/）直接消费本层的控制器输出（渲染文本 / 状态快照）；
+ *  - UI 层不直接 import core 的类实现，只依赖 core/types.ts 的纯类型 + 注入的「端口」
+ *    （ExportPort / ImportPort，宿主在 settings.section 挂载时把真实 Exporter/Importer 接入）。
+ */
+import type { SectionId } from '../schema/types.ts';
+import type {
+  CompatibilityScore, ImportAnalysis, ImportDecisions, ImportPlan, ImportResult,
+  ItemResolution, PathIssue, PlanItem, Portability, RollbackReport,
+} from '../core/types.ts';
+
+/* ---------------- 导出（规范 §1 / §21） ---------------- */
+
+export type ExportMode = 'quick' | 'custom';
+
+/** Custom Export 分组（规范 §1 分类；automation 组在 DSH 中无对应分区，UI 标注说明） */
+export type ExportGroup =
+  | 'general' | 'ai' | 'extensions' | 'mcp' | 'customization'
+  | 'automation' | 'workspace' | 'ui' | 'optional';
+
+/** 分类树节点（与 adapters 的 displayName/defaultIncluded/portability 对齐；宿主可注入覆盖） */
+export interface ExportCategory {
+  id: SectionId;
+  label: string;
+  description: string;
+  defaultIncluded: boolean;
+  portability: Portability;
+  group: ExportGroup;
+  /** 涉及秘密状态（如 credentialsStatus）：UI 需展示安全提示但绝不显示值 */
+  sensitive?: boolean;
+}
+
+export interface ExportGroupDef {
+  id: ExportGroup;
+  label: string;
+  /** automation 组在 DSH 无对应配置时的说明 */
+  note?: string;
+}
+
+/** Custom Export 分组目录（规范 §1；automation 组 DSH 无对应分区，仅说明） */
+export const EXPORT_GROUPS: readonly ExportGroupDef[] = [
+  { id: 'general', label: 'General' },
+  { id: 'ai', label: 'AI' },
+  { id: 'extensions', label: 'Extensions' },
+  { id: 'mcp', label: 'MCP / Tools' },
+  { id: 'customization', label: 'Customization' },
+  { id: 'automation', label: 'Automation', note: 'DSH 当前无 Workflows / Commands 配置文件（运行时注册），无迁移内容' },
+  { id: 'workspace', label: 'Workspace' },
+  { id: 'ui', label: 'UI' },
+  { id: 'optional', label: 'Optional Data' },
+] as const;
+
+/** Quick Export 推荐项 = defaultIncluded 且非 deviceSpecific（设计 §11.1） */
+export function isQuickRecommended(c: ExportCategory): boolean {
+  return c.defaultIncluded && c.portability !== 'deviceSpecific';
+}
+
+/* ---------------- 进度事件（规范 §29） ---------------- */
+
+export interface ProgressEvent {
+  /** 阶段 id（见 progress.ts 的 STAGE_TEXTS） */
+  stage: string;
+  detail?: string;
+  /** 阶段序号（从 1 起，供 UI 显示 n/m） */
+  step?: number;
+  /** 阶段总数 */
+  total?: number;
+}
+
+export type ProgressListener = (event: ProgressEvent) => void;
+
+/* ---------------- 导入向导（规范 §9 / §10 / §28） ---------------- */
+
+export type ImportStep =
+  | 'select'          // 选 ZIP
+  | 'analyzing'       // Analyzing...
+  | 'compatibility'   // Compatibility
+  | 'preview'         // Import Preview（Dry Run 摘要）
+  | 'conflicts'       // Resolve Conflicts（§11）
+  | 'path-mapping'    // Path Mapping（§12）
+  | 'secrets'         // Secrets 补录（§7）
+  | 'importing'       // Importing（含快照/回滚阶段）
+  | 'result';         // Result（§22）
+
+/** Preview 摘要（规范 §10 示例的数值化版本） */
+export interface ImportPreviewSummary {
+  /** 将更新的配置项数（Create+Update+Install 合计） */
+  willChange: number;
+  /** 已存在且一致的项（Skip） */
+  unchanged: number;
+  settingsUpdates: number;
+  pluginsInstalled: number;
+  pluginsToInstall: number;
+  mcpAdds: number;
+  prompts: number;
+  pathMappingsNeeded: number;
+  secretsNeeded: number;
+  conflicts: number;
+  needsRestart: boolean;
+}
+
+/** 向导状态快照（React 客户端可直接绑定渲染） */
+export interface WizardSnapshot {
+  step: ImportStep;
+  zipPath: string | null;
+  analysis: ImportAnalysis | null;
+  plan: ImportPlan | null;
+  result: ImportResult | null;
+  /** 导入执行的回滚策略（场景 E：默认 true 整体回滚） */
+  rollbackOnError: boolean;
+  errors: string[];
+}
+
+/* ---------------- 冲突视图（规范 §11） ---------------- */
+
+/** 单个冲突项的视图数据：当前值 vs 导入值摘要 + 用户决策 */
+export interface ConflictViewItem {
+  item: PlanItem;
+  currentSummary?: string;
+  importedSummary?: string;
+  resolution: ItemResolution | null;
+}
+
+/* ---------------- 路径映射（规范 §12） ---------------- */
+
+/** 路径映射编辑器的单条记录（旧前缀 → 新前缀；未解析时 newPrefix 为空串） */
+export interface PathMappingDraft {
+  /** 关联的原始路径问题值（一条 issue 一条 draft；批量映射用 oldPrefix 聚合） */
+  oldPrefix: string;
+  newPrefix: string;
+  issue?: PathIssue;
+  /** 应用范围（缺省 [] = 全部相关分区，与 core applyMappingsToSections 语义一致） */
+  appliesTo: PathMappingAppliesTo[];
+}
+
+/** 与 core PathMapping.appliesTo 对齐的取值（留空数组 = 全应用） */
+export type PathMappingAppliesTo = 'workspaces' | 'mcp' | 'pluginConfig' | 'skills';
+
+/* ---------------- 兼容性（规范 §30） ---------------- */
+
+export interface CompatibilityView {
+  score: CompatibilityScore;
+  sourceDsh: string;
+  targetDsh: string;
+  description: string;
+}
+
+/* ---------------- 报告（规范 §21 / §22 / §17） ---------------- */
+
+/** 导入结果按分区的统计（report.ts 用） */
+export interface ImportSectionStat {
+  section: SectionId;
+  ok: number;
+  skipped: number;
+  warned: number;
+  failed: number;
+  items: { itemId: string; status: 'ok' | 'skipped' | 'warning' | 'failed'; message?: string }[];
+}
+
+export type ImportResultAction = 'fixIssues' | 'viewDetails' | 'done';
+
+export interface RollbackView {
+  report: RollbackReport | null;
+  /** 是否有可展示的人工恢复清单（partial 回滚时） */
+  hasManualRecovery: boolean;
+}
+
+/* ---------------- 控制器公共依赖注入 ---------------- */
+
+/** UI 层与 core 的导入端口（宿主注入真实 Importer；测试注入内存 mock） */
+export interface ImportPort {
+  analyzeImport(zipPath: string): Promise<ImportAnalysis>;
+  createImportPlan(zipPath: string, decisions: ImportDecisions): Promise<ImportPlan>;
+  /**
+   * 解锁整体加密备份（只读，零写入）：用备份密码解密上传的加密容器，得到明文 ZIP
+   * 写入受控临时目录并返回新的 zipPath，供 analyze/plan/execute 引用。
+   * 顺带返回解密覆盖的凭据 ref 名（非值）——导出时容器密码与内部 secrets.enc
+   * 密码同源，解锁即完成凭据解密验证，无需第二次密码校验。
+   * 密码仅内存，绝不落盘/落日志；解密后的明文 ZIP 亦为临时文件，导入结束后清理。
+   */
+  decryptArchive(zipPath: string, password: string): Promise<{ zipPath: string; refs: string[] }>;
+  executeImportPlan(
+    zipPath: string,
+    plan: ImportPlan,
+    opts: {
+      /** 用户确认（安全阀，非 true 拒绝执行） */
+      confirm: boolean;
+      secretInputs?: Record<string, string>;
+      /** 显式回滚策略：true=任一项失败整体回滚（场景 E）；false=单项失败继续（§34.17） */
+      rollbackOnError: boolean;
+      /** 加密备份的解密密码（仅内存；core 拒绝加密备份无密码执行） */
+      decryptPassword?: string;
+    },
+  ): Promise<ImportResult>;
+}
+
+/** 选项构造辅助：从 PlanItem 提取稳定决策键（与 core analyzer.applyItemResolution 的 id 语义一致） */
+export function itemDecisionKey(item: PlanItem): string {
+  return item.id;
+}
+
+/* ---------------- Recovery（Phase 5：引导式恢复工作流） ---------------- */
+
+/** recovery 决策（§5.2）：rollback-recommended=恢复到 trusted snapshot；rollback-continue=续跑中断回滚；needs-attention=需人工调查。 */
+export type RecoveryDecision = 'rollback-recommended' | 'rollback-continue' | 'needs-attention';
+
+/** post-recovery verification verdict（§6.3）。 */
+export type RecoveryVerdict = 'MATCH' | 'PARTIAL_MATCH' | 'MISMATCH' | 'VERIFICATION_ERROR';
+
+/** GET /recovery/status 的单个 incident（未解决 operation）。 */
+export interface RecoveryIncident {
+  operationId: string;
+  operationType: string;
+  state: string;
+  decision: RecoveryDecision;
+  snapshotId: string | null;
+  /** 已 redact 的原因文本。 */
+  reason: string;
+  createdAt: string;
+}
+
+/** GET /recovery/status 响应。 */
+export interface RecoveryStatus {
+  incidents: RecoveryIncident[];
+  running: { runId: string; status: string }[];
+  /**
+   * 环境锁状态摘要（issue #31）。纯残留锁**不是** journal：进程在 op 期间被杀时
+   * `journalId: null`、`transactions/active/` 为空，incidents 恒为 []，而 423 文案却
+   * 让用户去「事故恢复」处理 → 面板恒空、GUI 无出路。本字段让面板能显示可执行的锁事项。
+   * 旧宿主不返回 → undefined（面板按「无锁事项」处理，不误报）。
+   */
+  lock?: RecoveryLockStatus;
+}
+
+/** 环境锁状态摘要：**只暴露分类**（owner pid/op/hostname 属内部诊断，不进 UI/响应体）。 */
+export interface RecoveryLockStatus {
+  /** LockState：STALE_LOCK_DETECTED / UNKNOWN_STATE / LOCKED / FREE / LOCK_IO_ERROR / PERMISSION_ERROR */
+  state: string;
+  /** 是否需用户显式处理（残留锁/无法判定）。LOCKED 活锁为 false —— 它会自行释放，不该催用户回收。 */
+  attention: boolean;
+}
+
+/** POST /recovery/lock/recover 响应（显式回收 stale 残留锁；拒绝时 ok=false）。 */
+export interface RecoveryLockRecoverResult {
+  ok: boolean;
+  removed: boolean;
+  state: string;
+}
+
+/** GET /recovery/:operationId/preview 响应（只读，零写入）。 */
+export interface RecoveryPreview {
+  operationId: string;
+  operationType: string;
+  state: string;
+  decision: RecoveryDecision;
+  snapshotId: string | null;
+  snapshotVerdict: string | null;
+  snapshotMeta: { id: string; createdAt: string; operationType?: string } | null;
+  environmentFingerprint: string;
+  environmentCompatible: boolean;
+  reason: string;
+  createdAt: string;
+}
+
+/** POST /recovery/:operationId/verify 响应。 */
+export interface RecoveryVerifyResult {
+  ok: boolean;
+  operationId: string;
+  verdict: RecoveryVerdict;
+  terminal: string;
+  /** 每项检查结果（已 redact）。 */
+  details: string[];
+  /** 需人工处理项（已 redact）。 */
+  manualHints: string[];
+}
+
+/** POST /recovery/:operationId/execute|retry 响应。 */
+export interface RecoveryExecuteResult {
+  ok: boolean;
+  operationId: string;
+  decision: RecoveryDecision;
+  state: string;
+  runId: string;
+}
+
+/** POST /recovery/:operationId/confirm 响应。 */
+export interface RecoveryConfirmResult {
+  ok: boolean;
+  operationId: string;
+  snapshotId: string;
+  verdict: string;
+}
+
+/** POST /recovery/:operationId/dismiss 响应。 */
+export interface RecoveryDismissResult {
+  ok: boolean;
+  operationId: string;
+  dismissed: boolean;
+}
+
+/**
+ * Recovery 端口契约（§10.3）：recovery 无现有 port（ExportPort/ImportPort 只服务控制器）。
+ * `recovery-api.ts` 实现之；`recovery-view.ts` 是纯渲染模型（非控制器），消费本端口返回的渲染数据。
+ * 安全：所有 destructive 动作（confirm/execute/retry/dismiss）必须显式传 userConfirmed=true，
+ * 由 Host 侧双重校验（请求体 + journal 状态机）。
+ */
+export interface RecoveryPort {
+  status(): Promise<RecoveryStatus>;
+  preview(operationId: string): Promise<RecoveryPreview>;
+  confirm(operationId: string, userConfirmed: boolean): Promise<RecoveryConfirmResult>;
+  execute(operationId: string, userConfirmed: boolean): Promise<RecoveryExecuteResult>;
+  verify(operationId: string): Promise<RecoveryVerifyResult>;
+  retry(operationId: string, userConfirmed: boolean): Promise<RecoveryExecuteResult>;
+  dismiss(operationId: string, userConfirmed: boolean): Promise<RecoveryDismissResult>;
+  /**
+   * POST /recovery/lock/recover（issue #31）：显式回收 stale 残留配置锁。
+   * 不带 operationId（残留锁没有 journal）；宿主侧会重新证明确属 stale 才回收，
+   * 无法证明（活锁/判定不确定/二次验证失败）→ 返回 ok=false 且不做任何改动。
+   */
+  recoverStaleLock(userConfirmed: boolean): Promise<RecoveryLockRecoverResult>;
+}