dsh-config-manager 0.1.20 → 0.1.21

package/lib/sync/autosync-scheduler.js

@@ -0,0 +1,379 @@
+/**
+ * AutoSyncScheduler：宿主后台自动同步调度器。
+ *
+ * 生命周期：
+ *  - start()：读 autosync-config；若 enabled 启动定时器（按 interval）；无条件执行一次
+ *    「启动触发下载合并」（受 startupMinIntervalMs 阈值约束）。
+ *  - stop()：清定时器、标记不再调度。
+ *  - runOnce()：执行一次完整双向自动同步（§6.1 流程）。
+ *
+ * 核心逻辑（runOnce）：
+ *  - 读配置；若 !enabled → return
+ *  - runs.register('autosync') 防重复；同 kind running → 跳过
+ *  - readSyncConfig → repoUrl 无 → 记 skipped(未配置) → return
+ *  - Phase A: engine.merge() 三方合并 → 判定 needsReview（冲突/缺失依赖/Install/Error）
+ *  - 冲突 → 跳过 + 写历史 skipped + conflictedSections[] → return
+ *  - Phase B: 无冲突 → engine.applyMergePlan(apply) 写入本地
+ *  - Phase C: 完整双向 → engine.push() 上传
+ *  - 收尾：写 autosync-config（lastRunAt, lastRunStatus, consecutiveFailures, lastRunHistoryId）
+ *
+ * 连续失败计数：只对网络/传输/apply 真实失败计数；skipped（未配置/冲突跳过/无远端）不计。
+ * 连续失败 ≥ 3 → host.log.warn 通知 + 记 notifiedAt。
+ */
+import crypto from 'node:crypto';
+import { readAutosyncConfig, writeAutosyncConfig } from "./autosync-config.js";
+import { readSyncConfig } from "./sync-config.js";
+import { readSyncHistory, appendAutosyncEntry } from "./sync-history.js";
+/** 间隔 → ms 换算（§4.3） */
+export function intervalToMs(interval) {
+    const table = {
+        '5m': 5 * 60 * 1000,
+        '15m': 15 * 60 * 1000,
+        '30m': 30 * 60 * 1000,
+        '60m': 60 * 60 * 1000,
+        '6h': 6 * 60 * 60 * 1000,
+        '12h': 12 * 60 * 60 * 1000,
+        '24h': 24 * 60 * 60 * 1000,
+    };
+    return table[interval];
+}
+/**
+ * 启动触发下载合并且满足阈值（now - lastRunAt >= startupMinIntervalMs）？
+ * lastRunAt 为 undefined（从未运行）→ true。
+ */
+export function shouldTriggerStartupRun(lastRunAt, startupMinIntervalMs, nowMs = Date.now()) {
+    if (lastRunAt === undefined || lastRunAt === '')
+        return true;
+    const lastMs = Date.parse(lastRunAt);
+    if (Number.isNaN(lastMs))
+        return true;
+    return nowMs - lastMs >= startupMinIntervalMs;
+}
+export class AutoSyncScheduler {
+    syncDir;
+    host;
+    makeSyncEngine;
+    msg;
+    runs;
+    now;
+    readConfig;
+    writeConfig;
+    readSyncConfigFn;
+    readHistoryFn;
+    appendHistoryFn;
+    setTimer;
+    clearTimer;
+    timer = null;
+    stopped = false;
+    running = false;
+    constructor(opts) {
+        this.syncDir = opts.syncDir;
+        this.host = opts.host;
+        this.makeSyncEngine = opts.makeSyncEngine;
+        this.msg = opts.msg;
+        this.runs = opts.runs;
+        this.now = opts.now ?? (() => new Date());
+        this.readConfig = opts.readConfig ?? (() => readAutosyncConfig(this.syncDir));
+        this.writeConfig = opts.writeConfig ?? ((cfg) => writeAutosyncConfig(this.syncDir, cfg));
+        this.readSyncConfigFn = opts.readSyncConfigFn ?? (() => readSyncConfig(this.syncDir));
+        this.readHistoryFn = opts.readHistoryFn ?? (() => readSyncHistory(this.syncDir));
+        this.appendHistoryFn = opts.appendHistoryFn ?? ((entry) => appendAutosyncEntry(this.syncDir, entry));
+        this.setTimer = opts.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+        this.clearTimer = opts.clearTimer ?? ((t) => clearTimeout(t));
+    }
+    /** 启动：读配置 → 若 enabled 启动定时器 → 无条件执行一次启动触发下载合并。 */
+    start() {
+        if (this.stopped)
+            return;
+        this.refreshTimer();
+        void this.startupRun();
+    }
+    /** 停止：清定时器、标记不再调度；正在执行的任务允许自然结束。 */
+    stop() {
+        this.stopped = true;
+        if (this.timer !== null) {
+            this.clearTimer(this.timer);
+            this.timer = null;
+        }
+    }
+    /** 重新加载配置（路由 POST /sync/autosync 后调用）。 */
+    async reload() {
+        if (this.stopped)
+            return;
+        this.refreshTimer();
+    }
+    refreshTimer() {
+        if (this.timer !== null) {
+            this.clearTimer(this.timer);
+            this.timer = null;
+        }
+        void this.readConfig().then((cfg) => {
+            if (this.stopped || !cfg.enabled)
+                return;
+            const ms = intervalToMs(cfg.interval);
+            this.timer = this.setTimer(() => {
+                if (this.stopped)
+                    return;
+                void this.runOnce().catch((err) => {
+                    this.host.log.error('自动同步定时触发失败', { error: err instanceof Error ? err.message : String(err) });
+                });
+            }, ms);
+        }).catch(() => { });
+    }
+    /** 启动触发下载合并（受 startupMinIntervalMs 阈值约束）。 */
+    async startupRun() {
+        try {
+            const cfg = await this.readConfig();
+            if (!cfg.enabled)
+                return; // 总开关关闭 → 启动触发不执行
+            if (!shouldTriggerStartupRun(cfg.lastRunAt, cfg.startupMinIntervalMs, this.now().getTime())) {
+                this.host.log.info('自动同步启动触发跳过：距上次运行未达阈值');
+                return;
+            }
+            await this.runOnce({ startup: true });
+        }
+        catch (err) {
+            this.host.log.error('启动触发下载合并失败', { error: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    /**
+     * 执行一次自动同步（§6.1）。
+     * @param opts.startup - true 表示启动触发变体（只做 Phase A+B，不做 Phase C push）
+     */
+    async runOnce(opts = {}) {
+        if (this.running)
+            return { status: 'skipped', direction: 'none', skipReason: 'running', historyId: '', consecutiveFailures: 0 };
+        const cfg = await this.readConfig();
+        if (!cfg.enabled) {
+            return { status: 'skipped', direction: 'none', skipReason: 'disabled', historyId: '', consecutiveFailures: cfg.consecutiveFailures };
+        }
+        this.running = true;
+        const nowIso = this.now().toISOString();
+        const historyId = `autosync-${crypto.randomUUID()}`;
+        // runs 防重复：同 kind running → 跳过（内部语义，不打搅用户）
+        let runId = null;
+        try {
+            const run = this.runs.register('autosync');
+            runId = run.runId;
+        }
+        catch {
+            this.running = false;
+            return { status: 'skipped', direction: 'none', skipReason: 'conflict', historyId, consecutiveFailures: cfg.consecutiveFailures };
+        }
+        try {
+            // 读 sync-config → repoUrl
+            const syncCfg = await this.readSyncConfigFn();
+            if (syncCfg === null || syncCfg.repoUrl === '') {
+                const result = {
+                    status: 'skipped', direction: 'none', skipReason: 'unconfigured', historyId,
+                    consecutiveFailures: cfg.consecutiveFailures,
+                };
+                await this.appendHistoryFn({
+                    direction: 'both',
+                    status: 'skipped',
+                    skipReason: 'unconfigured',
+                    createdAt: nowIso,
+                    failureCountAtRun: cfg.consecutiveFailures,
+                });
+                await this.writeFinalConfig(cfg, result, nowIso, historyId);
+                return result;
+            }
+            const engine = this.makeSyncEngine(syncCfg.repoUrl, syncCfg.gitBin);
+            // Phase A: pull 合并（下载）
+            let mergePlan;
+            try {
+                mergePlan = await engine.merge();
+            }
+            catch (err) {
+                const error = err instanceof Error ? err.message : String(err);
+                const result = {
+                    status: 'failed', direction: 'pull', error, historyId,
+                    consecutiveFailures: cfg.consecutiveFailures + 1,
+                };
+                await this.appendHistoryFn({
+                    direction: 'pull', status: 'failed', error, createdAt: nowIso,
+                    failureCountAtRun: cfg.consecutiveFailures + 1,
+                });
+                await this.writeFinalConfig(cfg, result, nowIso, historyId);
+                this.maybeNotify(cfg.consecutiveFailures + 1, historyId, nowIso);
+                return result;
+            }
+            // 判定 needsReview
+            const reviewSections = mergePlan.sections.filter((s) => s.decision === 'conflict');
+            if (reviewSections.length > 0) {
+                const conflictedSections = reviewSections.map((s) => s.id);
+                const result = {
+                    status: 'skipped', direction: 'pull', skipReason: 'conflict',
+                    conflictedSections, historyId,
+                    consecutiveFailures: cfg.consecutiveFailures,
+                };
+                await this.appendHistoryFn({
+                    direction: 'pull', status: 'skipped', skipReason: 'conflict',
+                    conflictedSections, createdAt: nowIso,
+                    failureCountAtRun: cfg.consecutiveFailures,
+                });
+                await this.writeFinalConfig(cfg, result, nowIso, historyId);
+                return result;
+            }
+            // 无冲突：构造 SyncApplyPlan（autoApply = 所有 useRemote/keepLocal 项；skipped = skip 项）
+            const apply = buildAutoApplyPlan(mergePlan);
+            if (apply.autoApply.length === 0) {
+                // 无物可应用（全部 skip / 无变化）
+                const result = {
+                    status: 'success', direction: 'pull', skipReason: 'unchanged', historyId,
+                    consecutiveFailures: 0,
+                };
+                await this.appendHistoryFn({
+                    direction: 'pull', status: 'success', skipReason: 'unchanged',
+                    createdAt: nowIso, failureCountAtRun: 0,
+                });
+                await this.writeFinalConfig(cfg, result, nowIso, historyId);
+                return result;
+            }
+            // Phase B: 写入本地（applyMergePlan，无 review-queue 写）
+            const applyReport = await engine.applyMergePlan(apply);
+            const appliedSections = applyReport.applied;
+            if (!applyReport.ok) {
+                const error = applyReport.warnings.join('; ') || 'applyMergePlan 执行失败';
+                const result = {
+                    status: 'failed', direction: 'pull', error, historyId,
+                    consecutiveFailures: cfg.consecutiveFailures + 1,
+                };
+                await this.appendHistoryFn({
+                    direction: 'pull', status: 'failed', error, createdAt: nowIso,
+                    failureCountAtRun: cfg.consecutiveFailures + 1,
+                });
+                await this.writeFinalConfig(cfg, result, nowIso, historyId);
+                this.maybeNotify(cfg.consecutiveFailures + 1, historyId, nowIso);
+                return result;
+            }
+            // Phase C: push 上传（完整双向）
+            if (!opts.startup) {
+                try {
+                    const pushReport = await engine.push();
+                    if (!pushReport.ok) {
+                        const error = pushReport.message ?? 'push 失败';
+                        const result = {
+                            status: 'failed', direction: 'both', appliedSections, error, historyId,
+                            consecutiveFailures: cfg.consecutiveFailures + 1,
+                        };
+                        await this.appendHistoryFn({
+                            direction: 'both', status: 'failed', appliedSections, error,
+                            createdAt: nowIso, failureCountAtRun: cfg.consecutiveFailures + 1,
+                        });
+                        await this.writeFinalConfig(cfg, result, nowIso, historyId);
+                        this.maybeNotify(cfg.consecutiveFailures + 1, historyId, nowIso);
+                        return result;
+                    }
+                    const result = {
+                        status: 'success', direction: 'both', appliedSections,
+                        pushedSnapshotId: pushReport.snapshotId, historyId, consecutiveFailures: 0,
+                    };
+                    await this.appendHistoryFn({
+                        direction: 'both', status: 'success', appliedSections,
+                        pushedSnapshotId: pushReport.snapshotId, createdAt: nowIso, failureCountAtRun: 0,
+                    });
+                    await this.writeFinalConfig(cfg, result, nowIso, historyId);
+                    return result;
+                }
+                catch (err) {
+                    const error = err instanceof Error ? err.message : String(err);
+                    const result = {
+                        status: 'failed', direction: 'both', appliedSections, error, historyId,
+                        consecutiveFailures: cfg.consecutiveFailures + 1,
+                    };
+                    await this.appendHistoryFn({
+                        direction: 'both', status: 'failed', appliedSections, error,
+                        createdAt: nowIso, failureCountAtRun: cfg.consecutiveFailures + 1,
+                    });
+                    await this.writeFinalConfig(cfg, result, nowIso, historyId);
+                    this.maybeNotify(cfg.consecutiveFailures + 1, historyId, nowIso);
+                    return result;
+                }
+            }
+            // startup 变体：只做 pull 合并（不上传）
+            const result = {
+                status: 'success', direction: 'pull', appliedSections, historyId, consecutiveFailures: 0,
+            };
+            await this.appendHistoryFn({
+                direction: 'pull', status: 'success', appliedSections,
+                createdAt: nowIso, failureCountAtRun: 0,
+            });
+            await this.writeFinalConfig(cfg, result, nowIso, historyId);
+            return result;
+        }
+        catch (err) {
+            const error = err instanceof Error ? err.message : String(err);
+            const result = {
+                status: 'failed', direction: 'none', error, historyId,
+                consecutiveFailures: cfg.consecutiveFailures + 1,
+            };
+            await this.appendHistoryFn({
+                direction: 'both', status: 'failed', error,
+                createdAt: nowIso, failureCountAtRun: cfg.consecutiveFailures + 1,
+            });
+            await this.writeFinalConfig(cfg, result, nowIso, historyId);
+            this.maybeNotify(cfg.consecutiveFailures + 1, historyId, nowIso);
+            return result;
+        }
+        finally {
+            this.running = false;
+            if (runId !== null) {
+                // 完成标记（不抛错，尽力而为）
+            }
+        }
+    }
+    /** 收尾：写 autosync-config（lastRunAt, lastRunStatus, consecutiveFailures, lastRunHistoryId）。 */
+    async writeFinalConfig(base, result, nowIso, historyId) {
+        await this.writeConfig({
+            ...base,
+            lastRunAt: nowIso,
+            lastRunStatus: result.status,
+            consecutiveFailures: result.consecutiveFailures,
+            lastRunHistoryId: historyId,
+            ...(result.error !== undefined ? { lastRunMessage: result.error } : {}),
+        });
+    }
+    /** 连续失败 ≥ 3 → 通知（host.log.warn）。 */
+    maybeNotify(failures, historyId, nowIso) {
+        if (failures >= 3) {
+            this.host.log.warn(`自动同步连续失败 ${failures} 次，请检查仓库配置/凭据`);
+            // 记录 notifiedAt（更新历史 entry）
+            void this.readHistoryFn().then(async (hist) => {
+                const entry = hist.autosyncEntries.find((e) => e.createdAt === nowIso);
+                if (entry) {
+                    entry.notifiedAt = nowIso;
+                    await this.writeConfig({
+                        ...(await this.readConfig()),
+                        lastRunMessage: `连续失败 ${failures} 次，已通知`,
+                    });
+                }
+            }).catch(() => { });
+        }
+    }
+}
+/** 从 MergePlan 构造 SyncApplyPlan（autoApply = 所有非 skip 非 conflict 项）。 */
+export function buildAutoApplyPlan(plan) {
+    const autoApply = [];
+    const review = [];
+    const skipped = [];
+    for (const s of plan.sections) {
+        if (s.decision === 'skip') {
+            skipped.push(s);
+            continue;
+        }
+        if (s.decision === 'conflict') {
+            review.push(s);
+            continue;
+        }
+        // useRemote / keepLocal：都有 merged 数据
+        if (s.merged !== undefined) {
+            autoApply.push(s);
+        }
+        else {
+            skipped.push(s);
+        }
+    }
+    return { autoApply, review, skipped };
+}
+//# sourceMappingURL=autosync-scheduler.js.map

package/lib/sync/autosync-scheduler.js.map

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

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

@@ -1,11 +1,12 @@
 import { Importer } from '../core/importer.ts';
-import type { ConfigAdapter, GlobalConflictStrategy, HostContext, PlanItem, PlanItemKind, SecretScanner } from '../core/types.ts';
+import type { ConfigAdapter, GlobalConflictStrategy, HostContext, ImportAnalysis, ImportPlan, ImportResult, PlanItem, PlanItemKind, SecretScanner } from '../core/types.ts';
 import type { SectionId } from '../schema/types.ts';
 import type { SnapshotFs } from './fs.ts';
-import type { SyncSnapshot, SyncTransport } from './transport.ts';
+import type { SyncSnapshot, SyncSnapshotMeta, SyncTransport } from './transport.ts';
 import type { MsgFunc } from '../core/messages.ts';
 import type { MergePlan } from './merge.ts';
 import type { SyncApplyPlan } from './risk.ts';
+import type { PlanItemProgress } from '../core/analyzer.ts';
 export interface SyncEngineOptions {
     ctx: HostContext;
     transport: SyncTransport;
@@ -66,6 +67,16 @@ export interface SyncPullReport {
     needsReview: boolean;
     message?: string;
 }
+/** 一键同步预览结果（preview() 返回；临时 ZIP 由调用方持有并负责清理）。 */
+export interface SyncPreviewResult {
+    ok: boolean;
+    /** 临时标准 ZIP 路径（apply-items 复用 executeImportPlan 需要；调用方清理） */
+    zipPath: string;
+    plan: ImportPlan | null;
+    analysis: ImportAnalysis | null;
+    snapshotId: string;
+    message?: string;
+}
 /** 自动应用执行器（P2b）报告 */
 export interface ApplyReport {
     ok: boolean;
@@ -80,6 +91,26 @@ export interface ApplyReport {
     /** 来自 Importer.ImportResult 的 warnings；UI 可用于红条提示 */
     warnings: 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;
+}
 export declare class SyncEngine {
     private readonly ctx;
     private readonly transport;
@@ -111,6 +142,15 @@ export declare class SyncEngine {
      * 绝不直接写配置、绝不执行导入；执行由上层按用户确认后走 Importer.executeImportPlan。
      */
     pull(opts?: SyncPullOptions): Promise<SyncPullReport>;
+    /** 列出远端已有快照（按 createdAt 升序）—— 供「选择历史快照」下拉。 */
+    listSnapshots(): Promise<SyncSnapshotMeta[]>;
+    /**
+     * 一键同步预览：拉取远端（最新或指定历史快照）→ 转临时 ZIP → Importer 分析出计划。
+     * 与 pull 的区别：临时 ZIP **不清理**（由调用方 / 会话持有，供 apply-items 复用），
+     * 并返回完整 plan/analysis/snapshotId 供会话登记。
+     * 调用方负责在会话消费或取消后清理 zipPath 所在目录。
+     */
+    preview(opts?: SyncPullOptions): Promise<SyncPreviewResult>;
     merge(opts?: {
         snapshotId?: string;
     }): Promise<MergePlan>;
@@ -121,11 +161,26 @@ export declare class SyncEngine {
     recordBaseline(snapshotId: string, sections: SyncSnapshot['sections'], nowIso?: string): Promise<void>;
     /**
      * 应用自动应用计划：写本地（走 Importer.executeImportPlan 标准路径；应用前调 backup.createSnapshot 兜底）；
-     * 任一 auto 项失败 → 整体 rollback + 把全部 auto 项移到 review 队列（写回 sync-review-queue.json）；
-     * 成功后 recordBaseline 更新祖先基线。
+     * 任一 auto 项失败 → 整体 rollback；成功后 recordBaseline 更新祖先基线。
      * 返回 ApplyReport；不抛错到调用方（失败返回 ok:false + rolledBack:true）。
+     * 不再写 review-queue（§2.3/§7.4：待审语义改由同步历史 skipped 标记表达）。
      */
     applyMergePlan(apply: SyncApplyPlan): Promise<ApplyReport>;
+    /**
+     * applyItems：按用户对差异项的逐项决策执行导入（§3.4/§5.3）。
+     *
+     * 与 applyMergePlan 的区别：applyItems 接收「会话级临时 ZIP + 子计划」，
+     * 直接执行（backup.createSnapshot 兜底 → importer.executeImportPlan →
+     * 成功 recordBaseline / 失败 rollback），不构造中间 SyncApplyPlan。
+     *
+     * @param zipPath 会话级临时标准 ZIP（由 sync/sync 生成，包含采纳项的 merged 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;
+    }): Promise<ApplyItemsReport>;
     /** 散文件快照 → 标准导出 ZIP（临时目录，用完即删）：buildManifest + checksums + 平铺分区 */
     private snapshotToZip;
 }