@logictan/dsh-config-manager 0.1.60

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

@@ -0,0 +1,81 @@
+import type { MsgFunc } from '../core/messages.ts';
+export declare const SYNC_CONFIG_FILE = "sync-config.json";
+/** 同步通道类型（git / webdav；host 侧统一引用，autosync-config / sync-selection 复用）。 */
+export type SyncTransportType = 'git' | 'webdav';
+/** 当前 sync-config.json schema 版本号（v3：双命名空间共存，切换通道不丢失另一通道配置）。 */
+export declare const SYNC_CONFIG_SCHEMA_VERSION = 3;
+/** 历史可读取版本：v1、v2、v3。 */
+export declare const SYNC_CONFIG_SUPPORTED_VERSIONS: readonly number[];
+/** git 通道配置（不含任何凭据；git 可执行文件固定使用系统 PATH 中的 git） */
+export interface GitConfig {
+    repoUrl: string;
+}
+/** webdav 通道配置（不含 password；password 走 DSH credentials） */
+export interface WebDavConfig {
+    /** WebDAV 端点地址（不含凭据；拒绝 userinfo） */
+    url: string;
+    /** 可选用户名（可回显） */
+    username?: string;
+}
+/**
+ * 完整双命名空间配置视图（v3 文件直接读取，供 status 路由回填另一通道的 repoUrl/url）。
+ * 与可辨识联合 SyncConfig 不同：git 和 webdav 命名空间同时存在，可能缺失。
+ */
+export interface FullSyncConfig {
+    transport: 'git' | 'webdav';
+    git?: GitConfig;
+    webdav?: WebDavConfig;
+}
+/** 持久化的同步通道配置：可辨识联合（schemaVersion 恒 2） */
+export type SyncConfig = {
+    schemaVersion: 2;
+    transport: 'git';
+    git: GitConfig;
+} | {
+    schemaVersion: 2;
+    transport: 'webdav';
+    webdav: WebDavConfig;
+};
+/** git 通道守卫 */
+export declare function isGitConfig(cfg: SyncConfig): cfg is Extract<SyncConfig, {
+    transport: 'git';
+}>;
+/** webdav 通道守卫 */
+export declare function isWebDavConfig(cfg: SyncConfig): cfg is Extract<SyncConfig, {
+    transport: 'webdav';
+}>;
+/**
+ * 读取同步通道配置；文件不存在/损坏/不支持 schema → null（视为未配置，UI 显示空表单）。
+ * 兼容旧文件：缺 schemaVersion 字段视为 v1（git 通道）。
+ * 恒返回 schemaVersion=2 的规范形态（v1 读取时归一为 git）。
+ */
+export declare function readSyncConfig(dir: string): Promise<SyncConfig | null>;
+/**
+ * 读取完整的双命名空间配置（供 status 路由回填另一通道的 repoUrl/url）。
+ * 文件不存在/损坏/无任何通道配置 → null（视为未配置）。
+ */
+export declare function readFullSyncConfig(dir: string): Promise<FullSyncConfig | null>;
+/**
+ * 读取指定通道的同步通道配置（供自动同步调度器按通道运行）。
+ * 从完整双命名空间配置取对应通道构造可辨识联合 SyncConfig；该通道未配置 → null。
+ */
+export declare function readSyncConfigFor(dir: string, channel: SyncTransportType): Promise<SyncConfig | null>;
+/**
+ * 保存同步通道配置（自动创建目录；恒写 schemaVersion=3 双命名空间）。
+ * - 写入当前通道的命名空间（git/webdav）；
+ * - 另一通道之前配置过 → 一并保留（切换通道不丢失另一通道的 repoUrl/url）；
+ * - 覆盖旧值；未配置过的字段不写入。
+ */
+export declare function writeSyncConfig(dir: string, cfg: SyncConfig): Promise<void>;
+/**
+ * 仓库地址合法性校验（返回错误消息；null = 合法）。
+ * 安全约束：token 永不拼入 repoUrl —— http(s) 地址带 userinfo（username[:password]@）直接拒绝，
+ * 引导用户把 token 放凭据字段（DSH credentials），避免 token 经 URL 泄漏进 git 历史/日志。
+ */
+export declare function validateRepoUrl(repoUrl: string, msg?: MsgFunc): string | null;
+/**
+ * WebDAV 端点地址合法性校验（返回错误消息；null = 合法）。
+ * 安全约束：口令/密码永不拼入 url —— 仅接受 http(s)，且拒绝带 userinfo
+ * （username[:password]@）的地址，引导用户把口令放 DSH credentials，避免凭据经 URL 泄漏进出入口/日志。
+ */
+export declare function validateWebDavUrl(url: string, msg?: MsgFunc): string | null;

