@logictan/dsh-config-manager 0.1.60

package/lib/security/zip-security.js

@@ -0,0 +1,154 @@
+/**
+ * ZIP 解压安全（规范 §19 / 设计 §9 / core utils/zip.ts 的强化层）。
+ *
+ * 分工（避免与 core 重复）：
+ * - core `utils/zip.ts` 已实现：条目名 isPathSafe、条目数/压缩体积/解压体积/单条/压缩比限额、
+ *   CRC32 与尺寸校验、ZipArchive.readEntry 预算、safeExtract 基础解压。
+ * - 本模块在其上强化 core 未覆盖的攻击面：
+ *   1. **symlink 条目拒绝**：解析中央目录 external attrs 的 Unix mode（S_IFLNK 0xA000）→ 拒绝；
+ *   2. **重复条目名拒绝**：同名条目（含目录/文件互撞）→ 拒绝（防读取歧义攻击）；
+ *   3. **安全解压强化**：解压后逐条 lstat 复查「必须是普通文件」，任何异常 → 中止并**完整清理**目标目录；
+ *   4. **可执行文件告警**：扩展名黑名单 → warnings（本插件从不执行 ZIP 内文件）。
+ *
+ * 与 core 注入点对齐：`parseZipHardened` / `createHardenedZipParser` 满足
+ * `ImporterOptions.parseZipOverride` 签名 `(buf, limits?) => ZipArchive`。
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { isPathSafe, isSameOrChild } from '../utils/paths.js';
+import { DEFAULT_ZIP_SAFETY_LIMITS, ZipArchive, ZipSafetyError, } from '../utils/zip.js';
+export { isPathSafe } from '../utils/paths.js';
+/* ---------------- 常量 ---------------- */
+const EOCD_SIG = Buffer.from([0x50, 0x4b, 0x05, 0x06]);
+const CENTRAL_SIG = 0x02014b50;
+/** Unix 文件类型掩码（external attrs 高 16 位） */
+const S_IFMT = 0xf000;
+/** 符号链接 */
+const S_IFLNK = 0xa000;
+/** 可执行文件扩展名黑名单（§19.6：只警告，本插件不执行任何脚本） */
+export const EXECUTABLE_EXTENSIONS = new Set([
+    '.exe', '.bat', '.cmd', '.sh', '.ps1', '.dll', '.so', '.dylib', '.bin', '.jar',
+]);
+/** 条目名是否疑似可执行文件（按扩展名） */
+export function isExecutableName(name) {
+    const ext = name.slice(name.lastIndexOf('.')).toLowerCase();
+    return EXECUTABLE_EXTENSIONS.has(ext);
+}
+/* ---------------- 强化解析（parseZipOverride 注入点） ---------------- */
+/**
+ * 强化版 ZIP 解析：在 core 全部安全校验（条目名/条目数/压缩体积）之上，
+ * 增加 symlink 拒绝与重复条目名拒绝。返回 core `ZipArchive`（解压校验完全复用）。
+ */
+export function parseZipHardened(buf, limits = {}) {
+    const merged = { ...DEFAULT_ZIP_SAFETY_LIMITS, ...limits };
+    const b = Buffer.isBuffer(buf) ? buf : Buffer.from(buf);
+    if (b.length < 22)
+        throw new ZipSafetyError('不是合法的 ZIP 文件（体积过小）');
+    const eocdIdx = b.lastIndexOf(EOCD_SIG);
+    if (eocdIdx < 0 || eocdIdx + 22 > b.length) {
+        throw new ZipSafetyError('不是合法的 ZIP 文件（缺少中央目录结束记录）');
+    }
+    const totalEntries = b.readUInt16LE(eocdIdx + 10);
+    const cdSize = b.readUInt32LE(eocdIdx + 12);
+    const cdOffset = b.readUInt32LE(eocdIdx + 16);
+    if (cdOffset + cdSize > b.length)
+        throw new ZipSafetyError('中央目录越界（ZIP 损坏）');
+    if (totalEntries > merged.maxEntries) {
+        throw new ZipSafetyError(`ZIP 条目数 ${totalEntries} 超过上限 ${merged.maxEntries}`);
+    }
+    const metas = [];
+    const seenNames = new Set();
+    let pos = cdOffset;
+    let compressedTotal = 0;
+    for (let i = 0; i < totalEntries; i++) {
+        if (pos + 46 > cdOffset + cdSize)
+            throw new ZipSafetyError('中央目录条目越界（ZIP 损坏）');
+        if (b.readUInt32LE(pos) !== CENTRAL_SIG)
+            throw new ZipSafetyError('中央目录签名损坏');
+        const method = b.readUInt16LE(pos + 10);
+        const crc = b.readUInt32LE(pos + 16);
+        const compSize = b.readUInt32LE(pos + 20);
+        const uncompSize = b.readUInt32LE(pos + 24);
+        const nameLen = b.readUInt16LE(pos + 28);
+        const extraLen = b.readUInt16LE(pos + 30);
+        const commentLen = b.readUInt16LE(pos + 32);
+        const externalAttrs = b.readUInt32LE(pos + 38);
+        const localOffset = b.readUInt32LE(pos + 42);
+        const name = b.subarray(pos + 46, pos + 46 + nameLen).toString('utf8');
+        // —— 强化检查 ——
+        if (!isPathSafe(name))
+            throw new ZipSafetyError(`ZIP 条目名不安全: ${name}`);
+        if (seenNames.has(name))
+            throw new ZipSafetyError(`ZIP 条目名重复: ${name}`);
+        seenNames.add(name);
+        const mode = (externalAttrs >>> 16) & S_IFMT;
+        if (mode === S_IFLNK) {
+            throw new ZipSafetyError(`ZIP 含符号链接条目，已拒绝: ${name}`);
+        }
+        if (localOffset + 30 > b.length) {
+            throw new ZipSafetyError(`条目 "${name}" 本地文件头越界`);
+        }
+        compressedTotal += compSize;
+        if (compressedTotal > merged.maxCompressedBytes) {
+            throw new ZipSafetyError('ZIP 压缩数据总量超过上限');
+        }
+        metas.push({
+            name,
+            method,
+            compressedSize: compSize,
+            uncompressedSize: uncompSize,
+            crc32: crc,
+            isDirectory: name.endsWith('/'),
+            localOffset,
+        });
+        pos += 46 + nameLen + extraLen + commentLen;
+    }
+    return new ZipArchive(b, metas, merged);
+}
+/** 工厂：带默认限额的强化解析器（对齐 ImporterOptions.parseZipOverride 签名） */
+export function createHardenedZipParser(defaultLimits) {
+    return (buf, limits) => parseZipHardened(buf, { ...defaultLimits, ...limits });
+}
+/**
+ * 安全解压到受控目录（对齐 core safeExtract 语义 + 强化）：
+ *  - 条目名/限额/symlink/重复名检查（parseZipHardened）；
+ *  - 逐条 CRC32/尺寸/预算校验（ZipArchive.readEntry）；
+ *  - 解压后 lstat 复查「全部产物必须是普通文件」（防符号链接/非常规写入）；
+ *  - 任何异常 → 中止并**完整清理** destDir 后抛出（不残留部分落盘）。
+ */
+export async function safeExtractHardened(zipPath, destDir, limits = {}) {
+    const data = await fs.readFile(zipPath);
+    const archive = parseZipHardened(data, limits);
+    const extracted = [];
+    const warnings = [];
+    try {
+        for (const meta of archive.entries()) {
+            if (meta.isDirectory)
+                continue;
+            const target = path.join(destDir, ...meta.name.split('/'));
+            if (!isSameOrChild(target, destDir)) {
+                throw new ZipSafetyError(`解压目标越界: ${meta.name}`);
+            }
+            await fs.mkdir(path.dirname(target), { recursive: true });
+            await fs.writeFile(target, archive.readEntry(meta.name));
+            extracted.push(meta.name);
+            if (isExecutableName(meta.name)) {
+                warnings.push(`条目 "${meta.name}" 是潜在可执行文件，本插件不会执行它`);
+            }
+        }
+        // 解压后复查：全部产物必须是普通文件（防 symlink 逃逸 / 非常规写入）
+        for (const rel of extracted) {
+            const p = path.join(destDir, ...rel.split('/'));
+            const st = await fs.lstat(p);
+            if (!st.isFile()) {
+                throw new ZipSafetyError(`解压产物不是普通文件: ${rel}`);
+            }
+        }
+        return { files: extracted, warnings };
+    }
+    catch (err) {
+        await fs.rm(destDir, { recursive: true, force: true });
+        throw err;
+    }
+}
+//# sourceMappingURL=zip-security.js.map

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

