@logictan/dsh-config-manager 0.1.60

package/lib/sync/sync-history.js

@@ -0,0 +1,78 @@
+/**
+ * m-autosync：自动同步执行记录持久化（sync-history.json）。
+ *
+ * 与 sync-config/autosync-config 并列独立文件。schemaVersion:1，
+ * 结构 { schemaVersion, autosyncEntries: AutosyncHistoryEntry[], updatedAt }。
+ *
+ * - append 追加（升序）并裁剪保留最近 AUTOSYNC_HISTORY_KEEP 条；
+ * - 原子写（临时文件 + rename）；
+ * - 损坏 JSON 严格拒绝（不静默降级到空列表）。
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { parseJsonSafe, stringifyJsonSafe } from '../utils/json.js';
+import { atomicWriteFile } from '../utils/atomic-write.js';
+export const SYNC_HISTORY_FILE = 'sync-history.json';
+export const SYNC_HISTORY_SCHEMA_VERSION = 1;
+/** 自动同步历史保留上限 */
+export const AUTOSYNC_HISTORY_KEEP = 200;
+/** 读取同步历史；文件不存在 → 空列表（schemaVersion=1）。损坏 JSON 抛错。 */
+export async function readSyncHistory(dir) {
+    const file = path.join(dir, SYNC_HISTORY_FILE);
+    let raw;
+    try {
+        raw = await fs.readFile(file, 'utf8');
+    }
+    catch {
+        return { schemaVersion: SYNC_HISTORY_SCHEMA_VERSION, autosyncEntries: [], updatedAt: '' };
+    }
+    let parsed;
+    try {
+        parsed = parseJsonSafe(raw);
+    }
+    catch {
+        throw new Error(`${SYNC_HISTORY_FILE} 损坏：JSON 解析失败`);
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`${SYNC_HISTORY_FILE} 损坏：必须是对象`);
+    }
+    const obj = parsed;
+    if (obj['schemaVersion'] !== SYNC_HISTORY_SCHEMA_VERSION) {
+        throw new Error(`${SYNC_HISTORY_FILE} 损坏：schemaVersion 必须是 ${SYNC_HISTORY_SCHEMA_VERSION}`);
+    }
+    if (!Array.isArray(obj['autosyncEntries'])) {
+        throw new Error(`${SYNC_HISTORY_FILE} 损坏：autosyncEntries 必须是数组`);
+    }
+    const entries = [];
+    for (const it of obj['autosyncEntries']) {
+        if (it === null || typeof it !== 'object' || Array.isArray(it)) {
+            throw new Error(`${SYNC_HISTORY_FILE} 损坏：每个 entry 必须是对象`);
+        }
+        const e = it;
+        if (typeof e['direction'] !== 'string' || typeof e['status'] !== 'string' || typeof e['createdAt'] !== 'string') {
+            throw new Error(`${SYNC_HISTORY_FILE} 损坏：entry 必须含字符串 direction/status/createdAt`);
+        }
+        entries.push(it);
+    }
+    return {
+        schemaVersion: SYNC_HISTORY_SCHEMA_VERSION,
+        autosyncEntries: entries,
+        updatedAt: typeof obj['updatedAt'] === 'string' ? obj['updatedAt'] : '',
+    };
+}
+/** 追加一条自动同步执行记录（升序），裁剪到 AUTOSYNC_HISTORY_KEEP 条，原子写。 */
+export async function appendAutosyncEntry(dir, entry, now = () => new Date()) {
+    const current = await readSyncHistory(dir);
+    current.autosyncEntries.push(entry);
+    // 裁剪：保留最近 AUTOSYNC_HISTORY_KEEP 条（升序 → 去掉最前的超限条）
+    if (current.autosyncEntries.length > AUTOSYNC_HISTORY_KEEP) {
+        current.autosyncEntries = current.autosyncEntries.slice(current.autosyncEntries.length - AUTOSYNC_HISTORY_KEEP);
+    }
+    current.updatedAt = now().toISOString();
+    await fs.mkdir(dir, { recursive: true });
+    const target = path.join(dir, SYNC_HISTORY_FILE);
+    const data = stringifyJsonSafe(current, { space: 2 });
+    await atomicWriteFile(target, data, { mode: 0o600 });
+}
+//# sourceMappingURL=sync-history.js.map

package/lib/sync/sync-selection.d.ts