package/lib/sync/sync-config.js

@@ -0,0 +1,281 @@
+/**
+ * m-sync-ui：同步通道配置的持久化（sync-config.json，schemaVersion v2）。
+ *
+ * 与 sync-state.json 的分工：sync-state 记录「同步了哪些分区、何时同步」（t4 拥有），
+ * 本文件只记录「上一次使用的同步通道配置」，供 UI 打开设置页时回填表单。
+ *
+ * schema v2（统一接口契约，captain 冻结）：
+ * - 顶层形状：
+ *     { "schemaVersion": 2, "transport": "git"|"webdav",
+ *       "git":    { "repoUrl": "..." },   // transport=git 时
+ *       "webdav": { "url": "...", "username": "..." } }    // transport=webdav 时
+ * - 顶层 transport 选择 + git/webdav 命名空间对象（嵌套，非扁平，避免歧义）。
+ *   git 命名空间不再含 gitBin（git 可执行文件固定使用系统 PATH 中的 git）。
+ * - webdav.url 不含任何凭据、拒绝 userinfo；username 可回显；
+ *   password 绝不入文件（走 DSH credentials ref `DSH_CONFIG_MANAGER_SYNC_WEBDAV_PASSWORD`）。
+ * - 代码内为可辨识联合 SyncConfig + isGitConfig()/isWebDavConfig() 守卫。
+ * - 兼容旧 v1 文件（{schemaVersion:1, repoUrl, gitBin?} 或缺 schemaVersion 视为 v1）
+ *   → 读取时归一为 v2 git 形态（旧 gitBin 字段被忽略/下一次保存时丢弃）。
+ *
+ * 安全不变量：
+ * - 配置文件绝不出现密码/token（webdav 仅存 url/可选 username；口令走 DSH credentials）。
+ * - url 校验：拒绝空白、非 http(s)、含 userinfo（username:password@）——仿 validateRepoUrl。
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { zhMsg } from '../core/messages.js';
+import { parseJsonSafe, stringifyJsonSafe } from '../utils/json.js';
+import { atomicWriteFile } from '../utils/atomic-write.js';
+export const SYNC_CONFIG_FILE = 'sync-config.json';
+/** 当前 sync-config.json schema 版本号（v3：双命名空间共存，切换通道不丢失另一通道配置）。 */
+export const SYNC_CONFIG_SCHEMA_VERSION = 3;
+/** 历史可读取版本：v1、v2、v3。 */
+export const SYNC_CONFIG_SUPPORTED_VERSIONS = [1, 2, 3];
+/** git 通道守卫 */
+export function isGitConfig(cfg) {
+    return cfg.transport === 'git';
+}
+/** webdav 通道守卫 */
+export function isWebDavConfig(cfg) {
+    return cfg.transport === 'webdav';
+}
+/** 从 v1 扁平形态解析 git 配置；缺 repoUrl → null（gitBin 已废弃：始终使用系统 PATH 中的 git） */
+function parseV1Git(obj) {
+    if (typeof obj['repoUrl'] !== 'string' || obj['repoUrl'] === '')
+        return null;
+    return { repoUrl: obj['repoUrl'] };
+}
+/** 从 v2 git 命名空间解析；缺有效 repoUrl → null */
+function parseV2GitNamespace(ns) {
+    if (ns === null || typeof ns !== 'object' || Array.isArray(ns))
+        return null;
+    return parseV1Git(ns);
+}
+/** 从 v2 webdav 命名空间解析；缺有效 url → null */
+function parseV2WebDavNamespace(ns) {
+    if (ns === null || typeof ns !== 'object' || Array.isArray(ns))
+        return null;
+    const o = ns;
+    if (typeof o['url'] !== 'string' || o['url'] === '')
+        return null;
+    const webdav = { url: o['url'] };
+    if (typeof o['username'] === 'string' && o['username'] !== '')
+        webdav.username = o['username'];
+    return webdav;
+}
+/**
+ * 读取同步通道配置；文件不存在/损坏/不支持 schema → null（视为未配置，UI 显示空表单）。
+ * 兼容旧文件：缺 schemaVersion 字段视为 v1（git 通道）。
+ * 恒返回 schemaVersion=2 的规范形态（v1 读取时归一为 git）。
+ */
+export async function readSyncConfig(dir) {
+    const file = path.join(dir, SYNC_CONFIG_FILE);
+    let raw;
+    try {
+        raw = await fs.readFile(file, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = parseJsonSafe(raw);
+    }
+    catch {
+        // 损坏 JSON / 体积超限 / 嵌套过深 → 视为未配置（不抛错）
+        return null;
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+        return null;
+    const obj = parsed;
+    // schemaVersion：缺省视为 v1（兼容旧文件）；非缺省但不在支持列表 → 拒绝
+    if (obj['schemaVersion'] !== undefined && typeof obj['schemaVersion'] !== 'number') {
+        return null;
+    }
+    const ver = typeof obj['schemaVersion'] === 'number' ? obj['schemaVersion'] : 1;
+    if (!SYNC_CONFIG_SUPPORTED_VERSIONS.includes(ver))
+        return null;
+    if (ver === 1) {
+        const git = parseV1Git(obj);
+        if (git === null)
+            return null;
+        return { schemaVersion: 2, transport: 'git', git };
+    }
+    // v2 / v3：顶层 transport 选择（v3 双命名空间并存，按 transport 返回对应通道）
+    const transport = obj['transport'];
+    if (transport !== 'git' && transport !== 'webdav')
+        return null;
+    if (transport === 'git') {
+        const git = parseV2GitNamespace(obj['git']);
+        if (git === null)
+            return null;
+        return { schemaVersion: 2, transport: 'git', git };
+    }
+    const webdav = parseV2WebDavNamespace(obj['webdav']);
+    if (webdav === null)
+        return null;
+    return { schemaVersion: 2, transport: 'webdav', webdav };
+}
+/**
+ * 读取 sync-config.json 原始内容，提取 git/webdav 两个命名空间（不存在/无效 → undefined）。
+ * 供 writeSyncConfig 合并保留另一通道配置用：切换通道保存时不得丢弃另一通道的 repoUrl/url。
+ */
+function readBothNamespaces(file) {
+    return (async () => {
+        let raw;
+        try {
+            raw = await fs.readFile(file, 'utf8');
+        }
+        catch {
+            return {}; // 文件不存在：无历史配置
+        }
+        let parsed;
+        try {
+            parsed = parseJsonSafe(raw);
+        }
+        catch {
+            return {}; // 损坏 JSON：按无历史配置处理（不阻塞保存）
+        }
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+            return {};
+        const o = parsed;
+        const out = {};
+        const git = parseV2GitNamespace(o['git']);
+        if (git !== null)
+            out.git = git;
+        const webdav = parseV2WebDavNamespace(o['webdav']);
+        if (webdav !== null)
+            out.webdav = webdav;
+        // v1 旧文件（无命名空间）：git 读扁平 repoUrl
+        if (out.git === undefined && out.webdav === undefined) {
+            const v1 = parseV1Git(o);
+            if (v1 !== null)
+                out.git = v1;
+        }
+        return out;
+    })();
+}
+/**
+ * 读取完整的双命名空间配置（供 status 路由回填另一通道的 repoUrl/url）。
+ * 文件不存在/损坏/无任何通道配置 → null（视为未配置）。
+ */
+export async function readFullSyncConfig(dir) {
+    const file = path.join(dir, SYNC_CONFIG_FILE);
+    const both = await readBothNamespaces(file);
+    if (both.git === undefined && both.webdav === undefined)
+        return null;
+    // 从原始文件读取当前活动 transport 字段
+    let transport = 'git';
+    try {
+        const raw = await fs.readFile(file, 'utf8');
+        const parsed = parseJsonSafe(raw);
+        if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            const o = parsed;
+            if (o['transport'] === 'webdav')
+                transport = 'webdav';
+        }
+    }
+    catch { /* 默认 git */ }
+    return { transport, git: both.git, webdav: both.webdav };
+}
+/**
+ * 读取指定通道的同步通道配置（供自动同步调度器按通道运行）。
+ * 从完整双命名空间配置取对应通道构造可辨识联合 SyncConfig；该通道未配置 → null。
+ */
+export async function readSyncConfigFor(dir, channel) {
+    const full = await readFullSyncConfig(dir);
+    if (full === null)
+        return null;
+    if (channel === 'webdav') {
+        if (full.webdav === undefined)
+            return null;
+        return { schemaVersion: 2, transport: 'webdav', webdav: full.webdav };
+    }
+    if (full.git === undefined)
+        return null;
+    return { schemaVersion: 2, transport: 'git', git: full.git };
+}
+/**
+ * 保存同步通道配置（自动创建目录；恒写 schemaVersion=3 双命名空间）。
+ * - 写入当前通道的命名空间（git/webdav）；
+ * - 另一通道之前配置过 → 一并保留（切换通道不丢失另一通道的 repoUrl/url）；
+ * - 覆盖旧值；未配置过的字段不写入。
+ */
+export async function writeSyncConfig(dir, cfg) {
+    await fs.mkdir(dir, { recursive: true });
+    const file = path.join(dir, SYNC_CONFIG_FILE);
+    const existing = await readBothNamespaces(file);
+    const payload = {
+        schemaVersion: SYNC_CONFIG_SCHEMA_VERSION,
+        transport: cfg.transport,
+    };
+    if (isGitConfig(cfg)) {
+        payload.git = cfg.git;
+        // 保留另一通道的 webdav 配置（存在时）
+        if (existing.webdav !== undefined)
+            payload.webdav = existing.webdav;
+    }
+    else {
+        payload.webdav = cfg.webdav;
+        // 保留另一通道的 git 配置（存在时）
+        if (existing.git !== undefined)
+            payload.git = existing.git;
+    }
+    await atomicWriteFile(file, stringifyJsonSafe(payload, { space: 2 }), { mode: 0o600 });
+}
+/**
+ * 仓库地址合法性校验（返回错误消息；null = 合法）。
+ * 安全约束：token 永不拼入 repoUrl —— http(s) 地址带 userinfo（username[:password]@）直接拒绝，
+ * 引导用户把 token 放凭据字段（DSH credentials），避免 token 经 URL 泄漏进 git 历史/日志。
+ */
+export function validateRepoUrl(repoUrl, msg = zhMsg) {
+    if (typeof repoUrl !== 'string' || repoUrl.trim() === '') {
+        return 'repoUrl is required';
+    }
+    const url = repoUrl.trim();
+    if (/\s/.test(url)) {
+        return msg('sync.configWhitespace');
+    }
+    if (/^https?:\/\//i.test(url)) {
+        let parsed;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            return msg('sync.configUnparseable', { url });
+        }
+        if (parsed.username !== '' || parsed.password !== '') {
+            return msg('sync.configUserinfo');
+        }
+    }
+    return null;
+}
+/**
+ * WebDAV 端点地址合法性校验（返回错误消息；null = 合法）。
+ * 安全约束：口令/密码永不拼入 url —— 仅接受 http(s)，且拒绝带 userinfo
+ * （username[:password]@）的地址，引导用户把口令放 DSH credentials，避免凭据经 URL 泄漏进出入口/日志。
+ */
+export function validateWebDavUrl(url, msg = zhMsg) {
+    if (typeof url !== 'string' || url.trim() === '') {
+        return 'url is required';
+    }
+    const cleaned = url.trim();
+    if (/\s/.test(cleaned)) {
+        return msg('sync.configWhitespace');
+    }
+    if (!/^https?:\/\//i.test(cleaned)) {
+        return msg('sync.configUnparseable', { url: cleaned });
+    }
+    let parsed;
+    try {
+        parsed = new URL(cleaned);
+    }
+    catch {
+        return msg('sync.configUnparseable', { url: cleaned });
+    }
+    if (parsed.username !== '' || parsed.password !== '') {
+        return msg('sync.configUserinfo');
+    }
+    return null;
+}
+//# sourceMappingURL=sync-config.js.map

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