@@ -0,0 +1,39 @@
+import type { SyncTransportType } from './sync-config.ts';
+export declare const AUTOSYNC_CONFIG_FILE = "sync-autosync.json";
+export declare const AUTOSYNC_CONFIG_SCHEMA_VERSION = 2;
+/** 统一间隔类型 */
+export type AutosyncInterval = '5m' | '15m' | '30m' | '60m' | '6h' | '12h' | '24h';
+/** 缺省间隔 */
+export declare const DEFAULT_AUTOSYNC_INTERVAL: AutosyncInterval;
+/** 缺省启动触发最小间隔阈值（5 分钟，防频繁重启反复同步） */
+export declare const DEFAULT_STARTUP_MIN_INTERVAL_MS: number;
+/** 最近一次自动同步执行状态 */
+export type AutosyncRunStatus = 'success' | 'skipped' | 'failed' | 'partial';
+/** 自动同步配置（持久化面；单通道） */
+export interface AutosyncConfig {
+    /** 总开关（同时控制上传 + 下载） */
+    enabled: boolean;
+    /** 统一间隔 */
+    interval: AutosyncInterval;
+    /** 重启触发的「自动下载合并」最小间隔阈值（ms） */
+    startupMinIntervalMs: number;
+    /** 连续失败计数（用于通知判定） */
+    consecutiveFailures: number;
+    /** 最近一次自动同步执行时间（ISO-8601 UTC）；''/undefined = 从未执行 */
+    lastRunAt?: string;
+    /** 最近一次自动同步执行状态 */
+    lastRunStatus?: AutosyncRunStatus;
+    lastRunMessage?: string;
+    /** 最近一次自动同步触发的同步历史条目 id */
+    lastRunHistoryId?: string;
+}
+/** 全通道配置视图（v2 文件直接读取；status 路由一次返回两个通道的状态）。 */
+export type AutosyncConfigByChannel = Record<SyncTransportType, AutosyncConfig>;
+/** 缺省配置（首次无文件 / 损坏 / 不支持 schema 时回退） */
+export declare function defaultAutosyncConfig(): AutosyncConfig;
+/** 读取全部通道的自动同步配置（v2 文件；v1 迁移为 git；webdav 缺省）。 */
+export declare function readAllAutosyncConfigs(dir: string): Promise<AutosyncConfigByChannel>;
+/** 读取指定通道的自动同步配置；文件不存在 / 损坏 / 不支持 schema → 缺省值（不抛错）。 */
+export declare function readAutosyncConfig(dir: string, channel: SyncTransportType): Promise<AutosyncConfig>;
+/** 写入指定通道的自动同步配置（原子写：临时文件 + rename；保留另一通道；自动创建目录）。 */
+export declare function writeAutosyncConfig(dir: string, channel: SyncTransportType, cfg: AutosyncConfig): Promise<void>;

