@logictan/dsh-config-manager 0.1.60

package/lib/ui/test-helpers.js

@@ -0,0 +1,154 @@
+/** 样本 manifest（UI 测试不关心真实字段，仅类型占位） */
+export function makeManifest() {
+    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 = {}) {
+    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 {
+    calls = [];
+    result;
+    constructor(report = makeExportReport()) {
+        this.result = {
+            zipPath: report.file.name,
+            manifest: makeManifest(),
+            report,
+        };
+    }
+    async export(opts) {
+        this.calls.push({ includeSecrets: opts.includeSecrets, only: opts.only });
+        return this.result;
+    }
+}
+/* ---------------- Import mock ---------------- */
+export function makeAnalysis(overrides = {}) {
+    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 = {}) {
+    return {
+        id: 'settings:general',
+        kind: 'Create',
+        adapter: 'settings',
+        description: '创建设置 general',
+        severity: 'info',
+        ...overrides,
+    };
+}
+export function makePlan(overrides = {}) {
+    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 = {}) {
+    return {
+        full: false,
+        restored: ['settings:a'],
+        failed: [{ item: 'plugin:x', reason: '安装失败', manualHint: '请手动安装' }],
+        ...overrides,
+    };
+}
+export function makeImportResult(overrides = {}) {
+    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 {
+    analysis;
+    plan;
+    result;
+    analyzeCalls = 0;
+    planCalls = [];
+    executeCalls = [];
+    constructor(opts = {}) {
+        this.analysis = opts.analysis ?? makeAnalysis();
+        this.plan = opts.plan ?? makePlan();
+        this.result = opts.result ?? makeImportResult();
+    }
+    async analyzeImport() {
+        this.analyzeCalls += 1;
+        return this.analysis;
+    }
+    async createImportPlan(_zip, decisions) {
+        this.planCalls.push(decisions);
+        return this.plan;
+    }
+    async decryptArchive(zipPath) {
+        // 测试用：把传入路径视为已解锁的明文 ZIP（不真正解密），无内部凭据
+        return { zipPath, refs: [] };
+    }
+    async executeImportPlan(_zip, plan, opts) {
+        this.executeCalls.push({ ...opts, plan });
+        return this.result;
+    }
+}
+//# sourceMappingURL=test-helpers.js.map

package/lib/ui/types.d.ts

@@ -0,0 +1,257 @@
+/**
+ * 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';
+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 declare const EXPORT_GROUPS: readonly ExportGroupDef[];
+/** Quick Export 推荐项 = defaultIncluded 且非 deviceSpecific（设计 §11.1） */
+export declare function isQuickRecommended(c: ExportCategory): boolean;
+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;
+export type ImportStep = 'select' | 'analyzing' | 'compatibility' | 'preview' | 'conflicts' | 'path-mapping' | 'secrets' | 'importing' | 'result';
+/** 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[];
+}
+/** 单个冲突项的视图数据：当前值 vs 导入值摘要 + 用户决策 */
+export interface ConflictViewItem {
+    item: PlanItem;
+    currentSummary?: string;
+    importedSummary?: string;
+    resolution: ItemResolution | null;
+}
+/** 路径映射编辑器的单条记录（旧前缀 → 新前缀；未解析时 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';
+export interface CompatibilityView {
+    score: CompatibilityScore;
+    sourceDsh: string;
+    targetDsh: string;
+    description: string;
+}
+/** 导入结果按分区的统计（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 declare function itemDecisionKey(item: PlanItem): string;
+/** 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>;
+}

package/lib/ui/types.js

@@ -0,0 +1,21 @@
+/** Custom Export 分组目录（规范 §1；automation 组 DSH 无对应分区，仅说明） */
+export const EXPORT_GROUPS = [
+    { 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' },
+];
+/** Quick Export 推荐项 = defaultIncluded 且非 deviceSpecific（设计 §11.1） */
+export function isQuickRecommended(c) {
+    return c.defaultIncluded && c.portability !== 'deviceSpecific';
+}
+/** 选项构造辅助：从 PlanItem 提取稳定决策键（与 core analyzer.applyItemResolution 的 id 语义一致） */
+export function itemDecisionKey(item) {
+    return item.id;
+}
+//# sourceMappingURL=types.js.map

package/lib/utils/atomic-write.d.ts

@@ -0,0 +1,88 @@
+/** 文件句柄最小面（node fs/promises FileHandle 的子集） */
+export interface AtomicHandle {
+    writeFile(data: Uint8Array): Promise<void>;
+    sync(): Promise<void>;
+    close(): Promise<void>;
+}
+/** 可注入异步文件系统门面（默认实现包 node:fs/promises；测试注入失败点） */
+export interface AtomicIo {
+    mkdir(dir: string, opts: {
+        recursive: boolean;
+    }): Promise<void>;
+    /** 目标不存在返回 null */
+    lstat(p: string): Promise<{
+        isSymbolicLink(): boolean;
+    } | null>;
+    /** 目标不存在返回 null */
+    stat(p: string): Promise<{
+        mode: number;
+    } | null>;
+    realpath(p: string): Promise<string>;
+    open(p: string, flags: string, mode?: number): Promise<AtomicHandle>;
+    rename(src: string, dst: string): Promise<void>;
+    unlink(p: string): Promise<void>;
+    copyFile(src: string, dst: string, mode?: number): Promise<void>;
+    chmod(p: string, mode: number): Promise<void>;
+    /** 父目录 fsync（POSIX strong durability）；Windows/不支持时静默 no-op */
+    fsyncDir(p: string): Promise<void>;
+    /** 重试退避（可注入便于测试） */
+    sleep(ms: number): Promise<void>;
+}
+/** 同步版注入面（atomicWriteFileSync 用；仅 plugin-cli 等同步路径） */
+export interface AtomicIoSync {
+    mkdir(dir: string, opts: {
+        recursive: boolean;
+    }): void;
+    lstat(p: string): {
+        isSymbolicLink(): boolean;
+        mode: number;
+    } | null;
+    realpath(p: string): string;
+    open(p: string, flags: string, mode?: number): number;
+    writeFd(fd: number, buf: Uint8Array): void;
+    fsyncFd(fd: number): void;
+    closeFd(fd: number): void;
+    rename(src: string, dst: string): void;
+    unlink(p: string): void;
+    /** 目录 fsync（POSIX）；Windows/不支持时 no-op */
+    fsyncDir(p: string): void;
+}
+export type SymlinkPolicy = 'follow' | 'reject';
+export interface AtomicWriteOptions {
+    /** 新文件权限；sensitive 调用显式 0o600 */
+    mode?: number;
+    /** 默认 true：目标存在则继承其 mode */
+    preserveMode?: boolean;
+    /** Windows / 目标被占用瞬时错误重试次数（默认 3） */
+    retries?: number;
+    /** 重试退避基数 ms（默认 25，翻倍递增：25→50→100） */
+    retryDelayMs?: number;
+    /** POSIX 是否 fsync 父目录（默认 true；Windows 自动跳过） */
+    fsyncDir?: boolean;
+    /** symlink 策略：默认 'follow'；sensitive 调用传 'reject' */
+    symlink?: SymlinkPolicy;
+    /** 测试注入的异步 io */
+    io?: AtomicIo;
+    /** tmp 清理失败回调（调用方接线日志，满足「清理失败留痕」要求） */
+    onCleanupFailure?: (tmp: string, err: unknown) => void;
+}
+export interface AtomicWriteSyncOptions extends Omit<AtomicWriteOptions, 'io'> {
+    syncIo?: AtomicIoSync;
+}
+/**
+ * tmp 名中 base 片段清洗：拒绝含 路径分隔符 / .. / 反斜杠 / 控制字符 / Windows 非法字符 的
+ * 目标 basename，防止恶意 base 把 tmp 引出目标目录。返回安全 base。
+ */
+export declare function sanitizeTmpBase(base: string): string;
+/**
+ * 原子写文件：同目录唯一 tmp → 写完整内容 → fsync(tmp) → rename(tmp, target)。
+ * 失败时不改写原 target（目标要么旧完整、要么新完整）。
+ */
+export declare function atomicWriteFile(target: string, data: string | Uint8Array, rawOpts?: AtomicWriteOptions): Promise<void>;
+/**
+ * 原子拷贝：copyFile(src→tmp) + fsync(tmp) + rename(tmp, dst)。
+ * 不整文件读内存（大 snapshot/session 避免双内存）。失败不改写 dst。
+ */
+export declare function atomicCopyFile(src: string, dst: string, rawOpts?: AtomicWriteOptions): Promise<void>;
+/** 同步版原子写（plugin-cli 等同步路径）。语义与 atomicWriteFile 一致。 */
+export declare function atomicWriteFileSync(target: string, data: string | Uint8Array, rawOpts?: AtomicWriteSyncOptions): void;