@logictan/dsh-config-manager 0.1.60

package/lib/core/cache-cleaner.js

@@ -0,0 +1,95 @@
+/**
+ * 缓存自动清理：只清「可重建 / 一次性」的临时文件与导出副本。
+ *
+ * 清理面（保留期内一律不删）：
+ *  - `tmp/`：过期 `.zip` 暂存 + SyncEngine 遗留的 `dsh-sync-pull-*` 目录；
+ *  - `exports/`：过期的导出产物 ZIP（导出时用户已下载/另存到本地）。
+ *
+ * **不清理**：`snapshots/`（回滚安全网）与 `sync/`（同步状态/快照）—— 它们是用户数据。
+ *
+ * 失败语义：任何单项失败只计入 `errors`，不影响主流程（调用方仅记日志）。
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+/** 临时文件缺省保留期：24h（供刷新恢复等窗口继续消费） */
+export const TMP_RETENTION_DEFAULT_MS = 24 * 60 * 60 * 1000;
+/** 导出产物缺省保留期：7 天（导出时用户已通过浏览器下载/另存到本地，host 端副本按周回收） */
+export const EXPORTS_RETENTION_DEFAULT_MS = 7 * 24 * 60 * 60 * 1000;
+/** SyncEngine 在 zipDir（即 tmpDir）下 mkdtemp 的目录前缀（用完即删，崩溃残留由清理兜底） */
+const SYNC_TMP_DIR_PREFIX = 'dsh-sync-pull-';
+/** 目录是否超期（stat 失败保守视为未超期 → 不删） */
+async function isExpired(target, retentionMs, nowMs) {
+    try {
+        const st = await fs.stat(target);
+        return nowMs - st.mtimeMs > retentionMs;
+    }
+    catch {
+        return false;
+    }
+}
+/** 删除一个文件/目录并计入报告；目录的 freedBytes 统计为 0（递归统计不划算，用途仅是日志） */
+async function removeEntry(target, label, result) {
+    try {
+        let size = 0;
+        try {
+            const st = await fs.stat(target);
+            size = st.isFile() ? st.size : 0;
+        }
+        catch {
+            /* stat 失败仍尝试删除（rm 自己会兜底不存在） */
+        }
+        await fs.rm(target, { recursive: true, force: true });
+        result.removed += 1;
+        result.freedBytes += size;
+        result.detail.push(`${label} (${size} bytes)`);
+    }
+    catch {
+        result.errors += 1;
+    }
+}
+/**
+ * 执行一次缓存清理（幂等；可重复调用）。
+ * 只清理超期（超过保留期）的缓存/临时条目，其余一律保留。
+ */
+export async function cleanupCaches(opts) {
+    const nowMs = (opts.now ?? Date.now)();
+    const tmpRetentionMs = opts.tmpRetentionMs ?? TMP_RETENTION_DEFAULT_MS;
+    const exportsRetentionMs = opts.exportsRetentionMs ?? EXPORTS_RETENTION_DEFAULT_MS;
+    const result = { removed: 0, freedBytes: 0, errors: 0, detail: [] };
+    // 1) tmpDir：过期 .zip（同步/解密暂存）与 SyncEngine 遗留的 dsh-sync-pull-* 目录
+    try {
+        const entries = await fs.readdir(opts.tmpDir, { withFileTypes: true });
+        for (const entry of entries) {
+            const target = path.join(opts.tmpDir, entry.name);
+            const isTmpish = (entry.isFile() && entry.name.endsWith('.zip')) ||
+                (entry.isDirectory() && entry.name.startsWith(SYNC_TMP_DIR_PREFIX));
+            if (!isTmpish)
+                continue;
+            if (await isExpired(target, tmpRetentionMs, nowMs)) {
+                await removeEntry(target, `tmp/${entry.name}`, result);
+            }
+        }
+    }
+    catch {
+        // tmpDir 不存在/不可读 → 跳过（尽力而为）
+        result.errors += 1;
+    }
+    // 2) exportsDir：过期的导出产物 .zip（导出时已下载/另存到本地，host 端副本按保留期回收）
+    try {
+        const entries = await fs.readdir(opts.exportsDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isFile() || !entry.name.endsWith('.zip'))
+                continue;
+            const target = path.join(opts.exportsDir, entry.name);
+            if (await isExpired(target, exportsRetentionMs, nowMs)) {
+                await removeEntry(target, `exports/${entry.name}`, result);
+            }
+        }
+    }
+    catch {
+        // exportsDir 不存在/不可读 → 跳过
+        result.errors += 1;
+    }
+    return result;
+}
+//# sourceMappingURL=cache-cleaner.js.map

package/lib/core/config-lifecycle.d.ts

