@logictan/dsh-config-manager 0.1.60

package/lib/core/config-snapshot.js

@@ -0,0 +1,424 @@
+/**
+ * 配置状态快照（Phase 1 P0-1 / P0-2 的持久化与回放层）。
+ *
+ * 与既有 `core/backup.ts` 的 `Snapshot` 的分工：
+ *  - `Snapshot`（backup.ts）：**导入计划驱动**，只登记「本次导入将写入的目标」的原值，
+ *    用于导入失败回滚。它不描述「整体配置在某时刻是什么样」。
+ *  - `ConfigSnapshot`（本模块）：**状态驱动**，记录整份配置在某一时刻的分区数据 + 分区指纹，
+ *    用于自动快照、撤销/重做、最后正常状态定位。恢复方式是**回放 adapter**
+ *    （validate → analyzeImport → applyItem，与导入/Profile 切换同一条管线），
+ *    因此天然覆盖 settings 命名空间、patch 行、文件类分区与插件安装。
+ *
+ * 存储布局：`<dir>/<id>/config-snapshot.json` = `{ meta, data }`。
+ * `data` 为各分区的 ExportSection.data；其中的 Uint8Array（文件类分区的字节）
+ * 经 `__u8` base64 包封做可逆 JSON 编码（JSON.stringify 会把字节变成 {0:..,1:..}）。
+ *
+ * 安全：快照 id 严格白名单校验（防穿越）；写入走 atomicWriteFile；分区数据只含
+ * `includeSecrets: false` 的导出结果，密钥值从不进入本模块。
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { atomicWriteFile } from '../utils/atomic-write.js';
+import { parseJsonSafe } from '../utils/json.js';
+import { SECTION_IDS } from '../schema/config.js';
+import { CURRENT_SCHEMA_VERSION } from '../schema/versions.js';
+import { msgOf, zhMsg } from './messages.js';
+import { isValidSnapshotId } from './restore.js';
+import { statesEqual } from './config-state.js';
+/** 快照文件名（每个快照一个目录） */
+export const CONFIG_SNAPSHOT_FILE = 'config-snapshot.json';
+/** 可逆 JSON 编码：Uint8Array → { __u8: base64 } */
+const U8_KEY = '__u8';
+function encodeForJson(value) {
+    if (value instanceof Uint8Array)
+        return { [U8_KEY]: Buffer.from(value).toString('base64') };
+    if (Array.isArray(value))
+        return value.map(encodeForJson);
+    if (value !== null && typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value))
+            out[k] = encodeForJson(v);
+        return out;
+    }
+    return value;
+}
+function decodeFromJson(value) {
+    if (Array.isArray(value))
+        return value.map(decodeFromJson);
+    if (value !== null && typeof value === 'object') {
+        const rec = value;
+        const keys = Object.keys(rec);
+        if (keys.length === 1 && keys[0] === U8_KEY && typeof rec[U8_KEY] === 'string') {
+            return new Uint8Array(Buffer.from(rec[U8_KEY], 'base64'));
+        }
+        const out = {};
+        for (const [k, v] of Object.entries(rec))
+            out[k] = decodeFromJson(v);
+        return out;
+    }
+    return value;
+}
+/** 供 undo.ts 使用的最小候选视图 */
+export function toUndoCandidate(meta) {
+    return {
+        id: meta.id,
+        createdAt: meta.createdAt,
+        kind: meta.kind,
+        state: meta.state,
+        consumed: meta.consumed,
+    };
+}
+/* ------------------------------------------------------------ 读写 */
+function snapshotDir(dir, id) {
+    if (!isValidSnapshotId(id))
+        throw new Error(`非法配置快照 id: ${JSON.stringify(id)}`);
+    const target = path.join(dir, id);
+    if (!target.startsWith(path.resolve(dir) + path.sep))
+        throw new Error(`配置快照路径越界: ${id}`);
+    return target;
+}
+/** 生成快照 id：时间戳 + 随机短串（可读 + 唯一；与既有 uuid 风格区分开） */
+export function makeConfigSnapshotId(now = () => new Date()) {
+    const d = now();
+    const p = (n, w = 2) => String(n).padStart(w, '0');
+    const stamp = `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`;
+    const rand = Math.random().toString(36).slice(2, 6).padEnd(4, '0');
+    return `${stamp}-${rand}`;
+}
+/**
+ * 写入一个配置快照。返回落盘后的元数据。
+ * id 冲突时自动追加后缀重试（同一秒内多次快照）。
+ */
+export async function saveConfigSnapshot(opts) {
+    const { dir, kind, reason, sections, state } = opts;
+    const now = opts.now ?? (() => new Date());
+    const idFactory = opts.idFactory ?? (() => makeConfigSnapshotId(now));
+    const maxBytes = opts.maxBytes ?? 64 * 1024 * 1024;
+    await fs.mkdir(dir, { recursive: true });
+    let id = idFactory();
+    for (let attempt = 0; attempt < 50; attempt++) {
+        try {
+            await fs.access(path.join(dir, id));
+            id = `${idFactory()}-${Math.random().toString(36).slice(2, 5)}`;
+        }
+        catch {
+            break; // 不存在 → 可用
+        }
+    }
+    const data = {};
+    for (const [sectionId, exported] of sections) {
+        data[sectionId] = encodeForJson(exported.data);
+    }
+    const sectionsList = [...sections.keys()].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    const payload = { meta: null, data };
+    const metaBase = {
+        id,
+        createdAt: now().toISOString(),
+        kind,
+        reason,
+        ...(opts.trigger !== undefined ? { trigger: opts.trigger } : {}),
+        sections: sectionsList,
+        state,
+        ...(opts.note !== undefined ? { note: opts.note } : {}),
+        ...(opts.tags !== undefined ? { tags: opts.tags } : {}),
+    };
+    payload.meta = metaBase;
+    const serialized = JSON.stringify(payload, null, 2);
+    const bytes = Buffer.byteLength(serialized);
+    if (bytes > maxBytes) {
+        throw new Error(`配置快照超出上限（${bytes} > ${maxBytes} 字节）；请缩小分区范围后重试`);
+    }
+    const meta = { ...metaBase, totalBytes: bytes };
+    payload.meta = meta;
+    const finalText = JSON.stringify(payload, null, 2);
+    const target = snapshotDir(dir, id);
+    await fs.mkdir(target, { recursive: true });
+    await atomicWriteFile(path.join(target, CONFIG_SNAPSHOT_FILE), finalText);
+    return meta;
+}
+/**
+ * meta.state 形状校验。
+ * 语义：
+ *  - 缺失 / undefined → **放行**（旧格式快照，撤销侧会按「无法比对」剔除，
+ *    但它仍应出现在列表里可见/可恢复）；
+ *  - 存在但不是 `{ sections: [...] }` → 判为损坏并整条丢弃：继续信任它会让
+ *    statesEqual/planUndo 拿到形状不对的对象（历史上会直接抛 TypeError，
+ *    一条坏文件就能让整个灾备面板 500）。
+ */
+function isValidStateField(value) {
+    if (value === undefined)
+        return true;
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    return Array.isArray(value.sections);
+}
+/** 读单个快照的元数据；缺失/损坏/非法 id → null（绝不抛）。 */
+export async function readConfigSnapshotMeta(dir, id) {
+    if (!isValidSnapshotId(id))
+        return null;
+    try {
+        const raw = await fs.readFile(path.join(dir, id, CONFIG_SNAPSHOT_FILE), 'utf8');
+        const parsed = parseJsonSafe(raw);
+        const meta = parsed?.meta;
+        if (meta === null || meta === undefined || typeof meta !== 'object')
+            return null;
+        if (meta.id !== id || typeof meta.createdAt !== 'string' || typeof meta.kind !== 'string')
+            return null;
+        if (!isValidStateField(meta.state))
+            return null;
+        return meta;
+    }
+    catch {
+        return null;
+    }
+}
+/** 列出全部快照元数据（按 createdAt 倒序；损坏条目跳过，不阻断其余）。 */
+export async function listConfigSnapshots(dir) {
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const metas = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const meta = await readConfigSnapshotMeta(dir, entry.name);
+        if (meta !== null)
+            metas.push(meta);
+    }
+    metas.sort((a, b) => {
+        if (a.createdAt !== b.createdAt)
+            return a.createdAt < b.createdAt ? 1 : -1;
+        return a.id < b.id ? 1 : a.id > b.id ? -1 : 0;
+    });
+    return metas;
+}
+/** 读完整快照（含分区数据）。缺失/损坏抛出。 */
+export async function loadConfigSnapshot(dir, id) {
+    const target = snapshotDir(dir, id);
+    const raw = await fs.readFile(path.join(target, CONFIG_SNAPSHOT_FILE), 'utf8');
+    const parsed = parseJsonSafe(raw);
+    const meta = parsed?.meta;
+    if (meta === null || meta === undefined || typeof meta !== 'object' || meta.id !== id) {
+        throw new Error(`配置快照 ${id} 的 ${CONFIG_SNAPSHOT_FILE} 不是合法对象`);
+    }
+    const data = {};
+    for (const [k, v] of Object.entries(parsed?.data ?? {})) {
+        data[k] = decodeFromJson(v);
+    }
+    return { ...meta, data };
+}
+/** 原地更新元数据字段；快照不存在返回 null。 */
+export async function updateConfigSnapshotMeta(dir, id, patch) {
+    if (!isValidSnapshotId(id))
+        return null;
+    const target = path.join(dir, id, CONFIG_SNAPSHOT_FILE);
+    let raw;
+    try {
+        raw = await fs.readFile(target, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    const parsed = parseJsonSafe(raw);
+    if (parsed?.meta === null || parsed?.meta === undefined)
+        return null;
+    const meta = { ...parsed.meta };
+    for (const [k, v] of Object.entries(patch)) {
+        if (v === undefined)
+            continue;
+        meta[k] = v;
+    }
+    await atomicWriteFile(target, JSON.stringify({ meta, data: parsed.data ?? {} }, null, 2));
+    return meta;
+}
+/** 删除单个快照（幂等：不存在视为成功）。 */
+export async function deleteConfigSnapshot(dir, id) {
+    if (!isValidSnapshotId(id))
+        throw new Error(`非法配置快照 id: ${JSON.stringify(id)}`);
+    const target = snapshotDir(dir, id);
+    try {
+        await fs.stat(target);
+    }
+    catch {
+        return false;
+    }
+    await fs.rm(target, { recursive: true, force: true });
+    return true;
+}
+/**
+ * 保留清理：按 kind 分桶，各自保留最新 N 份，删除更旧的。
+ * pinned 快照**一律豁免**（用户显式保留的回滚点不得被自动淘汰）。
+ * 返回被删除的快照 id 列表。
+ */
+export async function pruneConfigSnapshots(dir, opts = {}) {
+    const keepAuto = opts.keepAuto ?? 20;
+    const keepPre = opts.keepPreRestore ?? 10;
+    const keepManual = opts.keepManual ?? Number.POSITIVE_INFINITY;
+    const metas = (await listConfigSnapshots(dir)).filter((m) => m.pinned !== true);
+    const bucket = (kind) => {
+        if (kind === 'pre-restore')
+            return keepPre;
+        if (kind === 'manual')
+            return keepManual;
+        return keepAuto;
+    };
+    const grouped = new Map();
+    for (const meta of metas) {
+        const limit = bucket(meta.kind);
+        const list = grouped.get(limit) ?? [];
+        list.push(meta);
+        grouped.set(limit, list);
+    }
+    // metas 已按 createdAt 倒序 → 每桶内前 limit 个保留，其余删除
+    const removed = [];
+    for (const [limit, list] of grouped) {
+        if (!Number.isFinite(limit))
+            continue;
+        for (const meta of list.slice(Math.max(0, limit))) {
+            await fs.rm(path.join(dir, meta.id), { recursive: true, force: true });
+            removed.push(meta.id);
+        }
+    }
+    return removed;
+}
+/* ------------------------------------------------------------ 回放恢复 */
+/** 构建回放用 manifest（与 profiles/profile-manager.ts 的 buildProfileManifest 同构） */
+function buildReplayManifest(ctx) {
+    const sections = {};
+    for (const id of SECTION_IDS)
+        sections[id] = false;
+    return {
+        schemaVersion: CURRENT_SCHEMA_VERSION,
+        exporter: { name: 'DSH Config Manager', version: '0.1.0' },
+        source: {
+            dshVersion: ctx.dshVersion,
+            platform: ctx.platform,
+            arch: ctx.arch,
+        },
+        exportedAt: new Date().toISOString(),
+        sections: sections,
+        security: { containsSecrets: false, encrypted: false, encryption: null },
+    };
+}
+/** 非破坏性计划项：不调用 applyItem（与导入管线的「可执行 kinds」口径一致） */
+const NON_EXECUTABLE_KINDS = new Set(['Skip', 'Warning', 'MissingSecret', 'MissingDependency', 'PathMapping']);
+/**
+ * 回放一个配置快照：对每个分区 validate → analyzeImport → applyItem。
+ * 与导入/Profile 切换共用 adapter 管线，因此行为一致、无第二套写入逻辑。
+ * 单项失败不拖垮其余（如实计入 failed），与 rollback.ts 的尽力语义一致。
+ */
+export async function restoreConfigSnapshot(opts) {
+    const { dir, id, adapters, ctx } = opts;
+    const msg = opts.msg ?? ctx.msg ?? zhMsg;
+    const snapshot = await loadConfigSnapshot(dir, id);
+    const only = opts.only !== undefined ? new Set(opts.only) : null;
+    const sections = new Map();
+    for (const [k, v] of Object.entries(snapshot.data)) {
+        if (only !== null && !only.has(k))
+            continue;
+        sections.set(k, v);
+    }
+    const importCtx = {
+        manifest: buildReplayManifest(ctx),
+        targetPlatform: ctx.platform,
+        target: ctx,
+        sections,
+        pathMappings: [],
+        resolutions: {},
+        secretInputs: {},
+        log: ctx.log,
+        msg,
+    };
+    const ordered = opts.applyOrder !== undefined
+        ? [...adapters].sort((a, b) => {
+            const ia = opts.applyOrder.indexOf(a.id);
+            const ib = opts.applyOrder.indexOf(b.id);
+            return (ia < 0 ? Number.MAX_SAFE_INTEGER : ia) - (ib < 0 ? Number.MAX_SAFE_INTEGER : ib);
+        })
+        : [...adapters];
+    const report = {
+        ok: true,
+        snapshotId: id,
+        applied: [],
+        skipped: [],
+        failed: [],
+        invalidSections: [],
+        needsRestart: false,
+    };
+    for (const adapter of ordered) {
+        const data = sections.get(adapter.id);
+        if (data === undefined)
+            continue;
+        let items;
+        try {
+            const validation = await adapter.validate(data, msg);
+            if (!validation.valid) {
+                const reason = validation.issues
+                    .filter((i) => i.severity === 'error')
+                    .map((i) => `${i.path}: ${i.message}`)
+                    .join('; ');
+                report.invalidSections.push({ section: adapter.id, reason: reason === '' ? 'validation failed' : reason });
+                continue;
+            }
+            items = await adapter.analyzeImport(data, importCtx);
+        }
+        catch (err) {
+            report.invalidSections.push({
+                section: adapter.id,
+                reason: err instanceof Error ? err.message : String(err),
+            });
+            continue;
+        }
+        let index = 0;
+        for (const item of items) {
+            index += 1;
+            opts.onItem?.({ index, total: items.length, detail: `${adapter.id}:${item.id}` });
+            if (item.kind === 'Error') {
+                report.failed.push({ item: `${adapter.id}:${item.id}`, reason: item.description });
+                report.ok = false;
+                continue;
+            }
+            if (NON_EXECUTABLE_KINDS.has(item.kind)) {
+                report.skipped.push(`${adapter.id}:${item.id}`);
+                continue;
+            }
+            try {
+                const result = await adapter.applyItem(item, importCtx);
+                if (result.ok) {
+                    report.applied.push(`${adapter.id}:${item.id}`);
+                    if (result.needsRestart === true)
+                        report.needsRestart = true;
+                }
+                else if (result.warning === true) {
+                    report.skipped.push(`${adapter.id}:${item.id}`);
+                }
+                else {
+                    report.failed.push({
+                        item: `${adapter.id}:${item.id}`,
+                        reason: result.message ?? 'applyItem 返回失败',
+                    });
+                    report.ok = false;
+                }
+            }
+            catch (err) {
+                report.failed.push({
+                    item: `${adapter.id}:${item.id}`,
+                    reason: err instanceof Error ? err.message : String(err),
+                });
+                report.ok = false;
+            }
+        }
+    }
+    return report;
+}
+/** 便捷：两个快照的分区指纹是否等价（供 UI「与当前一致」提示） */
+export function snapshotsEquivalent(a, b) {
+    return statesEqual(a.state, b.state);
+}
+/** 供调用方取翻译器（保持与 core 其他模块一致的导出面） */
+export const configSnapshotMsgOf = msgOf;
+//# sourceMappingURL=config-snapshot.js.map

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

@@ -0,0 +1,70 @@
+import type { SectionId } from '../schema/types.ts';
+import type { ConfigAdapter, ExportSection, HostContext } from './types.ts';
+/** 单分区状态：内容指纹 + 计数（counts 仅展示，不参与相等性判定） */
+export interface SectionState {
+    section: SectionId;
+    /** 分区内容的稳定 sha256（hex） */
+    hash: string;
+    /** adapter 自报计数（展示用；不参与相等判定） */
+    counts: Record<string, number>;
+    /** 文件类分区的文件条数（非文件分区为 0） */
+    fileCount: number;
+}
+/** 一次配置状态采集结果 */
+export interface ConfigState {
+    /** ISO 时间戳 */
+    capturedAt: string;
+    /** 按 section 名升序，保证 stateSections/diff 的确定性 */
+    sections: SectionState[];
+}
+/**
+ * 稳定序列化：对象键**排序**后输出，保证同一逻辑内容得到同一字符串。
+ * 处理 undefined / 函数 → 省略（与 JSON 语义一致）；Date → ISO；Uint8Array → base64 标记。
+ * 不追求通用性：只服务本模块的哈希输入（adapter 导出数据 = JSON 安全结构）。
+ */
+export declare function stableStringify(value: unknown): string;
+/**
+ * 分区内容指纹。
+ * data 走 stableStringify；files（文件类分区）按「相对路径 + 内容 sha256」参与，
+ * 使文件重命名/内容变化都能被识别，而不必把字节写进哈希输入。
+ */
+export declare function hashExportSection(section: Pick<ExportSection, 'data' | 'files'>): string;
+export interface CaptureConfigStateOptions {
+    /** 仅采集这些分区（缺省 = 全部传入的 adapter） */
+    only?: readonly SectionId[];
+    /** 单分区采集失败回调（该分区被跳过，不进入 state） */
+    onSectionError?: (section: SectionId, error: unknown) => void;
+}
+/**
+ * 由**已导出的**分区结果构建状态（按 section 升序）。
+ *
+ * 单一事实源：`captureConfigState` 与「先导出再落快照」的快照路径都必须走这里，
+ * 否则两条路径的分区口径（hash / counts / fileCount）会悄悄漂移。
+ */
+export declare function stateFromExports(sections: ReadonlyMap<SectionId, ExportSection>, capturedAt?: string): ConfigState;
+/**
+ * 采集当前配置状态。分区按 id 升序输出以保证可比性。
+ * 单分区失败 → 跳过（记入 onSectionError），不抛出。
+ */
+export declare function captureConfigState(adapters: readonly ConfigAdapter[], ctx: HostContext, opts?: CaptureConfigStateOptions): Promise<ConfigState>;
+/** section → SectionState（便于比较与展示）；state 为 null/损坏时返回空表（不抛）。 */
+export declare function stateSections(state: ConfigState | null): Map<SectionId, SectionState>;
+/**
+ * 两个状态的内容是否完全一致（分区集合 + 每分区 hash）。
+ *
+ * 全函数：null / undefined / 缺 sections 的损坏状态一律**不抛**——
+ * 任一侧不可解析时退化为引用相等（null vs null 为 true，其余为 false）。
+ */
+export declare function statesEqual(a: ConfigState | null, b: ConfigState | null): boolean;
+export interface ConfigStateDiff {
+    /** 两侧都有但 hash 不同 */
+    changed: SectionId[];
+    /** 仅 after 有 */
+    added: SectionId[];
+    /** 仅 before 有 */
+    removed: SectionId[];
+    /** 无任何差异 */
+    identical: boolean;
+}
+/** 分区级差异（before → after）。顺序确定（按 section 升序）。 */
+export declare function diffStates(before: ConfigState | null, after: ConfigState | null): ConfigStateDiff;

package/lib/core/config-state.js

@@ -0,0 +1,177 @@
+/**
+ * 配置状态向量（Phase 1 地基：P0-1 自动快照 / P0-2 撤销重做 共用）。
+ *
+ * 问题：既有 `Snapshot` 是**导入计划驱动**的（只登记本次导入将写入的目标），
+ * 因此它无法回答「相对于某个时刻，配置整体有没有变」「变的是哪个分区」。
+ * 撤销/重做与自动快照需要的正是后者。
+ *
+ * 本模块把「当前 DSH 配置」压成一个**可分区的稳定指纹集合**（ConfigState）：
+ *  - 每个分区经 `adapter.export(ctx, { includeSecrets: false })` 读取；
+ *  - 对分区内容做**稳定序列化**后取 sha256（对象键排序，跨进程/跨机器一致）；
+ *  - 文件类分区的文件字节按 sha256 计入，不把二进制塞进哈希输入。
+ *
+ * 边界：纯计算 + 只读 adapter，零写入；不持久化（持久化见 config-snapshot.ts）。
+ * 采集失败的分区**跳过并回调**，绝不因单分区异常而使整次采集失败——否则一个坏
+ * adapter 会让自动快照静默停摆。
+ */
+import { sha256Hex } from '../utils/hashing.js';
+/**
+ * 稳定序列化：对象键**排序**后输出，保证同一逻辑内容得到同一字符串。
+ * 处理 undefined / 函数 → 省略（与 JSON 语义一致）；Date → ISO；Uint8Array → base64 标记。
+ * 不追求通用性：只服务本模块的哈希输入（adapter 导出数据 = JSON 安全结构）。
+ */
+export function stableStringify(value) {
+    const seen = new WeakSet();
+    const walk = (v) => {
+        if (v === null)
+            return 'null';
+        if (v === undefined)
+            return 'undefined';
+        const t = typeof v;
+        if (t === 'number')
+            return Number.isFinite(v) ? String(v) : 'null';
+        if (t === 'boolean')
+            return v === true ? 'true' : 'false';
+        if (t === 'bigint')
+            return `${String(v)}n`;
+        if (t === 'string')
+            return JSON.stringify(v);
+        if (t === 'function' || t === 'symbol')
+            return 'undefined';
+        // 二进制按内容 sha256 计入，而非 base64 展开：文件类分区的字节就在 data.files[].data 里，
+        // 展开成 base64 会让哈希输入膨胀 33% 且对大目录明显变慢；变更检测只需要内容指纹。
+        if (v instanceof Uint8Array)
+            return `"sha256:${sha256Hex(v)}"`;
+        if (v instanceof Date)
+            return JSON.stringify(v.toISOString());
+        const obj = v;
+        if (seen.has(obj))
+            return '"<cycle>"';
+        seen.add(obj);
+        if (Array.isArray(v))
+            return `[${v.map(walk).join(',')}]`;
+        const entries = Object.entries(obj)
+            .filter(([, val]) => val !== undefined && typeof val !== 'function')
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        return `{${entries.map(([k, val]) => `${JSON.stringify(k)}:${walk(val)}`).join(',')}}`;
+    };
+    return walk(value);
+}
+/**
+ * 分区内容指纹。
+ * data 走 stableStringify；files（文件类分区）按「相对路径 + 内容 sha256」参与，
+ * 使文件重命名/内容变化都能被识别，而不必把字节写进哈希输入。
+ */
+export function hashExportSection(section) {
+    const files = (section.files ?? [])
+        .map((f) => ({ path: f.relativePath, hash: sha256Hex(f.data) }))
+        .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    return sha256Hex(stableStringify({ data: section.data, files }));
+}
+/**
+ * 由**已导出的**分区结果构建状态（按 section 升序）。
+ *
+ * 单一事实源：`captureConfigState` 与「先导出再落快照」的快照路径都必须走这里，
+ * 否则两条路径的分区口径（hash / counts / fileCount）会悄悄漂移。
+ */
+export function stateFromExports(sections, capturedAt = new Date().toISOString()) {
+    const list = [];
+    for (const [id, exported] of sections) {
+        list.push({
+            section: id,
+            hash: hashExportSection(exported),
+            counts: exported.counts ?? {},
+            fileCount: exported.files?.length ?? 0,
+        });
+    }
+    list.sort((a, b) => (a.section < b.section ? -1 : a.section > b.section ? 1 : 0));
+    return { capturedAt, sections: list };
+}
+/**
+ * 采集当前配置状态。分区按 id 升序输出以保证可比性。
+ * 单分区失败 → 跳过（记入 onSectionError），不抛出。
+ */
+export async function captureConfigState(adapters, ctx, opts = {}) {
+    const only = opts.only !== undefined ? new Set(opts.only) : null;
+    const collected = new Map();
+    for (const adapter of adapters) {
+        if (only !== null && !only.has(adapter.id))
+            continue;
+        try {
+            collected.set(adapter.id, await adapter.export(ctx, { includeSecrets: false, only: [adapter.id] }));
+        }
+        catch (error) {
+            opts.onSectionError?.(adapter.id, error);
+        }
+    }
+    return stateFromExports(collected);
+}
+/** section → SectionState（便于比较与展示）；state 为 null/损坏时返回空表（不抛）。 */
+export function stateSections(state) {
+    const map = new Map();
+    const sections = sectionListOf(state);
+    if (sections === null)
+        return map;
+    for (const s of sections)
+        map.set(s.section, s);
+    return map;
+}
+/**
+ * 取出 state.sections；非数组（含 state 为 null/undefined、或旧格式缺字段）→ null。
+ * 用于让 statesEqual 成为**全函数**：绝不因一条损坏的持久化快照而抛 TypeError
+ * （undo/redo/status 都直接消费磁盘上的 meta.state）。
+ */
+function sectionListOf(state) {
+    if (state === null || state === undefined)
+        return null;
+    const sections = state.sections;
+    return Array.isArray(sections) ? sections : null;
+}
+/**
+ * 两个状态的内容是否完全一致（分区集合 + 每分区 hash）。
+ *
+ * 全函数：null / undefined / 缺 sections 的损坏状态一律**不抛**——
+ * 任一侧不可解析时退化为引用相等（null vs null 为 true，其余为 false）。
+ */
+export function statesEqual(a, b) {
+    const left = sectionListOf(a);
+    const right = sectionListOf(b);
+    if (left === null || right === null)
+        return a === b;
+    if (left.length !== right.length)
+        return false;
+    const bySection = new Map();
+    for (const s of left)
+        bySection.set(s.section, s);
+    for (const s of right) {
+        const other = bySection.get(s.section);
+        if (other === undefined || other.hash !== s.hash)
+            return false;
+    }
+    return true;
+}
+/** 分区级差异（before → after）。顺序确定（按 section 升序）。 */
+export function diffStates(before, after) {
+    const b = stateSections(before);
+    const a = stateSections(after);
+    const changed = [];
+    const added = [];
+    const removed = [];
+    for (const [id, as] of a) {
+        const bs = b.get(id);
+        if (bs === undefined)
+            added.push(id);
+        else if (bs.hash !== as.hash)
+            changed.push(id);
+    }
+    for (const id of b.keys()) {
+        if (!a.has(id))
+            removed.push(id);
+    }
+    const sortIds = (ids) => ids.sort((x, y) => (x < y ? -1 : x > y ? 1 : 0));
+    sortIds(changed);
+    sortIds(added);
+    sortIds(removed);
+    return { changed, added, removed, identical: changed.length === 0 && added.length === 0 && removed.length === 0 };
+}
+//# sourceMappingURL=config-state.js.map