dsh-config-manager 0.1.11 → 0.1.13

package/lib/core/run-registry.js

@@ -0,0 +1,120 @@
+/**
+ * Host 端 run 注册表（m1）：记录导出/导入任务的运行状态与真实进度。
+ *
+ * 浏览器侧通过 `/api/dsh-config-manager/progress?runId=…` 与
+ * `/api/dsh-config-manager/runs` 轮询/恢复进度（m2 store 刷新恢复、m3 进度 UI
+ * 消费）；本模块是 Host 侧的单一事实源，不依赖任何 DSH 运行时服务。
+ *
+ * 安全纪律：
+ *  - runId 由 crypto.randomBytes(16) 生成（32 hex 字符），不可猜测；
+ *  - RunState 只存非敏感摘要（分区/计数/详情文案），绝不写入密钥、密码、
+ *    秘密补录值或任何敏感内容；
+ *  - result 只存可 JSON 序列化的业务结果（导出为 { zipPath, manifest, report }，
+ *    导入为 ImportResult），不含秘密值。
+ *
+ * 生命周期：register（running）→ update（进度）→ finish（done+result）/
+ * fail（failed+error）；超过保留期（默认 30 分钟）的 run 在任意读操作时惰性清理。
+ * 并发纪律：同一 kind 已有 running 的 run 时，register 抛 RunConflictError
+ * （宿主路由以 409 拒绝新任务，防止重复导出/导入）。
+ */
+import { randomBytes } from 'node:crypto';
+/** 进行中同 kind 已有 run 时注册被拒（宿主路由 → 409）。 */
+export class RunConflictError extends Error {
+    /** 已在进行中的 run id（供客户端定位既有任务）。 */
+    runId;
+    constructor(runId, kind) {
+        super(kind === 'export'
+            ? `已有进行中的导出任务（${runId}），请等待其完成后再试`
+            : `已有进行中的导入任务（${runId}），请等待其完成后再试`);
+        this.name = 'RunConflictError';
+        this.runId = runId;
+    }
+}
+/** 完成/失败后的默认保留时长（30 分钟）。 */
+export const DEFAULT_RUN_RETENTION_MS = 30 * 60 * 1000;
+/**
+ * 内存 run 注册表。Node 单线程 + 同步 Map 读写，无并发竞争；
+ * 所有公开读方法返回状态副本，防止外部直接篡改内部状态。
+ */
+export class RunRegistry {
+    runs = new Map();
+    retentionMs;
+    now;
+    constructor(opts = {}) {
+        this.retentionMs = opts.retentionMs ?? DEFAULT_RUN_RETENTION_MS;
+        this.now = opts.now ?? (() => Date.now());
+    }
+    /** 注册新 run；同 kind 已有 running 时抛 RunConflictError。 */
+    register(kind) {
+        this.prune();
+        for (const run of this.runs.values()) {
+            if (run.kind === kind && run.status === 'running')
+                throw new RunConflictError(run.runId, kind);
+        }
+        const now = this.now();
+        const state = {
+            runId: randomBytes(16).toString('hex'),
+            kind,
+            status: 'running',
+            section: null,
+            sectionTotal: null,
+            item: null,
+            itemTotal: null,
+            detail: null,
+            createdAt: now,
+            updatedAt: now,
+        };
+        this.runs.set(state.runId, state);
+        return { ...state };
+    }
+    /** 更新进度；run 不存在返回 undefined；已完成/失败后的晚到更新被忽略（防御异步回调竞态）。 */
+    update(runId, patch) {
+        const run = this.runs.get(runId);
+        if (run === undefined)
+            return undefined;
+        if (run.status !== 'running')
+            return { ...run };
+        Object.assign(run, patch, { updatedAt: this.now() });
+        return { ...run };
+    }
+    /** 读单个 run；超过保留期或不存在返回 undefined。 */
+    get(runId) {
+        this.prune();
+        const run = this.runs.get(runId);
+        return run === undefined ? undefined : { ...run };
+    }
+    /** 列出活跃（running）run（刷新恢复时经 /runs 重订阅用）。 */
+    listActive() {
+        this.prune();
+        return [...this.runs.values()].filter((r) => r.status === 'running').map((r) => ({ ...r }));
+    }
+    /** 标记完成并写入业务结果；run 不存在返回 undefined。 */
+    finish(runId, result) {
+        const run = this.runs.get(runId);
+        if (run === undefined)
+            return undefined;
+        run.status = 'done';
+        run.result = result;
+        run.updatedAt = this.now();
+        return { ...run };
+    }
+    /** 标记失败并写入错误消息；run 不存在返回 undefined。 */
+    fail(runId, error) {
+        const run = this.runs.get(runId);
+        if (run === undefined)
+            return undefined;
+        run.status = 'failed';
+        run.error = error;
+        run.updatedAt = this.now();
+        return { ...run };
+    }
+    /** 惰性清理：超过保留期的 run（含长期 running 的僵死任务）全部移除。 */
+    prune() {
+        const cutoff = this.now() - this.retentionMs;
+        for (const [id, run] of this.runs) {
+            if (run.updatedAt < cutoff)
+                this.runs.delete(id);
+        }
+    }
+}
+//# sourceMappingURL=run-registry.js.map