package/lib/sync/autosync-config.js

@@ -0,0 +1,151 @@
+/**
+ * m-autosync：自动同步配置持久化（sync-autosync.json）。
+ *
+ * 与 sync-config.json 并列独立文件：语义清楚、schema 演进独立。
+ * schemaVersion:2 —— 按同步通道拆分（git / webdav 各自独立的自动同步配置与运行状态）：
+ * ```
+ * { "schemaVersion": 2,
+ *   "channels": {
+ *     "git":    { enabled, interval, startupMinIntervalMs, consecutiveFailures, lastRunAt, ... },
+ *     "webdav": { ... } } }
+ * ```
+ * v1（顶层单通道）→ 读取时归一为 v2 的 git 通道（webdav 回退缺省）。
+ *
+ * 原子写（临时文件 + rename），损坏/不支持 schema 回退缺省（enabled=false,
+ * interval='30m', startupMinIntervalMs=5*60*1000）。
+ */
+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 AUTOSYNC_CONFIG_FILE = 'sync-autosync.json';
+export const AUTOSYNC_CONFIG_SCHEMA_VERSION = 2;
+/** 缺省间隔 */
+export const DEFAULT_AUTOSYNC_INTERVAL = '30m';
+/** 缺省启动触发最小间隔阈值（5 分钟，防频繁重启反复同步） */
+export const DEFAULT_STARTUP_MIN_INTERVAL_MS = 5 * 60 * 1000;
+/** 缺省配置（首次无文件 / 损坏 / 不支持 schema 时回退） */
+export function defaultAutosyncConfig() {
+    return {
+        enabled: false,
+        interval: DEFAULT_AUTOSYNC_INTERVAL,
+        startupMinIntervalMs: DEFAULT_STARTUP_MIN_INTERVAL_MS,
+        consecutiveFailures: 0,
+    };
+}
+/** 从 v1 顶层字段（缺 schemaVersion 或 schemaVersion=1）解析单通道配置；非法字段回退缺省。 */
+function parseV1Channel(obj) {
+    const cfg = defaultAutosyncConfig();
+    if (typeof obj['enabled'] === 'boolean')
+        cfg.enabled = obj['enabled'];
+    if (isAutosyncInterval(obj['interval']))
+        cfg.interval = obj['interval'];
+    if (typeof obj['startupMinIntervalMs'] === 'number' && Number.isFinite(obj['startupMinIntervalMs']) && obj['startupMinIntervalMs'] > 0) {
+        cfg.startupMinIntervalMs = obj['startupMinIntervalMs'];
+    }
+    if (typeof obj['consecutiveFailures'] === 'number' && Number.isFinite(obj['consecutiveFailures']) && obj['consecutiveFailures'] >= 0) {
+        cfg.consecutiveFailures = obj['consecutiveFailures'];
+    }
+    if (typeof obj['lastRunAt'] === 'string' && obj['lastRunAt'] !== '')
+        cfg.lastRunAt = obj['lastRunAt'];
+    if (typeof obj['lastRunStatus'] === 'string' && (obj['lastRunStatus'] === 'success' || obj['lastRunStatus'] === 'skipped' || obj['lastRunStatus'] === 'failed' || obj['lastRunStatus'] === 'partial')) {
+        cfg.lastRunStatus = obj['lastRunStatus'];
+    }
+    if (typeof obj['lastRunMessage'] === 'string')
+        cfg.lastRunMessage = obj['lastRunMessage'];
+    if (typeof obj['lastRunHistoryId'] === 'string')
+        cfg.lastRunHistoryId = obj['lastRunHistoryId'];
+    return cfg;
+}
+/** 从 v2 channels 命名空间解析单通道配置；缺失/非法 → 缺省。 */
+function parseV2Channel(ns) {
+    if (ns === null || typeof ns !== 'object' || Array.isArray(ns))
+        return defaultAutosyncConfig();
+    return parseV1Channel(ns);
+}
+/** 读取全部通道的自动同步配置（v2 文件；v1 迁移为 git；webdav 缺省）。 */
+export async function readAllAutosyncConfigs(dir) {
+    const file = path.join(dir, AUTOSYNC_CONFIG_FILE);
+    let raw;
+    try {
+        raw = await fs.readFile(file, 'utf8');
+    }
+    catch {
+        return { git: defaultAutosyncConfig(), webdav: defaultAutosyncConfig() };
+    }
+    let parsed;
+    try {
+        parsed = parseJsonSafe(raw);
+    }
+    catch {
+        return { git: defaultAutosyncConfig(), webdav: defaultAutosyncConfig() };
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return { git: defaultAutosyncConfig(), webdav: defaultAutosyncConfig() };
+    }
+    const obj = parsed;
+    // schemaVersion：缺省视为 v1；非缺省但 != 2 → 回退缺省
+    const ver = typeof obj['schemaVersion'] === 'number' ? obj['schemaVersion'] : 1;
+    if (ver !== 1 && ver !== AUTOSYNC_CONFIG_SCHEMA_VERSION) {
+        return { git: defaultAutosyncConfig(), webdav: defaultAutosyncConfig() };
+    }
+    if (ver === 1) {
+        // v1 迁移：顶层字段 → git 通道（webdav 缺省；首次按 v2 写回时持久化）
+        return { git: parseV1Channel(obj), webdav: defaultAutosyncConfig() };
+    }
+    const channels = obj['channels'];
+    const ch = channels !== null && typeof channels === 'object' && !Array.isArray(channels)
+        ? channels
+        : {};
+    return {
+        git: parseV2Channel(ch['git']),
+        webdav: parseV2Channel(ch['webdav']),
+    };
+}
+/** 读取指定通道的自动同步配置；文件不存在 / 损坏 / 不支持 schema → 缺省值（不抛错）。 */
+export async function readAutosyncConfig(dir, channel) {
+    const all = await readAllAutosyncConfigs(dir);
+    return all[channel];
+}
+/** 写入指定通道的自动同步配置（原子写：临时文件 + rename；保留另一通道；自动创建目录）。 */
+export async function writeAutosyncConfig(dir, channel, cfg) {
+    await fs.mkdir(dir, { recursive: true });
+    const existing = await readAllAutosyncConfigs(dir);
+    const channels = {
+        git: channel === 'git' ? cfg : existing.git,
+        webdav: channel === 'webdav' ? cfg : existing.webdav,
+    };
+    const payload = {
+        schemaVersion: AUTOSYNC_CONFIG_SCHEMA_VERSION,
+        channels: {
+            git: toChannelPayload(channels.git),
+            webdav: toChannelPayload(channels.webdav),
+        },
+    };
+    const target = path.join(dir, AUTOSYNC_CONFIG_FILE);
+    const data = stringifyJsonSafe(payload, { space: 2 });
+    await atomicWriteFile(target, data, { mode: 0o600 });
+}
+/** AutosyncConfig → 文件载荷（可选运行字段仅在非空时写入，保持文件干净）。 */
+function toChannelPayload(cfg) {
+    const payload = {
+        enabled: cfg.enabled,
+        interval: cfg.interval,
+        startupMinIntervalMs: cfg.startupMinIntervalMs,
+        consecutiveFailures: cfg.consecutiveFailures,
+    };
+    if (cfg.lastRunAt !== undefined && cfg.lastRunAt !== '')
+        payload['lastRunAt'] = cfg.lastRunAt;
+    if (cfg.lastRunStatus !== undefined)
+        payload['lastRunStatus'] = cfg.lastRunStatus;
+    if (cfg.lastRunMessage !== undefined && cfg.lastRunMessage !== '')
+        payload['lastRunMessage'] = cfg.lastRunMessage;
+    if (cfg.lastRunHistoryId !== undefined && cfg.lastRunHistoryId !== '')
+        payload['lastRunHistoryId'] = cfg.lastRunHistoryId;
+    return payload;
+}
+function isAutosyncInterval(v) {
+    return v === '5m' || v === '15m' || v === '30m' || v === '60m' || v === '6h' || v === '12h' || v === '24h';
+}
+//# sourceMappingURL=autosync-config.js.map