@@ -0,0 +1,269 @@
+import { Importer } from '../core/importer.ts';
+import type { ConfigAdapter, GlobalConflictStrategy, HostContext, ImportAnalysis, ImportPlan, ImportResult, PlanItem, PlanItemKind } from '../core/types.ts';
+import type { SectionData, SectionId } from '../schema/types.ts';
+import type { SnapshotFs } from './fs.ts';
+import type { SyncSnapshot, SyncSnapshotMeta, SyncTransport } from './transport.ts';
+import type { MsgFunc } from '../core/messages.ts';
+import type { TransactionSnapshotContext } from '../core/types.ts';
+import type { PlanItemProgress } from '../core/analyzer.ts';
+export interface SyncEngineOptions {
+    ctx: HostContext;
+    transport: SyncTransport;
+    /** sync-state.json 所在目录 */
+    stateDir: string;
+    /** 分区 adapter 列表（缺省 createAdapters()；宿主应注入 namespaces 等） */
+    adapters?: ConfigAdapter[];
+    /** pull 需要；不注入则 pull 抛错（push 不受影响） */
+    importer?: Importer;
+    now?: () => Date;
+    /** 快照 id 生成器（缺省 sync-<uuid>；须符合通道安全字符集） */
+    snapshotId?: () => string;
+    /** 记录到 sync-state.transport.ref（如 git 分支名） */
+    transportRef?: string;
+    /** 本地散文件快照副本目录（push 落盘审计副本；不传则跳过本地落盘） */
+    localSnapshotsDir?: string;
+    /** 一键回滚兜底快照目录（apply-items 落盘；缺省 <stateDir>/snapshots，
+     *  与 Host /sync/rollback 路由读取的目录保持一致，否则回滚找不到 snapshot.json） */
+    rollbackSnapshotsDir?: string;
+    /** pull 临时 ZIP 目录（缺省 os.tmpdir()） */
+    zipDir?: string;
+    exporterVersion?: string;
+    fsx?: SnapshotFs;
+    /** 消息翻译器（缺省 ctx.msg ?? zh） */
+    msg?: MsgFunc;
+    /**
+     * 同步范围（自定义同步模式持久化配置）：只处理这些分区。
+     * 缺省 = 全部推荐分区。应用于 push / pull 等全部链路，供自动同步等后台流程复用
+     * 用户选择；手动请求仍可用 push(opts.sections) 覆盖。
+     */
+    sections?: SectionId[];
+}
+export interface SyncPushOptions {
+    /** 覆盖自动生成的快照 id */
+    snapshotId?: string;
+    /** 仅同步指定分区（缺省 = 全部推荐分区）。
+     *  传入未知分区 → 忽略并告警（不静默吞掉）。 */
+    sections?: SectionId[];
+}
+export interface SyncPullOptions {
+    /** 指定远端快照 id（缺省 = 最新） */
+    snapshotId?: string;
+    /** 冲突全局策略（缺省 replace：勾选即同步，远端值直接覆盖本地，不做 diff/合并） */
+    strategy?: GlobalConflictStrategy;
+}
+export interface SyncPushReport {
+    ok: boolean;
+    snapshotId: string;
+    /** 实际进入同步的分区 */
+    sections: SectionId[];
+    /** 分区级告警（单项失败不拖垮整体，§34.17 语义） */
+    warnings: string[];
+    message?: string;
+}
+/** 差异报告中的单个变更项（PlanItem 摘要，不含敏感细节） */
+export interface PullChange {
+    id: string;
+    adapter: SectionId;
+    kind: PlanItemKind;
+    description: string;
+    severity: PlanItem['severity'];
+}
+export interface SyncPullReport {
+    ok: boolean;
+    snapshotId: string;
+    changes: PullChange[];
+    /** 是否存在需要人工决策的项（Conflict / MissingSecret / MissingDependency / 路径问题）。 */
+    needsReview: boolean;
+    message?: string;
+}
+/** push 前只读预览 ——「将推送什么」的单分区摘要（不写远端、不落盘）。 */
+export interface SyncPushPreviewSection {
+    /** 分区 id（将进入快照的分区） */
+    section: SectionId;
+    /** 分区内条目计数（adapter.export 的 counts 聚合；无计数时为 0） */
+    count: number;
+    /** 相对上次基线（sync-state）是否变化：true = 本次会更新该分区；false = 与基线一致 */
+    changed: boolean;
+}
+/** push 前预览结果（零写入）。 */
+export interface SyncPushPreview {
+    ok: boolean;
+    /** 将推送的分区清单（含计数与变化标记） */
+    sections: SyncPushPreviewSection[];
+    /** 远端现有快照数（0 = 首次推送将创建首个基线） */
+    remoteSnapshotCount: number;
+    message?: string;
+}
+/** 一键 sync 预览结果（preview() 返回；临时 ZIP 由调用方持有并负责清理）。 */
+export interface SyncPreviewResult {
+    ok: boolean;
+    /** 临时标准 ZIP 路径（apply-items 复用 executeImportPlan 需要；调用方清理） */
+    zipPath: string;
+    plan: ImportPlan | null;
+    analysis: ImportAnalysis | null;
+    snapshotId: string;
+    message?: string;
+}
+/** applyItems 报告（§3.4 ApplyItemsResponse 的服务端形态） */
+export interface ApplyItemsReport {
+    ok: boolean;
+    /** 实际写入的分区 id 列表（去重） */
+    applied: string[];
+    /** 未采纳的 itemId 列表 */
+    skipped?: string[];
+    /** 应用前快照 id（UI 一键回滚用；失败时仍透传以便排查） */
+    restoreId: string;
+    /** 任一失败是否整体回滚 */
+    rolledBack: boolean;
+    warnings: string[];
+    failed: {
+        itemId: string;
+        message?: string;
+    }[];
+    /** 透传 executeImportPlan 结果 */
+    result: ImportResult | null;
+    needsRestart?: boolean;
+}
+/**
+ * 远端快照保留数量上限：每次 push 上传成功后对远端裁剪，
+ * 保留最新 N 个（按 createdAt 升序的最末 N 个，含刚 push 的），更旧的逐个删除。
+ * 只按数量裁剪，不按时间窗口。删除失败只告警（进 push 的 warnings），不上抛阻断主流程。
+ */
+export declare const MAX_REMOTE_SNAPSHOTS = 10;
+export declare class SyncEngine {
+    private readonly ctx;
+    private readonly transport;
+    private readonly stateDir;
+    private readonly adapters;
+    private readonly importer;
+    private readonly now;
+    private readonly snapshotIdFn;
+    private readonly transportRef;
+    private readonly localSnapshotsDir;
+    private readonly rollbackSnapshotsDir;
+    private readonly zipDir;
+    private readonly exporterVersion;
+    private readonly fsx;
+    private readonly msg;
+    private readonly sections;
+    constructor(opts: SyncEngineOptions);
+    /** 参与同步的分区全集：构造注入 sections（同步范围）时按注入范围过滤 ——
+     *  自动同步等后台流程 push/pull 全链路复用用户选择；手动请求仍可用 push(opts.sections) 覆盖。 */
+    private syncAdapters;
+    /** 未显式传 sections 时的默认范围。
+     *
+     *  - 构造注入 sections（高级模式：用户已在 UI 勾选并持久化）→ 该选择**就是**默认范围，
+     *    不再按 defaultIncluded 收窄（否则高级模式勾选的 sessions/pluginFiles 会被悄悄剔除）；
+     *  - 未注入（默认模式「快速导出」）→ 只取推荐分区 defaultIncluded。
+     *
+     *  defaultIncluded=false 的分区（sessions 含历史会话明文、pluginFiles）语义是「用户显式
+     *  勾选才同步」；把它们并进默认模式的范围会绕过 UI 勾选与「将同步 N 个推荐分区」计数，
+     *  把敏感内容静默推到远端通道。 */
+    private defaultTargets;
+    /**
+     * push 候选 adapter：
+     * - sections 缺省/空 → 全部推荐分区（defaultIncluded）；
+     * - sections 显式给出 → 从**全部已挂载分区**取命中项（显式勾选可触达 defaultIncluded=false
+     *   的分区，这正是「默认关闭」的含义）；未知分区 → 警告跳过（不静默，用户能看见自己勾了哪个无效项）。
+     */
+    private pushTargets;
+    /**
+     * 快照读取准备（download 后、使用前）：
+     * 加密快照（manifest.encrypted）→ 明确拒绝：同步通道已不再产生加密快照，
+     * 旧加密快照无法用当前引擎读取（拒绝静默当明文处理）。
+     */
+    private prepareSnapshot;
+    /**
+     * push：导出分区（真实值）→ 组装快照 → 本地散文件副本 → transport.upload → 更新 sync-state。
+     * 单项分区导出失败只告警跳过（§34.17），全部失败才整体失败。
+     * opts.sections：指定仅同步这些分区（自定义模式）；缺省 = 全部推荐分区。
+     */
+    push(opts?: SyncPushOptions): Promise<SyncPushReport>;
+    /**
+     * push 前只读预览「将推送什么」—— 零写入、零远端变更：
+     *  - 导出目标分区（与 push 同口径：sections 过滤）；
+     *  - 逐分区相对上次基线（sync-state.sections hash）的 changed 标记；
+     *  - 远端现有快照数（list 只读；首次推送 = 0）。
+     * 任何失败都不写任何内容；预览只是 push 的「确认前说明书」。
+     */
+    previewPush(opts?: SyncPushOptions): Promise<SyncPushPreview>;
+    /**
+     * 裁剪远端快照：调用 transport.list() 获取全部快照（按 createdAt 升序），
+     * 保留最新 MAX_REMOTE_SNAPSHOTS 个（含刚 push 的 pushedId），对更旧的逐个调用 transport.delete()。
+     * 只按数量裁剪，不按时间窗口。
+     *
+     * 失败语义：list/delete 失败均只 push 进 warnings，不上抛 —— 裁剪是「尽力而为」的后台整理，
+     * 绝不影响 push 主流程的成功与否（§34.17 分区级告警同款语义）。
+     */
+    private pruneRemoteSnapshots;
+    /**
+     * pull：拉取远端最新（或指定）快照 → 转临时标准 ZIP →
+     * 复用 Importer 预览流程（analyzeImport/createImportPlan）产出差异报告。
+     * 绝不直接写配置、绝不执行导入；执行由上层按用户确认后走 Importer.executeImportPlan。
+     */
+    pull(opts?: SyncPullOptions): Promise<SyncPullReport>;
+    /** 列出远端已有快照（按 createdAt 升序）—— 供「选择历史快照」下拉。 */
+    listSnapshots(): Promise<SyncSnapshotMeta[]>;
+    /**
+     * 远端是否出现比本地共同祖先（sync-state.lastSnapshotId）更新的快照（§3.2「检测到远端新快照」）。
+     * - 远端为空 → false（无物可拉）；
+     * - 本地从未同步（lastSnapshotId=''）且远端非空 → true（首次可拉）；
+     * - 否则比较远端最新快照 id 与 lastSnapshotId。
+     * 只读远端列表（transport.list），不做下载/合并。
+     */
+    hasNewRemoteSnapshot(): Promise<boolean>;
+    /**
+     * 本地配置当前内容与上次基线（sync-state.sections hash）相比是否有变化（§3.1 上传「看变化」）。
+     * - 从未同步（sync-state.sections 为空）→ true；
+     * - 任一分区当前导出 hash ≠ 基线 hash → true；
+     * - 全部一致 → false（无本地改动，不上传）。
+     * 只读本地导出 + sync-state，不写任何东西、不碰远端。
+     */
+    hasLocalChanges(): Promise<boolean>;
+    /**
+     * 一键同步预览：拉取远端（最新或指定历史快照）→ 转临时 ZIP → Importer 分析出计划。
+     * 与 pull 的区别：临时 ZIP **不清理**（由调用方 / 会话持有，供 apply-items 复用），
+     * 并返回完整 plan/analysis/snapshotId 供会话登记。
+     * 调用方负责在会话消费或取消后清理 zipPath 所在目录。
+     */
+    preview(opts?: SyncPullOptions): Promise<SyncPreviewResult>;
+    /**
+     * 记录基线：写本地快照副本 + 更新 sync-state
+     * （lastSnapshotId、每分区 hash/updatedAt、lastSyncAt、transport）。
+     * 通常由 push() 在上传成功后调用，也可被上层（apply-items 完成后）显式调用。
+     */
+    recordBaseline(snapshotId: string, sections: SyncSnapshot['sections'], nowIso?: string): Promise<void>;
+    /**
+     * applyItems：按用户对差异项的逐项决策执行导入（§3.4/§5.3）。
+     *
+     * 接收「会话级临时 ZIP + 子计划」，直接执行
+     * （backup.createSnapshot 兜底 → importer.executeImportPlan → 成功 recordBaseline / 失败 rollback）。
+     *
+     * @param zipPath 会话级临时标准 ZIP（由 sync 预览生成，包含采纳项的 payload）
+     * @param subPlan 子计划（仅含采纳项的 ImportPlan；globalStrategy/pathMappings/needsRestart 沿用会话 plan）
+     * @param opts 执行选项（onItem 进度回调）
+     * @returns ApplyItemsReport（ok/applied/restoreId/rolledBack/warnings/result）
+     */
+    applyItems(zipPath: string, subPlan: ImportPlan, opts?: {
+        onItem?: (info: PlanItemProgress) => void;
+        /** Phase 4 生产 journal↔snapshot 绑定（deferred；透传给 Importer.executeImportPlan） */
+        snapshotBinding?: TransactionSnapshotContext;
+        /**
+         * 本次应用的**远端快照 id**（preview() 返回值）。
+         *
+         * 必须传：基线（sync-state.lastSnapshotId）要与「刚刚应用的远端快照」对齐，
+         * 否则 `hasNewRemoteSnapshot()` 会把同一个远端快照一直判定为「新的」，
+         * 自动同步每轮都会重复拉取同一个快照（空转）。
+         * 缺省（不传）时才回退到本地新生成的 id —— 仅适用于「本地产生的快照」语义。
+         */
+        snapshotId?: string;
+    }): Promise<ApplyItemsReport>;
+    /** 散文件快照 → 标准导出 ZIP（临时目录，用完即删）：buildManifest + checksums + 平铺分区 */
+    private snapshotToZip;
+}
+/**
+ * 快照是否实际携带凭据值：复用 exporter 的敏感字段扫描器（单一真源，不另造字段表）。
+ * 用于如实标注 manifest.security.containsSecrets —— 标注必须与内容一致，
+ * 否则「含明文却标注 false」会让下游按「无秘密」处理。
+ */
+export declare function sectionsCarrySecrets(sections: Partial<Record<SectionId, SectionData>>): boolean;