package/lib/core/run-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-registry.js","sourceRoot":"","sources":["../../src/core/run-registry.ts"],"names":[],"mappings":"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"}

package/lib/core/types.d.ts

@@ -130,6 +130,8 @@ export interface HostContext {
     workspace: WorkspaceFacade;
     patchFile: PatchFileFacade;
     fs: FileSystemFacade;
+    /** 当前管理的 DSH profile 名（如 web）；引擎用它定位 profiles/<profile>/cordis.patch.yml。宿主不暴露时缺省 */
+    profile?: string;
 }
 export type PlanItemKind = 'Create' | 'Update' | 'Skip' | 'Conflict' | 'Install' | 'MissingSecret' | 'MissingDependency' | 'PathMapping' | 'Warning' | 'Error';
 export type ItemResolution = 'keepCurrent' | 'useImported' | 'review';
@@ -249,17 +251,35 @@ export interface SnapshotEntry {
     /** 所属快照 id（file 条目回滚读取 blob 时使用） */
     snapshotId?: string;
 }
+/** 快照生命周期状态（M1 增强；旧快照无此字段，视为未知/兼容） */
+export type SnapshotStatus = 'pending' | 'done' | 'rolled-back';
+/** 宿主整文件备份登记（M1）：导入前对 $DSH_HOME 关键文件的整文件快照。
+ * relPath 相对 $DSH_HOME（如 settings.yaml / cordis.patch.yml / profiles/<p>/cordis.patch.yml），
+ * blobPath 为快照内 blob 路径（existed=false 时为空串，表示该文件当时不存在）。 */
+export interface HostFileBackup {
+    relPath: string;
+    blobPath: string;
+    existed: boolean;
+}
 export interface Snapshot {
     id: string;
     createdAt: string;
     sourceZip: string;
     entries: SnapshotEntry[];
+    /** 生命周期状态：pending（已生成，导入未完成）/ done（导入成功）/ rolled-back（失败已回滚）。旧快照缺省 */
+    status?: SnapshotStatus;
+    /** 导入前已安装插件清单（M2 restore 撤销插件时与当前已装对比）。旧快照缺省 */
+    beforePlugins?: PluginInfo[];
+    /** 宿主整文件备份（settings.yaml / settings.json / cordis.patch.yml / profiles/<p>/cordis.patch.yml）。旧快照缺省 */
+    hostFileBackups?: HostFileBackup[];
 }
 /** 快照存储（默认文件实现见 core/backup.ts；测试可用内存实现） */
 export interface SnapshotStore {
     save(snapshot: Snapshot, blobs?: Map<string, Uint8Array>): Promise<string>;
     load(id: string): Promise<Snapshot>;
     readBlob(id: string, blobPath: string): Promise<Uint8Array>;
+    /** 标记快照生命周期状态（导入成功→done；失败回滚→rolled-back；持久化由实现负责） */
+    updateStatus(id: string, status: SnapshotStatus): Promise<void>;
 }
 export interface RollbackReport {
     full: boolean;

package/lib/core/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAuUA,4CAA4C;AAE5C,sBAAsB;AACtB,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAChD;QACE,KAAK,CAAC,+BAA+B,CAAC,CAAC;QACvC,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AAED,+BAA+B;AAC/B,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IACjC,MAAM,CAAe;IAC9B,YAAY,OAAe,EAAE,MAAoB;QAC/C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AA6VA,4CAA4C;AAE5C,sBAAsB;AACtB,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAChD;QACE,KAAK,CAAC,+BAA+B,CAAC,CAAC;QACvC,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AAED,+BAA+B;AAC/B,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IACjC,MAAM,CAAe;IAC9B,YAAY,OAAe,EAAE,MAAoB;QAC/C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF"}

package/lib/index.d.ts

@@ -33,7 +33,9 @@
  * official `dsh plugin --profile <name>` CLI (pnpm forwarder) and read the
  * profile's package.json / node_modules directly.
  */
+import type { ServerResponse } from 'node:http';
 import type { Context } from '@deepseek-ai/cordis';
+import { type RestorePlan, type RestoreReport } from './core/restore.ts';
 import { runDshPlugin } from './core/plugin-cli.ts';
 import type { PatchFileFacade, PluginInfo, PluginsFacade } from './core/types.ts';
 /** Stable cordis plugin name — must match the cordis.patch.yml row id. */
@@ -78,6 +80,49 @@ export declare class DshPluginsFacade implements PluginsFacade {
         needsRestart: boolean;
     }>;
 }