package/lib/sync/autosync-scheduler.d.ts

@@ -0,0 +1,139 @@
+import type { Logger } from '../utils/logger.ts';
+import type { MsgFunc } from '../core/messages.ts';
+import type { SectionId } from '../schema/types.ts';
+import type { RunRegistry } from '../core/run-registry.ts';
+import type { SyncEngine } from './sync-engine.ts';
+import type { MutationLockPort, MutationLockContext } from '../utils/env-lock.ts';
+import type { AutosyncConfig, AutosyncInterval } from './autosync-config.ts';
+import type { SyncConfig, SyncTransportType } from './sync-config.ts';
+import { readSyncHistory } from './sync-history.ts';
+import type { AutosyncHistoryEntry } from './sync-history.ts';
+/** 间隔 → ms 换算（§4.3） */
+export declare function intervalToMs(interval: AutosyncInterval): number;
+/**
+ * 启动触发下载合并且满足阈值（now - lastRunAt >= startupMinIntervalMs）？
+ * lastRunAt 为 undefined（从未运行）→ true。
+ */
+export declare function shouldTriggerStartupRun(lastRunAt: string | undefined, startupMinIntervalMs: number, nowMs?: number): boolean;
+/** runOnce 执行结果 */
+export interface AutosyncRunResult {
+    status: 'success' | 'skipped' | 'failed' | 'partial';
+    direction: 'pull' | 'push' | 'both' | 'none';
+    skipReason?: string;
+    conflictedSections?: SectionId[];
+    appliedSections?: SectionId[];
+    pushedSnapshotId?: string;
+    pulledSnapshotId?: string;
+    error?: string;
+    historyId: string;
+    consecutiveFailures: number;
+}
+export interface AutoSyncSchedulerOptions {
+    syncDir: string;
+    host: {
+        log: Logger;
+    };
+    /** 注入 SyncEngine 构造器：按 SyncConfig 构造对应通道的引擎（git/webdav）。 */
+    makeSyncEngine: (cfg: SyncConfig) => SyncEngine;
+    /** 消息翻译器 */
+    msg: MsgFunc;
+    runs: RunRegistry;
+    /** 时间源（测试注入） */
+    now?: () => Date;
+    /** 注入 autosync-config 读写（按通道；测试可内存实现） */
+    readConfig?: (channel: SyncTransportType) => Promise<AutosyncConfig>;
+    writeConfig?: (channel: SyncTransportType, cfg: AutosyncConfig) => Promise<void>;
+    /** 注入 sync-config 读取（按通道） */
+    readSyncConfigFn?: (channel: SyncTransportType) => Promise<SyncConfig | null>;
+    /** 注入 sync-history 读写 */
+    readHistoryFn?: () => Promise<Awaited<ReturnType<typeof readSyncHistory>>>;
+    appendHistoryFn?: (entry: AutosyncHistoryEntry) => Promise<void>;
+    /** 注入计时器（测试用；缺省 setInterval/clearInterval） */
+    setTimer?: (fn: () => void, ms: number) => ReturnType<typeof setTimeout>;
+    clearTimer?: (timer: ReturnType<typeof setTimeout>) => void;
+    /**
+     * 远端新快照检测（§3.2「下载=检测到远端新快照才拉取」）。
+     * 缺省：若 engine 实现了 hasNewRemoteSnapshot() 则调用；否则视为 true（保持旧行为=每次拉取）。
+     */
+    detectRemoteNew?: (engine: SyncEngine) => Promise<boolean>;
+    /**
+     * 本地配置变化检测（§3.1「上传=本地改动才推」）。
+     * 缺省：若 engine 实现了 hasLocalChanges() 则调用；否则视为 true（保持旧行为=每次都推）。
+     */
+    detectLocalChange?: (engine: SyncEngine) => Promise<boolean>;
+    /** Phase 2 跨进程环境锁端口（可选注入；缺省无锁环境——自动同步 apply（写本地配置）属 GLOBAL mutation） */
+    mutationLock?: MutationLockPort;
+    /** Phase 3 SAFE MODE：注入同步谓词（被挡 → autosync skip），供 withMutationLock isBlocked 用。 */
+    isBlocked?: () => boolean;
+    /** Phase 3 recovery（可选注入）：apply/push 包 intent journal（P0-A 接线）。 */
+    phase3Recovery?: {
+        runExternalIntent(opts: {
+            operationType: string;
+            lockCtx: MutationLockContext;
+            intent: {
+                adapter: string;
+                ref: string;
+                kind: string;
+            };
+            fn: () => Promise<unknown>;
+        }): Promise<{
+            operationId: string;
+            result: unknown;
+        }>;
+    };
+}
+export declare class AutoSyncScheduler {
+    private readonly syncDir;
+    private readonly host;
+    private readonly makeSyncEngine;
+    private readonly msg;
+    private readonly runs;
+    private readonly now;
+    private readonly readConfig;
+    private readonly writeConfig;
+    private readonly readSyncConfigFn;
+    private readonly readHistoryFn;
+    private readonly appendHistoryFn;
+    private readonly setTimer;
+    private readonly clearTimer;
+    private readonly detectRemoteNew;
+    private readonly detectLocalChange;
+    private readonly mutationLock;
+    private readonly isBlocked;
+    private readonly phase3Recovery;
+    /** 本次 runOnce 由 withMutationLock 取得的下游锁上下文（供 apply/push journal-wrap），非线程级。 */
+    private lockCtxForJournal;
+    /** 每通道一个定时器（git/webdav 各自 enabled 时独立排期）。 */
+    private readonly timers;
+    private stopped;
+    private running;
+    constructor(opts: AutoSyncSchedulerOptions);
+    /** 追加一条自动同步历史（自动带上触发通道；0x 安全：绝不覆盖调用方显式 transport）。 */
+    private appendHistory;
+    /** 启动：读两个通道配置 → enabled 通道各自排定时器 → 对每个 enabled 通道执行一次启动触发。 */
+    start(): void;
+    /** 停止：清全部定时器、标记不再调度；正在执行的任务允许自然结束。 */
+    stop(): void;
+    /** 重新加载配置（路由 POST /sync/autosync 后调用；重排所有通道定时器）。 */
+    reload(): Promise<void>;
+    private refreshTimers;
+    /** 启动触发下载合并（每个 enabled 通道；受各自 startupMinIntervalMs 阈值约束）。 */
+    private startupRuns;
+    /**
+     * 执行一次指定通道的自动同步（§6.1）。
+     * @param channel - 同步通道（git / webdav；各自独立的配置与运行状态）
+     * @param opts.startup - true 表示启动触发变体（只做 Phase A+B，不做 Phase C push）
+     */
+    runOnce(channel: SyncTransportType, opts?: {
+        startup?: boolean;
+    }): Promise<AutosyncRunResult>;
+    /** 收尾：写该通道 autosync-config（lastRunAt, lastRunStatus, consecutiveFailures, lastRunHistoryId）。 */
+    private writeFinalConfig;
+    /** 连续失败 ≥ 3 → 通知（host.log.warn）。 */
+    private maybeNotify;
+}
+/**
+ * 同步通道是否「已配置」：git 看 git.repoUrl 非空；webdav 看 webdav.url 非空；
+ * 未配置（null / 缺字段）→ false。作为 autosync 未配置跳过的判定依据。
+ */
+export declare function syncIsConfigured(cfg: SyncConfig | null): boolean;