@@ -0,0 +1,29 @@
+import type { SectionId } from '../schema/types.ts';
+import type { SyncTransportType } from './sync-config.ts';
+export declare const SYNC_SELECTION_FILE = "sync-selection.json";
+export declare const SYNC_SELECTION_SCHEMA_VERSION = 2;
+/** 可读的版本：1 = 上游顶层单通道（或早期 channels 信封）；2 = 本信封（含上游 0.1.60）。 */
+export declare const SYNC_SELECTION_SUPPORTED_VERSIONS: readonly number[];
+/** 远程同步分区选择模式：default = 全部推荐分区；advanced = 自定义勾选。 */
+export type SyncSelectionMode = 'default' | 'advanced';
+/** 远程同步分区选择（持久化面；单通道）。 */
+export interface SyncSelection {
+    schemaVersion: number;
+    mode: SyncSelectionMode;
+    /** 高级模式勾选分区；default 模式可为空数组 */
+    sections: SectionId[];
+}
+/** 缺省配置（首次无文件 / 损坏 / 不支持 schema 时回退） */
+export declare function defaultSyncSelection(): SyncSelection;
+/**
+ * 生效的同步分区范围：
+ * - mode='advanced' 且 sections 非空 → sections（自定义同步）；
+ * - 其余（default / advanced 但未勾选）→ undefined（= 全部推荐分区）。
+ */
+export declare function effectiveSections(sel: SyncSelection): SectionId[] | undefined;
+/** 读取全部通道的分区选择配置；文件不存在 / 损坏 / 不支持 schema → 缺省值（不抛错）。 */
+export declare function readAllSyncSelections(dir: string): Promise<Record<SyncTransportType, SyncSelection>>;
+/** 读取指定通道的分区选择配置；文件不存在 / 损坏 / 不支持 schema → 缺省值（不抛错）。 */
+export declare function readSyncSelection(dir: string, channel: SyncTransportType): Promise<SyncSelection>;
+/** 写入指定通道的分区选择配置（原子写：临时文件 + rename；保留另一通道；自动创建目录）。 */
+export declare function writeSyncSelection(dir: string, channel: SyncTransportType, sel: SyncSelection): Promise<void>;

package/lib/sync/sync-selection.js