+/** 同步路由可预期的请求级错误（status 缺省 400；引擎/传输失败走 500） */
+export declare class SyncRouteError extends Error {
+    readonly status: number;
+    constructor(message: string, status?: number);
+}
+/** 同步路由错误统一出口：SyncRouteError 用其 status，其余 500（GitTransport 错误消息已脱敏） */
+export declare function writeSyncRouteError(res: ServerResponse, error: unknown): void;
+/** POST /restore 请求体校验（纯函数；snapshotId 拒绝路径分隔符防 join 越界）。 */
+export type BuildRestoreBodyResult = {
+    ok: true;
+    value: {
+        snapshotId: string;
+        dryRun: boolean;
+    };
+} | {
+    ok: false;
+    error: string;
+};
+export declare function buildRestoreBody(body: unknown): BuildRestoreBodyResult;
+/**
+ * 宿主侧恢复动作执行器（真实执行 restore 计划）：
+ * 整文件/文件还原与删除走 ctx.fs（home-relative facade，越界由 facade 再拦一道），
+ * blob 读取与 pre-restore 副本走快照目录（node fs），插件卸载走官方 dsh plugin CLI。
+ */
+export interface RestoreExecutor {
+    /** 读快照目录内 blob（相对 snapshotDir） */
+    readBlob(blobPath: string): Promise<Uint8Array>;
+    /** 把当前 home 文件内容复制到 <snapshotDir>/pre-restore/（覆盖/删除前的双保险） */
+    savePreRestore(relPath: string): Promise<void>;
+    existsHome(relPath: string): Promise<boolean>;
+    writeHome(relPath: string, data: Uint8Array): Promise<void>;
+    removeHome(relPath: string): Promise<void>;
+    /** 卸载插件（官方通道）；失败返回 { ok:false, message } */
+    uninstallPlugin(name: string): Promise<{
+        ok: boolean;
+        message?: string;
+    }>;
+}
+/**
+ * 按计划执行恢复动作（纯执行器；逐项 try/catch 不拖垮其余），
+ * 返回与 CLI 一致的诚实报告。顺序 = 计划顺序（整文件 → 插件 → file 补偿）。
+ */
+export declare function executeRestorePlan(plan: RestorePlan, exec: RestoreExecutor): Promise<RestoreReport>;
 /**
  * Mount the config-manager engine: host context, adapters, and the
  * /api/dsh-config-manager routes (when a webServer is present).