@@ -0,0 +1,180 @@
+import { type ConfigState } from './config-state.ts';
+import { type ConfigSnapshotMeta, type ConfigSnapshotRestoreReport } from './config-snapshot.ts';
+import { type ConfigSnapshotKind } from './undo.ts';
+import { type TimerApi, type WatchFactory, type WatcherEvent } from './watcher.ts';
+import type { ConfigAdapter, HostContext } from './types.ts';
+import type { SectionId } from '../schema/types.ts';
+/** 启动关键配置文件（相对 homeDir）——自动快照最需要覆盖的那一批 */
+export declare const BOOT_CRITICAL_RELS: readonly string[];
+/** profile 下启动关键配置文件（相对 homeDir） */
+export declare function profileCriticalRels(profile: string): string[];
+/** 需要监听变更的目录（绝对路径；去重） */
+export declare function watchDirsFor(homeDir: string, profile: string): string[];
+/** 回声候选文件（绝对路径）：我们恢复时会写的配置面文件 */
+export declare function echoCandidatePaths(homeDir: string, profile: string): string[];
+export interface ConfigLifecycleOptions {
+    /** 配置快照根目录（建议 <dataDir>/config-snapshots） */
+    dir: string;
+    adapters: readonly ConfigAdapter[];
+    ctx: HostContext;
+    /** profile 名（决定监听目录与 profile 文件集） */
+    profile: string;
+    /** 分区应用顺序（回放用；建议传与导入管线一致的顺序） */
+    applyOrder?: readonly SectionId[];
+    /** 自动快照开关（缺省 true） */
+    autoEnabled?: boolean;
+    /** 防抖窗口（缺省 1500ms） */
+    debounceMs?: number;
+    /** 保留份数（缺省 auto 20 / pre-restore 10 / manual 不限） */
+    keepAuto?: number;
+    keepPreRestore?: number;
+    /** watch 工厂（缺省由宿主注入真 fs.watch；未注入则自动快照不启动） */
+    watchFactory?: WatchFactory;
+    /** 定时器注入（透传给 DebouncedWatcher；测试用假定时器即可完整驱动时序） */
+    timers?: TimerApi;
+    /** 采集时单分区失败回调（不阻断） */
+    onSectionError?: (section: SectionId, error: unknown) => void;
+    /** 自动快照落盘后的回调（宿主写审计史） */
+    onAutoSnapshot?: (meta: ConfigSnapshotMeta) => void;
+    /** 诊断日志（默认静默） */
+    onWarn?: (message: string, detail?: unknown) => void;
+}
+export interface LifecycleStatus {
+    canUndo: boolean;
+    canRedo: boolean;
+    total: number;
+    /** 最近一次自动快照时间（null = 从未） */
+    lastAutoAt: string | null;
+    /** 当前是否正在监听文件变更 */
+    watching: boolean;
+}
+export interface UndoOutcome {
+    ok: boolean;
+    /** 命中目标快照 id（成功时） */
+    targetId?: string;
+    /** 撤销前落下的「撤销前状态」快照 id（重做的依据） */
+    preSnapshotId?: string;
+    /** 失败原因（未命中/回放失败） */
+    reason?: string;
+    report?: ConfigSnapshotRestoreReport;
+    /** 被标记为「已跨过」的快照 id */
+    stepped?: string[];
+}
+export interface RedoOutcome {
+    ok: boolean;
+    targetId?: string;
+    reason?: string;
+    report?: ConfigSnapshotRestoreReport;
+    /** 重做后清除 stepped 标记的快照 id */
+    unstepped?: string[];
+}
+export interface SnapshotRequest {
+    kind: ConfigSnapshotKind;
+    reason: string;
+    trigger?: string;
+    note?: string;
+    tags?: string[];
+    /** 只采集这些分区（缺省全部） */
+    only?: readonly SectionId[];
+}
+/**
+ * 配置生命周期服务（宿主单例）。
+ * 所有公开方法都不抛：错误转为 `ok:false + reason`，避免拖垮宿主路由。
+ */
+export declare class ConfigLifecycle {
+    private readonly opts;
+    private readonly echo;
+    private watcher;
+    private lastAutoAt;
+    private flushRunning;
+    private disposed;
+    /**
+     * flush 进行中到达的事件批（见 onAutoFlush）。
+     * watcher 在回调前已把事件批从 pending 摘除，若直接丢弃就再也没有定时器补发，
+     * 那一次变更将永远不会被快照 —— 撤销会直接跳过它。
+     */
+    private deferred;
+    /**
+     * 最近一次回放（撤销/重做）把配置写成的目标状态。
+     * 第二层回声防线的兜底：抑制窗口只能挡住**窗口内**的事件，窗口之后才投递的事件
+     * （macOS / 网络盘 / 杀毒扫描后重写）只能靠内容判定 —— 若此刻采集到的状态仍等于
+     * 刚写回的目标状态，那批事件就是恢复自写的回声，不得产生新快照（否则它比
+     * pre-restore 更新，会把重做通道堵死）。真实变更一旦落盘即清空。
+     */
+    private lastReplayState;
+    /** 当前实际建立监听的目录（供 reconcileWatchSet 比对，避免无谓重建） */
+    private watchedDirs;
+    constructor(options: ConfigLifecycleOptions);
+    private warn;
+    get dir(): string;
+    get isWatching(): boolean;
+    /**
+     * 采集各分区导出结果 + 分区指纹：**单次遍历**，不重复 export。
+     * 单分区失败 → 记入 failed 并跳过（不抛），使调用方能判断这次状态是否可信。
+     */
+    private captureSections;
+    /** 采集当前配置状态（单分区失败跳过，不抛） */
+    capture(only?: readonly SectionId[]): Promise<ConfigState>;
+    /** 采集并落盘一个配置快照 */
+    snapshot(req: SnapshotRequest): Promise<ConfigSnapshotMeta>;
+    /**
+     * 用一个**已采集**的产物落盘快照。
+     * 为什么必须支持传入已采集结果：撤销的 pre-restore 快照必须与「据以挑选目标的
+     * 那次采集」是同一份观测 —— 否则二次采集之间用户又改了配置，pre-restore 记下的
+     * 就不是「撤销前状态」，重做会把用户没见过的内容写回去。
+     */
+    private saveSnapshot;
+    list(): Promise<ConfigSnapshotMeta[]>;
+    prune(): Promise<string[]>;
+    status(): Promise<LifecycleStatus>;
+    /**
+     * 撤销：回退到与当前状态**内容不同**的最新快照。
+     * 撤销前先落 `pre-restore` 快照记录当前状态，使重做可逆。
+     */
+    undo(): Promise<UndoOutcome>;
+    /** 重做：回到最近一次未消费的 pre-restore（其后若有新快照则拒绝）。 */
+    redo(): Promise<RedoOutcome>;
+    /**
+     * 回放指定快照（撤销/重做共用）。
+     * 全程在监听抑制窗口内，并在结束后登记回声指纹——两道防线都在这里落地。
+     */
+    replay(id: string): Promise<ConfigSnapshotRestoreReport>;
+    /**
+     * 登记「刚写回的内容指纹」：恢复动作写完文件后调用。
+     * 只登记我们确实会写的配置面文件（存在才登记），避免把无关文件误判为回声而漏拍。
+     */
+    recordEcho(): Promise<void>;
+    /**
+     * 事件批是否为「恢复自写的回声」。
+     * 判定：批内每个文件都必须已登记**且**内容仍等于登记值；任一文件内容变了、
+     * 未登记、或读不到（新增/删除）→ 真实变更。
+     */
+    isEchoBatch(events: readonly WatcherEvent[]): Promise<boolean>;
+    /** 启动自动快照监听（幂等；未注入 watchFactory 或已关闭则空操作） */
+    startAutoSnapshot(): void;
+    /**
+     * 监听集自愈：启动之后才出现的目录（skills / .agent-presets 在全新安装里通常不存在）
+     * 在**下一次快照之后**自动纳入监听。
+     *
+     * 为什么需要它：startAutoSnapshot 每次进程只被调用一次（启动闸门），若只在那里过滤
+     * 一次，那两个目录在整个进程生命周期里都不会被监听 —— 与注释里的承诺不符（「注释承诺 >
+     * 实际防线」正是本仓库踩过的坑）。放在 flush 之后调用，既不打断进行中的采集，也不会
+     * 丢掉排队中的事件批。
+     */
+    private reconcileWatchSet;
+    stopAutoSnapshot(): void;
+    /** 释放：停止监听（宿主 dispose 调用） */
+    dispose(): void;
+    /** 供宿主在路由层复用的抑制包装（例如 Profile 切换时） */
+    suppressWhileAsync<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * 防抖到期后的自动快照。
+     *
+     * 并发保护是「排队」而不是「丢弃」：watcher 在回调前已经把事件批从 pending 摘除，
+     * 若这里直接 return，那批事件就再也没有定时器补发 —— 那次变更永远不会被快照，
+     * 撤销会直接跳过它（实测：连写 v2、v3 只落了 1 份快照，且 undo 无从回到 v2）。
+     */
+    private onAutoFlush;
+    /** 处理一批事件：回声判定 → 采集 → 落盘。 */
+    private flushOnce;
+}