@@ -0,0 +1,127 @@
+/**
+ * m-sync-selection：远程同步分区选择持久化（sync-selection.json）。
+ *
+ * 与 sync-config.json / sync-autosync.json 并列独立文件：语义清楚、schema 演进独立。
+ * schemaVersion:2 —— 按同步通道拆分（git / webdav 各自独立的分区勾选）：
+ * ```
+ * { "schemaVersion": 2,
+ *   "channels": {
+ *     "git":    { mode: 'default'|'advanced', sections: SectionId[] },
+ *     "webdav": { ... } } }
+ * ```
+ * - mode='default'（快速同步）：推送/自动同步使用全部推荐分区（sections 可空）；
+ * - mode='advanced'（自定义同步）：推送/自动同步只处理勾选的 sections（空 sections 回退全量，
+ *   避免自动同步卡死）。
+ *
+ * 快照恒为明文：同步通道是用户自有的私有通道，勾选即同步，不加密、不脱敏。
+ *
+ * **版本号与上游同号是刻意的**：上游 0.1.60 的 `schemaVersion:2` 就是本信封
+ * （多出 `encrypt` / `includeSecrets` 两个已废弃字段），上游的 v1 则是**顶层单通道**
+ * 形状（`{mode, sections}`，无 channels）。本文件必须能读回上游 v2，否则升级即静默
+ * 丢失用户勾选；写出的 v2 上游也仍能读（它接受 ver===2），故回滚到上游不会重置。
+ * 若把本信封编号写成 1，就会与上游 v1 的顶层形状撞号：既读不回上游 v2，写出的文件
+ * 上游按顶层解析又只得到缺省。
+ *
+ * 原子写（临时文件 + rename），损坏/不支持 schema 回退缺省（mode='default', sections=[]）。
+ * 持久化原因：自动同步调度器运行于 Host 进程（浏览器关闭也在跑），必须从磁盘读
+ * 用户选择，而不是依赖浏览器 localStorage。
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { parseJsonSafe, stringifyJsonSafe } from '../utils/json.js';
+import { atomicWriteFile } from '../utils/atomic-write.js';
+export const SYNC_SELECTION_FILE = 'sync-selection.json';
+export const SYNC_SELECTION_SCHEMA_VERSION = 2;
+/** 可读的版本：1 = 上游顶层单通道（或早期 channels 信封）；2 = 本信封（含上游 0.1.60）。 */
+export const SYNC_SELECTION_SUPPORTED_VERSIONS = [1, 2];
+/** 缺省配置（首次无文件 / 损坏 / 不支持 schema 时回退） */
+export function defaultSyncSelection() {
+    return { schemaVersion: SYNC_SELECTION_SCHEMA_VERSION, mode: 'default', sections: [] };
+}
+/**
+ * 生效的同步分区范围：
+ * - mode='advanced' 且 sections 非空 → sections（自定义同步）；
+ * - 其余（default / advanced 但未勾选）→ undefined（= 全部推荐分区）。
+ */
+export function effectiveSections(sel) {
+    if (sel.mode === 'advanced' && sel.sections.length > 0)
+        return [...sel.sections];
+    return undefined;
+}
+/** 从单通道对象解析（非法字段回退缺省）。 */
+function parseChannelSelection(obj) {
+    const sel = defaultSyncSelection();
+    if (obj['mode'] === 'advanced' || obj['mode'] === 'default')
+        sel.mode = obj['mode'];
+    if (Array.isArray(obj['sections'])) {
+        sel.sections = obj['sections'].filter((s) => typeof s === 'string' && s !== '');
+    }
+    return sel;
+}
+/** 读取全部通道的分区选择配置；文件不存在 / 损坏 / 不支持 schema → 缺省值（不抛错）。 */
+export async function readAllSyncSelections(dir) {
+    const fallback = () => ({
+        git: defaultSyncSelection(),
+        webdav: defaultSyncSelection(),
+    });
+    const file = path.join(dir, SYNC_SELECTION_FILE);
+    let raw;
+    try {
+        raw = await fs.readFile(file, 'utf8');
+    }
+    catch {
+        return fallback();
+    }
+    let parsed;
+    try {
+        parsed = parseJsonSafe(raw);
+    }
+    catch {
+        return fallback();
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+        return fallback();
+    const obj = parsed;
+    // 缺 schemaVersion 视为 v1（与上游一致）；不支持的版本回退缺省。
+    const ver = typeof obj['schemaVersion'] === 'number' ? obj['schemaVersion'] : 1;
+    if (!SYNC_SELECTION_SUPPORTED_VERSIONS.includes(ver))
+        return fallback();
+    const channels = obj['channels'];
+    if (channels === null || typeof channels !== 'object' || Array.isArray(channels)) {
+        // v1 顶层单通道形状：整个对象就是一个通道配置（归 git），与上游迁移语义一致。
+        // v2 缺 channels 信封属于损坏 → 回退缺省。
+        if (ver === 1)
+            return { git: parseChannelSelection(obj), webdav: defaultSyncSelection() };
+        return fallback();
+    }
+    const ch = channels;
+    const pick = (ns) => ns !== null && typeof ns === 'object' && !Array.isArray(ns)
+        ? parseChannelSelection(ns)
+        : defaultSyncSelection();
+    return { git: pick(ch['git']), webdav: pick(ch['webdav']) };
+}
+/** 读取指定通道的分区选择配置；文件不存在 / 损坏 / 不支持 schema → 缺省值（不抛错）。 */
+export async function readSyncSelection(dir, channel) {
+    const all = await readAllSyncSelections(dir);
+    return all[channel];
+}
+/** 写入指定通道的分区选择配置（原子写：临时文件 + rename；保留另一通道；自动创建目录）。 */
+export async function writeSyncSelection(dir, channel, sel) {
+    await fs.mkdir(dir, { recursive: true });
+    const existing = await readAllSyncSelections(dir);
+    const channels = {
+        git: channel === 'git' ? sel : existing.git,
+        webdav: channel === 'webdav' ? sel : existing.webdav,
+    };
+    const payload = {
+        schemaVersion: SYNC_SELECTION_SCHEMA_VERSION,
+        channels: {
+            git: { mode: channels.git.mode, sections: channels.git.sections },
+            webdav: { mode: channels.webdav.mode, sections: channels.webdav.sections },
+        },
+    };
+    const target = path.join(dir, SYNC_SELECTION_FILE);
+    const data = stringifyJsonSafe(payload, { space: 2 });
+    await atomicWriteFile(target, data, { mode: 0o600 });
+}
+//# sourceMappingURL=sync-selection.js.map

package/lib/sync/sync-session.d.ts

@@ -0,0 +1,40 @@
+import type { ImportAnalysis, ImportPlan } from '../core/types.ts';
+import type { SyncConfig } from './sync-config.ts';
+/** 默认会话 TTL（30 分钟） */
+export declare const DEFAULT_SESSION_TTL_MS: number;
+/** 一次差异确认会话的完整数据 */
+export interface SyncSession {
+    id: string;
+    /** 临时标准 ZIP（apply-items 执行 executeImportPlan 需要） */
+    zipPath: string;
+    plan: ImportPlan;
+    analysis: ImportAnalysis;
+    /** 被拉取的远端快照 id */
+    snapshotId: string;
+    /** 该次同步使用的通道配置（git/webdav 通用；apply-items 据此重建引擎） */
+    config: SyncConfig;
+    /** 创建时间（epoch ms） */
+    createdAt: number;
+    /** 过期时间（epoch ms；过期条目惰性清理） */
+    expiresAt: number;
+}
+/** 内存会话存储；同 id 覆盖；过期条目视为不存在。 */
+export declare class SyncSessionStore {
+    private readonly sessions;
+    private readonly ttlMs;
+    private readonly now;
+    constructor(opts?: {
+        ttlMs?: number;
+        now?: () => number;
+    });
+    /** 登记（或覆盖）会话；id 缺省时自动生成。createdAt/expiresAt 缺省自动填充。返回会话 id。 */
+    set(session: Omit<SyncSession, 'id' | 'createdAt' | 'expiresAt'> & {
+        id?: string;
+        createdAt?: number;
+        expiresAt?: number;
+    }): string;
+    /** 读取会话；过期条目返回 undefined（惰性清理）。 */
+    get(id: string): SyncSession | undefined;
+    /** 删除会话（cancel / apply-items 消费后调用）。 */
+    delete(id: string): void;
+}

package/lib/sync/sync-session.js

@@ -0,0 +1,54 @@
+/**
+ * SyncSessionStore：一键同步差异确认会话的内存登记。
+ *
+ * 会话把「拉取预览」与「逐项执行导入」解耦：一次 /sync/sync 在内存持有一份
+ * 临时 ZIP 路径 + ImportPlan + ImportAnalysis，配一个 syncSessionId；
+ * /sync/apply-items 凭 id 复用这些数据，避免重复拉取/重复 build ZIP。
+ *
+ * 生命周期：
+ *  - 进程内存（不落盘），默认 TTL 30 分钟，过期条目惰性清理（get 时检查）；
+ *  - 同 id 覆盖（set 后旧 session 被新 session 替换，旧 ZIP 由上层负责清理）；
+ *  - delete 显式移除（/sync/cancel 与 apply-items 消费后调用）。
+ */
+import crypto from 'node:crypto';
+/** 默认会话 TTL（30 分钟） */
+export const DEFAULT_SESSION_TTL_MS = 30 * 60 * 1000;
+/** 内存会话存储；同 id 覆盖；过期条目视为不存在。 */
+export class SyncSessionStore {
+    sessions = new Map();
+    ttlMs;
+    now;
+    constructor(opts = {}) {
+        this.ttlMs = opts.ttlMs ?? DEFAULT_SESSION_TTL_MS;
+        this.now = opts.now ?? (() => Date.now());
+    }
+    /** 登记（或覆盖）会话；id 缺省时自动生成。createdAt/expiresAt 缺省自动填充。返回会话 id。 */
+    set(session) {
+        const id = session.id ?? `sync-session-${crypto.randomUUID()}`;
+        const createdAt = session.createdAt ?? this.now();
+        const expiresAt = session.expiresAt ?? createdAt + this.ttlMs;
+        this.sessions.set(id, {
+            ...session,
+            id,
+            createdAt,
+            expiresAt,
+        });
+        return id;
+    }
+    /** 读取会话；过期条目返回 undefined（惰性清理）。 */
+    get(id) {
+        const s = this.sessions.get(id);
+        if (s === undefined)
+            return undefined;
+        if (this.now() >= s.expiresAt) {
+            this.sessions.delete(id);
+            return undefined;
+        }
+        return { ...s };
+    }
+    /** 删除会话（cancel / apply-items 消费后调用）。 */
+    delete(id) {
+        this.sessions.delete(id);
+    }
+}
+//# sourceMappingURL=sync-session.js.map

package/lib/sync/sync-state.d.ts

@@ -0,0 +1,37 @@
+import type { MsgFunc } from '../core/messages.ts';
+import type { SectionData, SectionId } from '../schema/types.ts';
+import type { SnapshotFs } from './fs.ts';
+export declare const SYNC_STATE_SCHEMA_VERSION = 2;
+/** 历史可读取版本：v1 缺 lastSnapshotId 时做内存迁移到 v2（lastSnapshotId=''）。 */
+export declare const SYNC_STATE_SUPPORTED_VERSIONS: readonly number[];
+export declare const SYNC_STATE_FILE = "sync-state.json";
+/** 单个分区的同步状态：内容 hash + 最近变更时间 */
+export interface SyncSectionState {
+    hash: string;
+    updatedAt: string;
+}
+/** sync-state.json 结构 */
+export interface SyncState {
+    schemaVersion: number;
+    lastSyncAt: string;
+    sections: Partial<Record<SectionId, SyncSectionState>>;
+    /** 当前绑定的传输通道（type = SyncTransport.type，ref = 通道内引用，如 git 分支） */
+    transport?: {
+        type: string;
+        ref: string;
+    };
+    /** 最近一次同步的快照 ID（= 共同祖先指针）；'' = 从未同步或无祖先 */
+    lastSnapshotId: string;
+}
+/**
+ * 分区内容 hash：
+ * - JSON 分区：键序规范化的 JSON 序列化 → SHA-256（同一内容不同键序 → 相同 hash）
+ * - 文件类分区：文件相对路径 + 文件字节 SHA-256 的有序清单 → SHA-256
+ *   （文件数组顺序无关；contentHash 字段不参与，以字节为准）
+ */
+export declare function hashSection(data: SectionData): string;
+/** 读取同步状态；文件不存在 → 返回缺省空状态（从未同步）。
+ * v1 文件 → 内存迁移到 v2（lastSnapshotId=''），不在磁盘上就地升级。 */
+export declare function loadSyncState(dir: string, fsx?: SnapshotFs, msg?: MsgFunc): Promise<SyncState>;
+/** 保存同步状态（自动创建目录） */
+export declare function saveSyncState(dir: string, state: SyncState, fsx?: SnapshotFs): Promise<void>;

package/lib/sync/sync-state.js

@@ -0,0 +1,108 @@
+/**
+ * m-sync-transport：sync-state.json 模型。
+ * 记录上次同步时间与各分区内容 hash，供变更检测（与远端快照对比决定是否重传）。
+ * 纯逻辑 + 可注入 fs；不触碰真实 ~/.dsh。
+ */
+import { sha256Hex } from '../utils/hashing.js';
+import { parseJsonSafe, stringifyJsonSafe } from '../utils/json.js';
+import { zhMsg } from '../core/messages.js';
+import { createSnapshotFs, joinFs } from './fs.js';
+export const SYNC_STATE_SCHEMA_VERSION = 2;
+/** 历史可读取版本：v1 缺 lastSnapshotId 时做内存迁移到 v2（lastSnapshotId=''）。 */
+export const SYNC_STATE_SUPPORTED_VERSIONS = [1, 2];
+export const SYNC_STATE_FILE = 'sync-state.json';
+/** 文件类分区判定：{ version: 1, files: [...] }（duck-typing，与 JSON 分区区分） */
+function isFilesSection(data) {
+    const obj = data;
+    return data !== null && typeof data === 'object' && obj.version === 1 && Array.isArray(obj.files);
+}
+/** 键序规范化的 JSON 序列化（跨机器/跨解析稳定，用于内容 hash） */
+function canonicalJson(value) {
+    if (value === null || typeof value !== 'object') {
+        if (value === undefined)
+            return 'null'; // 防御：不产生 undefined 字面量
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((v) => canonicalJson(v)).join(',')}]`;
+    }
+    const obj = value;
+    const parts = [];
+    for (const key of Object.keys(obj).sort()) {
+        const v = obj[key];
+        if (v === undefined)
+            continue; // 与 JSON.stringify 一致：跳过 undefined 键
+        parts.push(`${JSON.stringify(key)}:${canonicalJson(v)}`);
+    }
+    return `{${parts.join(',')}}`;
+}
+/**
+ * 分区内容 hash：
+ * - JSON 分区：键序规范化的 JSON 序列化 → SHA-256（同一内容不同键序 → 相同 hash）
+ * - 文件类分区：文件相对路径 + 文件字节 SHA-256 的有序清单 → SHA-256
+ *   （文件数组顺序无关；contentHash 字段不参与，以字节为准）
+ */
+export function hashSection(data) {
+    if (isFilesSection(data)) {
+        const files = [...data.files]
+            .sort((a, b) => (a.relativePath < b.relativePath ? -1 : a.relativePath > b.relativePath ? 1 : 0))
+            .map((f) => `${f.relativePath}\u0000${sha256Hex(f.data)}`)
+            .join('\u0001');
+        return sha256Hex(`files:v1\u0000${files}`);
+    }
+    return sha256Hex(canonicalJson(data));
+}
+/** 读取同步状态；文件不存在 → 返回缺省空状态（从未同步）。
+ * v1 文件 → 内存迁移到 v2（lastSnapshotId=''），不在磁盘上就地升级。 */
+export async function loadSyncState(dir, fsx = createSnapshotFs(), msg = zhMsg) {
+    const file = joinFs(dir, SYNC_STATE_FILE);
+    if (!(await fsx.exists(file))) {
+        return { schemaVersion: SYNC_STATE_SCHEMA_VERSION, lastSyncAt: '', sections: {}, lastSnapshotId: '' };
+    }
+    const raw = Buffer.from(await fsx.readFile(file)).toString('utf8');
+    const parsed = parseJsonSafe(raw);
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(msg('sync.state.notObject'));
+    }
+    const obj = parsed;
+    if (typeof obj['schemaVersion'] !== 'number' || !SYNC_STATE_SUPPORTED_VERSIONS.includes(obj['schemaVersion'])) {
+        throw new Error(msg('sync.state.schemaUnsupported', { version: String(obj['schemaVersion']), expected: String(SYNC_STATE_SUPPORTED_VERSIONS.join('/')) }));
+    }
+    if (typeof obj['lastSyncAt'] !== 'string') {
+        throw new Error(msg('sync.state.lastSyncAt'));
+    }
+    if (obj['sections'] === null || typeof obj['sections'] !== 'object' || Array.isArray(obj['sections'])) {
+        throw new Error(msg('sync.state.sections'));
+    }
+    const sections = {};
+    for (const [sid, rec] of Object.entries(obj['sections'])) {
+        if (rec === null || typeof rec !== 'object' || Array.isArray(rec)) {
+            throw new Error(msg('sync.state.sectionRecord', { section: sid }));
+        }
+        const r = rec;
+        if (typeof r['hash'] !== 'string' || typeof r['updatedAt'] !== 'string') {
+            throw new Error(msg('sync.state.sectionFields', { section: sid }));
+        }
+        sections[sid] = { hash: r['hash'], updatedAt: r['updatedAt'] };
+    }
+    const state = {
+        schemaVersion: SYNC_STATE_SCHEMA_VERSION,
+        lastSyncAt: obj['lastSyncAt'],
+        sections,
+        lastSnapshotId: typeof obj['lastSnapshotId'] === 'string' ? obj['lastSnapshotId'] : '',
+    };
+    const t = obj['transport'];
+    if (t !== undefined) {
+        if (t === null || typeof t !== 'object' || typeof t['type'] !== 'string' || typeof t['ref'] !== 'string') {
+            throw new Error(msg('sync.state.transport'));
+        }
+        state.transport = { type: t.type, ref: t.ref };
+    }
+    return state;
+}
+/** 保存同步状态（自动创建目录） */
+export async function saveSyncState(dir, state, fsx = createSnapshotFs()) {
+    await fsx.mkdir(dir);
+    await fsx.writeFile(joinFs(dir, SYNC_STATE_FILE), new TextEncoder().encode(stringifyJsonSafe(state, { space: 2 })));
+}
+//# sourceMappingURL=sync-state.js.map

package/lib/sync/transport.d.ts

@@ -0,0 +1,75 @@
+/**
+ * m-sync-transport：SyncTransport 抽象层。
+ * 纯类型 + 纯 helper，零副作用、零 fs —— 传输通道实现（git 等）由后续波次提供。
+ * 与核心引擎同原则：只依赖 src/schema/types.ts 的纯类型，不 import 任何 DSH 运行时包。
+ */
+import type { EncryptionInfo, Manifest, SectionData, SectionId } from '../schema/types.ts';
+/** manifest 摘要：快照列表展示 / 变更判断所需的轻量来源信息 */
+export interface ManifestSummary {
+    schemaVersion: number;
+    dshVersion: string;
+    platform: string;
+    /** 快照包含的分区（按 manifest.sections 中为 true 的键） */
+    sectionIds: SectionId[];
+    containsSecrets: boolean;
+    /** 快照是否加密（sections 为 EncryptedSections 密文载荷）；缺省 false（旧快照兼容） */
+    encrypted?: boolean;
+    /** 产生该快照的同步通道（git / webdav；供同步历史展示触发来源；旧快照缺省 undefined） */
+    transport?: string;
+}
+/** 快照元信息：list() 条目 / upload() 返回值 */
+export interface SyncSnapshotMeta {
+    id: string;
+    createdAt: string;
+    /** 各分区内容 hash（sectionId → hashSection 结果），用于变更检测。
+     *  加密快照的 sections 为密文载荷，不参与明文 hash 比较 → 空对象。 */
+    sections: Partial<Record<SectionId, string>>;
+    manifest: ManifestSummary;
+}
+/** 加密快照的 sections 载荷：整个明文 sections 对象序列化后整体加密（AES-256-GCM）。 */
+export interface EncryptedSections {
+    encrypted: {
+        /** 加密参数（salt/iv/authTag base64；与 security/encryption.ts 的 EncryptionInfo 对齐） */
+        info: EncryptionInfo;
+        /** base64：带 DSC1 头的密文（明文 = 序列化的 sections Record） */
+        data: string;
+    };
+}
+/** 快照载荷：upload() 入参 / download() 返回 */
+export interface SyncSnapshot {
+    id: string;
+    createdAt: string;
+    manifest: ManifestSummary;
+    /** JSON 分区数据 + 文件类分区（FilesSection）；加密快照为 EncryptedSections 密文载荷 */
+    sections: Partial<Record<SectionId, SectionData>> | EncryptedSections;
+}
+/**
+ * 远端快照传输通道契约。
+ * 实现约定：同 id 重复 upload 视为覆盖（幂等友好）；download 对不存在的 id 必须抛错。
+ */
+export interface SyncTransport {
+    readonly type: string;
+    /** 列出远端已有快照（按 createdAt 升序） */
+    list(): Promise<SyncSnapshotMeta[]>;
+    /** 上传快照，返回其元信息（含各分区 hash） */
+    upload(snapshot: SyncSnapshot): Promise<SyncSnapshotMeta>;
+    /** 下载快照完整载荷 */
+    download(id: string): Promise<SyncSnapshot>;
+    /** 删除远端快照（不存在视为成功） */
+    delete(id: string): Promise<void>;
+}
+/** 由快照计算元信息：sections hash 记录 + manifest 摘要透传。
+ *  加密快照（sections 为密文载荷）→ sections hash 记录为空（密文无法与本地明文比较）。 */
+export declare function computeSnapshotMeta(snapshot: SyncSnapshot): SyncSnapshotMeta;
+/** 判定远端索引条目与本地快照「内容相同」（快照级跳过判定，供 webdav 通道增量上传用）：
+ *  仅比较各分区内容 hash（sections 全等），不比较 createdAt / manifest 摘要
+ *  （同 id 重复上传但内容未变 → 视为幂等覆盖，无需重新 PUT 载荷）。
+ *  - 本地 sections 为空对象（加密快照：密文无法与远端明文 hash 比较）→ 返回 false，
+ *    「无法比较」必须照常上传，绝不跳过；
+ *  - 键集合与每个键的 hash 值全部相等 → true；否则 false。
+ */
+export declare function sectionsEqual(remote: SyncSnapshotMeta, local: SyncSnapshotMeta): boolean;
+/** 判定 sections 是否为加密密文载荷（duck-typing：含 encrypted.info + encrypted.data 字符串）。 */
+export declare function isEncryptedSections(sections: unknown): sections is EncryptedSections;
+/** 从导出 Manifest 提取摘要 */
+export declare function manifestSummaryFrom(manifest: Manifest): ManifestSummary;

package/lib/sync/transport.js

@@ -0,0 +1,55 @@
+import { hashSection } from './sync-state.js';
+/** 由快照计算元信息：sections hash 记录 + manifest 摘要透传。
+ *  加密快照（sections 为密文载荷）→ sections hash 记录为空（密文无法与本地明文比较）。 */
+export function computeSnapshotMeta(snapshot) {
+    const sections = {};
+    if (!isEncryptedSections(snapshot.sections)) {
+        for (const [id, data] of Object.entries(snapshot.sections)) {
+            sections[id] = hashSection(data);
+        }
+    }
+    return { id: snapshot.id, createdAt: snapshot.createdAt, sections, manifest: snapshot.manifest };
+}
+/** 判定远端索引条目与本地快照「内容相同」（快照级跳过判定，供 webdav 通道增量上传用）：
+ *  仅比较各分区内容 hash（sections 全等），不比较 createdAt / manifest 摘要
+ *  （同 id 重复上传但内容未变 → 视为幂等覆盖，无需重新 PUT 载荷）。
+ *  - 本地 sections 为空对象（加密快照：密文无法与远端明文 hash 比较）→ 返回 false，
+ *    「无法比较」必须照常上传，绝不跳过；
+ *  - 键集合与每个键的 hash 值全部相等 → true；否则 false。
+ */
+export function sectionsEqual(remote, local) {
+    const r = remote.sections;
+    const l = local.sections;
+    if (Object.keys(l).length === 0)
+        return false; // 本地为空（加密快照）→ 无法比较
+    if (Object.keys(r).length !== Object.keys(l).length)
+        return false;
+    for (const key of Object.keys(r)) {
+        if (r[key] !== l[key])
+            return false;
+    }
+    return true;
+}
+/** 判定 sections 是否为加密密文载荷（duck-typing：含 encrypted.info + encrypted.data 字符串）。 */
+export function isEncryptedSections(sections) {
+    if (sections === null || typeof sections !== 'object')
+        return false;
+    const enc = sections.encrypted;
+    if (enc === null || typeof enc !== 'object')
+        return false;
+    const e = enc;
+    return typeof e.data === 'string' && e.data !== '' && e.info !== null && typeof e.info === 'object';
+}
+/** 从导出 Manifest 提取摘要 */
+export function manifestSummaryFrom(manifest) {
+    return {
+        schemaVersion: manifest.schemaVersion,
+        dshVersion: manifest.source.dshVersion,
+        platform: manifest.source.platform,
+        sectionIds: Object.entries(manifest.sections)
+            .filter(([, included]) => included)
+            .map(([id]) => id),
+        containsSecrets: manifest.security.containsSecrets,
+    };
+}
+//# sourceMappingURL=transport.js.map

package/lib/sync/ui-prefs.d.ts

@@ -0,0 +1,34 @@
+export declare const UI_PREFS_FILE = "ui-prefs.json";
+export declare const UI_PREFS_SCHEMA_VERSION = 1;
+/** 同步通道类型（与 sync-selection / sync-config 共享语义；避免循环 import 自行声明） */
+export type UiPrefsChannel = 'git' | 'webdav';
+/** 插件自身 UI 偏好（持久化面）。 */
+export interface UiPrefs {
+    schemaVersion: number;
+    /** 用户上次选择的同步通道；未配置为 undefined */
+    lastSyncChannel?: UiPrefsChannel;
+    /** Star 引导弹窗：首次进入页面时间（ms 时间戳）；未配置 = 尚未进入过页面 */
+    starPromptFirstSeenAt?: number;
+    /** Star 引导弹窗：用户点过「不再提示」（永久不再弹） */
+    starPromptDismissed?: boolean;
+    /** Star 引导弹窗：用户点过「去点 Star」（方案 A：引导完成，不再弹） */
+    starPromptClicked?: boolean;
+    /** 更新内容弹窗：上次已记录/展示过的插件版本号（如 '0.1.54'） */
+    releaseNotesLastSeenVersion?: string;
+    /** 更新内容弹窗：用户点过「永不提示」（永久不再自动弹出） */
+    releaseNotesDismissed?: boolean;
+}
+/** 缺省配置（首次无文件 / 损坏 / 不支持 schema 时回退） */
+export declare function defaultUiPrefs(): UiPrefs;
+/** 读取 UI 偏好；文件不存在 / 损坏 / 不支持 schema → 缺省值（不抛错）。 */
+export declare function readUiPrefs(dir: string): Promise<UiPrefs>;
+/** 写入 UI 偏好（原子写：临时文件 + rename；自动创建目录）。 */
+export declare function writeUiPrefs(dir: string, prefs: UiPrefs): Promise<void>;
+/**
+ * 局部原子更新：read → merge → write。
+ * 多端点共写 ui-prefs.json 时（sync/ui-prefs 与 star-prompt），任一端点写全量对象
+ * 都会丢掉另一端点刚写入的字段；统一走本函数按补丁合并，杜绝互相覆盖。
+ */
+export declare function updateUiPrefs(dir: string, patch: UiPrefsPatch): Promise<UiPrefs>;
+/** updateUiPrefs 的补丁类型（UiPrefs 全部可选字段，schemaVersion 不可补丁）。 */
+export type UiPrefsPatch = Partial<Omit<UiPrefs, 'schemaVersion'>>;