@logictan/dsh-config-manager 0.1.60

package/src/sync/sync-history.test.ts

@@ -0,0 +1,116 @@
+/**
+ * sync-history 测试：自动同步执行记录读写（sync-history.json）、append 升序、
+ * 读不存在 → 空、损坏拒绝、裁剪 N 条。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import {
+  readSyncHistory, appendAutosyncEntry, SYNC_HISTORY_FILE,
+  AUTOSYNC_HISTORY_KEEP,
+} from './sync-history.ts';
+import type { AutosyncHistoryEntry } from './sync-history.ts';
+import type { SectionId } from '../schema/types.ts';
+
+function makeEntry(seed: number, status: AutosyncHistoryEntry['status']): AutosyncHistoryEntry {
+  return {
+    direction: 'both',
+    status,
+    appliedSections: (seed % 2 === 0 ? ['settings'] : []) as SectionId[],
+    createdAt: new Date(2026, 7, 16, 12, seed).toISOString(),
+    failureCountAtRun: 0,
+  };
+}
+
+test('appendAutosyncEntry：追加记录 → readSyncHistory 读回升序列表', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-history-append-'));
+  try {
+    await appendAutosyncEntry(dir, makeEntry(0, 'success'));
+    await appendAutosyncEntry(dir, makeEntry(1, 'skipped'));
+    const hist = await readSyncHistory(dir);
+    assert.equal(hist.schemaVersion, 1);
+    assert.equal(hist.autosyncEntries.length, 2);
+    assert.equal(hist.autosyncEntries[0]!.status, 'success');
+    assert.equal(hist.autosyncEntries[1]!.status, 'skipped');
+    // updatedAt 非空
+    assert.ok(hist.updatedAt !== '', 'updatedAt 已写入');
+  } finally { await fs.rm(dir, { recursive: true, force: true }); }
+});
+
+test('readSyncHistory：文件不存在 → 返回空列表（schemaVersion=1）', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-history-missing-'));
+  try {
+    const hist = await readSyncHistory(dir);
+    assert.equal(hist.schemaVersion, 1);
+    assert.deepEqual(hist.autosyncEntries, []);
+    assert.equal(hist.updatedAt, '');
+  } finally { await fs.rm(dir, { recursive: true, force: true }); }
+});
+
+test('readSyncHistory：损坏 JSON → 抛错', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-history-corrupt-'));
+  try {
+    await fs.writeFile(path.join(dir, SYNC_HISTORY_FILE), '{not-json', 'utf8');
+    await assert.rejects(() => readSyncHistory(dir), /损坏/);
+  } finally { await fs.rm(dir, { recursive: true, force: true }); }
+});
+
+test('appendAutosyncEntry：记录触发通道（transport git/webdav）→ 读回保留', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-history-channel-'));
+  try {
+    await appendAutosyncEntry(dir, { ...makeEntry(0, 'success'), transport: 'git' });
+    await appendAutosyncEntry(dir, { ...makeEntry(1, 'skipped'), transport: 'webdav' });
+    const hist = await readSyncHistory(dir);
+    assert.equal(hist.autosyncEntries[0]!.transport, 'git');
+    assert.equal(hist.autosyncEntries[1]!.transport, 'webdav');
+    // 旧记录（无字段）读回 → undefined（向后兼容）
+    const raw = await fs.readFile(path.join(dir, SYNC_HISTORY_FILE), 'utf8');
+    void raw;
+  } finally { await fs.rm(dir, { recursive: true, force: true }); }
+});
+
+test('readSyncHistory：旧记录无 transport 字段 → 读回 undefined（向后兼容）', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-history-legacy-'));
+  try {
+    await fs.writeFile(
+      path.join(dir, SYNC_HISTORY_FILE),
+      JSON.stringify({
+        schemaVersion: 1,
+        autosyncEntries: [{ direction: 'push', status: 'success', createdAt: '2026-08-16T12:00:00.000Z', failureCountAtRun: 0 }],
+        updatedAt: '2026-08-16T12:00:00.000Z',
+      }),
+      'utf8',
+    );
+    const hist = await readSyncHistory(dir);
+    assert.equal(hist.autosyncEntries[0]!.transport, undefined);
+  } finally { await fs.rm(dir, { recursive: true, force: true }); }
+});
+
+test('appendAutosyncEntry：裁剪到 AUTOSYNC_HISTORY_KEEP 条', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-history-prune-'));
+  try {
+    // 预置 250 条
+    for (let i = 0; i < AUTOSYNC_HISTORY_KEEP + 50; i++) {
+      await appendAutosyncEntry(dir, makeEntry(i, 'success'));
+    }
+    const hist = await readSyncHistory(dir);
+    assert.ok(hist.autosyncEntries.length <= AUTOSYNC_HISTORY_KEEP, `裁剪后不超过 ${AUTOSYNC_HISTORY_KEEP} 条`);
+    assert.equal(hist.autosyncEntries.length, AUTOSYNC_HISTORY_KEEP);
+    // 保留的是最新的（末尾的 createdAt 最大）
+    const first = hist.autosyncEntries[0]!;
+    const last = hist.autosyncEntries[hist.autosyncEntries.length - 1]!;
+    assert.ok(first.createdAt <= last.createdAt, '升序排列，最新的在末尾');
+  } finally { await fs.rm(dir, { recursive: true, force: true }); }
+});
+
+test('appendAutosyncEntry：原子写（不残留 .tmp 文件）', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-history-atomic-'));
+  try {
+    await appendAutosyncEntry(dir, makeEntry(0, 'failed'));
+    const files = await fs.readdir(dir);
+    assert.ok(!files.some((f) => f.includes('.tmp')), '不应残留 .tmp 临时文件');
+  } finally { await fs.rm(dir, { recursive: true, force: true }); }
+});

package/src/sync/sync-history.ts

@@ -0,0 +1,120 @@
+/**
+ * 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.ts';
+import { atomicWriteFile } from '../utils/atomic-write.ts';
+import type { SectionId } from '../schema/types.ts';
+import type { SyncTransportType } from './sync-config.ts';
+
+export const SYNC_HISTORY_FILE = 'sync-history.json';
+export const SYNC_HISTORY_SCHEMA_VERSION = 1;
+/** 自动同步历史保留上限 */
+export const AUTOSYNC_HISTORY_KEEP = 200;
+
+/** 自动同步执行记录（§3.7 AutosyncHistoryEntry） */
+export interface AutosyncHistoryEntry {
+  /** 触发该次运行的同步通道（git / webdav；旧记录缺省 undefined） */
+  transport?: SyncTransportType;
+  /** 执行方向 */
+  direction: 'pull' | 'push' | 'both';
+  status: 'success' | 'skipped' | 'failed' | 'partial';
+  /** 跳过原因（冲突项 / 缺失依赖 / Install / 错误 / 无远端 / 网络） */
+  skipReason?: string;
+  /** 被跳过的冲突分区 id（冲突跳过时列出） */
+  conflictedSections?: SectionId[];
+  /** 本次自动合并实际写入的分区 */
+  appliedSections?: SectionId[];
+  /** 本次 push 产生的快照 id（direction 含 push 时） */
+  pushedSnapshotId?: string;
+  /** 本次 pull 来源快照 id */
+  pulledSnapshotId?: string;
+  /** failed 时的错误摘要（脱敏） */
+  error?: string;
+  /** 连续失败 3 次通知时间（ISO-8601 UTC） */
+  notifiedAt?: string;
+  /** 本次触发时的连续失败计数 */
+  failureCountAtRun: number;
+  /** 记录创建时间（ISO-8601 UTC） */
+  createdAt: string;
+}
+
+/** sync-history.json 文件结构 */
+export interface SyncHistoryFile {
+  schemaVersion: number;
+  autosyncEntries: AutosyncHistoryEntry[];
+  updatedAt: string;
+}
+
+/** 读取同步历史；文件不存在 → 空列表（schemaVersion=1）。损坏 JSON 抛错。 */
+export async function readSyncHistory(dir: string): Promise<SyncHistoryFile> {
+  const file = path.join(dir, SYNC_HISTORY_FILE);
+  let raw: string;
+  try {
+    raw = await fs.readFile(file, 'utf8');
+  } catch {
+    return { schemaVersion: SYNC_HISTORY_SCHEMA_VERSION, autosyncEntries: [], updatedAt: '' };
+  }
+  let parsed: unknown;
+  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 as Record<string, unknown>;
+  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: AutosyncHistoryEntry[] = [];
+  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 as Record<string, unknown>;
+    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 as unknown as AutosyncHistoryEntry);
+  }
+  return {
+    schemaVersion: SYNC_HISTORY_SCHEMA_VERSION,
+    autosyncEntries: entries,
+    updatedAt: typeof obj['updatedAt'] === 'string' ? obj['updatedAt'] : '',
+  };
+}
+
+/** 追加一条自动同步执行记录（升序），裁剪到 AUTOSYNC_HISTORY_KEEP 条，原子写。 */
+export async function appendAutosyncEntry(
+  dir: string,
+  entry: AutosyncHistoryEntry,
+  now: () => Date = () => new Date(),
+): Promise<void> {
+  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 });
+}

package/src/sync/sync-selection.test.ts

@@ -0,0 +1,186 @@
+/**
+ * sync-selection 测试：sync-selection.json 读写往返、缺省值、损坏 JSON 回退缺省、
+ * 非字符串 sections 过滤、effectiveSections（高级模式 → 勾选分区；其余 → undefined）、
+ * 按通道独立（git/webdav 互不干扰）、v1（顶层单通道）迁移为 git。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import {
+  defaultSyncSelection, effectiveSections, readSyncSelection, writeSyncSelection,
+  readAllSyncSelections, SYNC_SELECTION_FILE, SYNC_SELECTION_SCHEMA_VERSION,
+} from './sync-selection.ts';
+
+test('writeSyncSelection + readSyncSelection：advanced 模式写入 → 读回字段一致（git 通道）', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-sync-selection-rt-'));
+  try {
+    await writeSyncSelection(dir, 'git', { schemaVersion: SYNC_SELECTION_SCHEMA_VERSION, mode: 'advanced', sections: ['settings', 'skills'] });
+    const sel = await readSyncSelection(dir, 'git');
+    assert.equal(sel.mode, 'advanced');
+    assert.deepEqual(sel.sections, ['settings', 'skills']);
+    // 原始文件校验（v2 按通道）
+    const raw = JSON.parse(await fs.readFile(path.join(dir, SYNC_SELECTION_FILE), 'utf8'));
+    assert.equal(raw.schemaVersion, SYNC_SELECTION_SCHEMA_VERSION);
+    assert.equal(raw.channels.git.mode, 'advanced');
+    assert.deepEqual(raw.channels.git.sections, ['settings', 'skills']);
+    assert.equal(raw.channels.webdav.mode, 'default', '未配置的 webdav 通道落盘为缺省');
+  } finally { await fs.rm(dir, { recursive: true, force: true }); }
+});
+
+test('readSyncSelection：文件不存在 → 返回缺省（default 模式 + 空 sections）', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-sync-selection-default-'));
+  try {
+    const sel = await readSyncSelection(dir, 'git');
+    assert.equal(sel.mode, 'default');
+    assert.deepEqual(sel.sections, []);
+    const webdav = await readSyncSelection(dir, 'webdav');
+    assert.equal(webdav.mode, 'default');
+  } finally { await fs.rm(dir, { recursive: true, force: true }); }
+});
+
+test('readSyncSelection：损坏 JSON → 回退缺省', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-sync-selection-corrupt-'));
+  try {
+    await fs.writeFile(path.join(dir, SYNC_SELECTION_FILE), '{not-json', 'utf8');
+    const sel = await readSyncSelection(dir, 'git');
+    assert.equal(sel.mode, 'default');
+    assert.deepEqual(sel.sections, []);
+  } finally { await fs.rm(dir, { recursive: true, force: true }); }
+});
+
+test('readSyncSelection：不支持的 schemaVersion → 回退缺省', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-sync-selection-schema-'));
+  try {
+    await fs.writeFile(
+      path.join(dir, SYNC_SELECTION_FILE),
+      JSON.stringify({ schemaVersion: 99, mode: 'advanced', sections: ['settings'] }),
+      'utf8',
+    );
+    const sel = await readSyncSelection(dir, 'git');
+    assert.equal(sel.mode, 'default');
+    assert.deepEqual(sel.sections, []);
+  } finally { await fs.rm(dir, { recursive: true, force: true }); }
+});
+
+test('readSyncSelection：非法 mode / 非字符串 sections 元素 → 过滤回退', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-sync-selection-filter-'));
+  try {
+    await fs.writeFile(
+      path.join(dir, SYNC_SELECTION_FILE),
+      JSON.stringify({ schemaVersion: 1, channels: { git: { mode: 'bogus', sections: ['settings', 42, '', 'skills'] } } }),
+      'utf8',
+    );
+    const sel = await readSyncSelection(dir, 'git');
+    assert.equal(sel.mode, 'default', '非法 mode 回退 default');
+    assert.deepEqual(sel.sections, ['settings', 'skills'], '非字符串/空串元素被过滤');
+  } finally { await fs.rm(dir, { recursive: true, force: true }); }
+});
+
+test('effectiveSections：advanced + 非空 → 勾选分区；default / advanced 空勾选 → undefined（全量）', () => {
+  assert.deepEqual(
+    effectiveSections({ schemaVersion: SYNC_SELECTION_SCHEMA_VERSION, mode: 'advanced', sections: ['settings', 'skills'] }),
+    ['settings', 'skills'],
+  );
+  assert.equal(effectiveSections(defaultSyncSelection()), undefined, 'default 模式 = 全量推荐分区');
+  assert.equal(
+    effectiveSections({ schemaVersion: SYNC_SELECTION_SCHEMA_VERSION, mode: 'advanced', sections: [] }),
+    undefined,
+    'advanced 但未勾选 → 回退全量（避免自动同步卡死）',
+  );
+});
+
+test('readSyncSelection：旧字段（encrypt/includeSecrets）被忽略，只读 mode + sections', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-sync-selection-safe-'));
+  try {
+    await fs.writeFile(
+      path.join(dir, SYNC_SELECTION_FILE),
+      JSON.stringify({ schemaVersion: 1, channels: { git: { mode: 'advanced', sections: ['settings'], encrypt: true, includeSecrets: true } } }),
+      'utf8',
+    );
+    const sel = await readSyncSelection(dir, 'git');
+    assert.equal(sel.mode, 'advanced');
+    assert.deepEqual(sel.sections, ['settings']);
+    assert.equal('encrypt' in sel, false, '旧字段不再出现在读取结果');
+    assert.equal('includeSecrets' in sel, false);
+  } finally { await fs.rm(dir, { recursive: true, force: true }); }
+});
+
+test('readSyncSelection：升级路径 —— 上游 v2 文件（含 encrypt/includeSecrets）→ 保留用户勾选', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-sync-selection-upstream-v2-'));
+  try {
+    // 逐字取自上游 dsh-config-manager@0.1.60 实际落盘的文件形状：
+    // 同一 channels 信封，多出 encrypt / includeSecrets 两个已废弃字段。
+    await fs.writeFile(
+      path.join(dir, SYNC_SELECTION_FILE),
+      JSON.stringify({
+        schemaVersion: 2,
+        channels: {
+          git: { mode: 'advanced', sections: ['settings', 'providers', 'prompts'], encrypt: true, includeSecrets: true },
+          webdav: { mode: 'advanced', sections: ['settings', 'skills'], encrypt: true, includeSecrets: true },
+        },
+      }),
+      'utf8',
+    );
+    const git = await readSyncSelection(dir, 'git');
+    assert.equal(git.mode, 'advanced', '上游 v2 的 git 勾选必须被保留，不得回退缺省');
+    assert.deepEqual(git.sections, ['settings', 'providers', 'prompts']);
+    assert.equal('encrypt' in git, false, '已废弃字段不进入读取结果');
+    assert.equal('includeSecrets' in git, false);
+    const webdav = await readSyncSelection(dir, 'webdav');
+    assert.equal(webdav.mode, 'advanced', '上游 v2 的 webdav 勾选必须被保留');
+    assert.deepEqual(webdav.sections, ['settings', 'skills']);
+  } finally { await fs.rm(dir, { recursive: true, force: true }); }
+});
+
+test('按通道独立：写 webdav 不影响 git，反之亦然', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-sync-selection-perchannel-'));
+  try {
+    await writeSyncSelection(dir, 'git', { schemaVersion: SYNC_SELECTION_SCHEMA_VERSION, mode: 'default', sections: [] });
+    await writeSyncSelection(dir, 'webdav', { schemaVersion: SYNC_SELECTION_SCHEMA_VERSION, mode: 'advanced', sections: ['settings', 'skills'] });
+    const git = await readSyncSelection(dir, 'git');
+    assert.equal(git.mode, 'default', 'git 通道保持 default');
+    const webdav = await readSyncSelection(dir, 'webdav');
+    assert.equal(webdav.mode, 'advanced');
+    assert.deepEqual(webdav.sections, ['settings', 'skills']);
+    // 全量读取视图
+    const all = await readAllSyncSelections(dir);
+    assert.equal(all.git.mode, 'default');
+    assert.equal(all.webdav.mode, 'advanced');
+  } finally { await fs.rm(dir, { recursive: true, force: true }); }
+});
+
+test('readSyncSelection：上游 v1 顶层单通道形状 → 归 git 通道，webdav 缺省', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-sync-selection-upstream-v1-'));
+  try {
+    // 上游 v1：整个文件就是一个通道配置，没有 channels 信封。
+    await fs.writeFile(
+      path.join(dir, SYNC_SELECTION_FILE),
+      JSON.stringify({ schemaVersion: 1, mode: 'advanced', sections: ['settings', 'mcp'] }),
+      'utf8',
+    );
+    const git = await readSyncSelection(dir, 'git');
+    assert.equal(git.mode, 'advanced');
+    assert.deepEqual(git.sections, ['settings', 'mcp']);
+    const webdav = await readSyncSelection(dir, 'webdav');
+    assert.equal(webdav.mode, 'default', 'v1 无 webdav 信息 → 缺省');
+  } finally { await fs.rm(dir, { recursive: true, force: true }); }
+});
+
+test('非 channels 形状（顶层单通道）→ 回退缺省（schemaVersion 不匹配）', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-sync-selection-v1-'));
+  try {
+    await fs.writeFile(
+      path.join(dir, SYNC_SELECTION_FILE),
+      JSON.stringify({ schemaVersion: 0, mode: 'advanced', sections: ['settings'] }),
+      'utf8',
+    );
+    const git = await readSyncSelection(dir, 'git');
+    assert.equal(git.mode, 'default', '不支持 schema → 回退缺省');
+    assert.deepEqual(git.sections, []);
+    const webdav = await readSyncSelection(dir, 'webdav');
+    assert.equal(webdav.mode, 'default', 'webdav 通道回退缺省');
+  } finally { await fs.rm(dir, { recursive: true, force: true }); }
+});

package/src/sync/sync-selection.ts

@@ -0,0 +1,143 @@
+/**
+ * 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 type { SectionId } from '../schema/types.ts';
+import type { SyncTransportType } from './sync-config.ts';
+import { parseJsonSafe, stringifyJsonSafe } from '../utils/json.ts';
+import { atomicWriteFile } from '../utils/atomic-write.ts';
+
+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: readonly number[] = [1, 2];
+
+/** 远程同步分区选择模式：default = 全部推荐分区；advanced = 自定义勾选。 */
+export type SyncSelectionMode = 'default' | 'advanced';
+
+/** 远程同步分区选择（持久化面；单通道）。 */
+export interface SyncSelection {
+  schemaVersion: number;
+  mode: SyncSelectionMode;
+  /** 高级模式勾选分区；default 模式可为空数组 */
+  sections: SectionId[];
+}
+
+/** 缺省配置（首次无文件 / 损坏 / 不支持 schema 时回退） */
+export function defaultSyncSelection(): SyncSelection {
+  return { schemaVersion: SYNC_SELECTION_SCHEMA_VERSION, mode: 'default', sections: [] };
+}
+
+/**
+ * 生效的同步分区范围：
+ * - mode='advanced' 且 sections 非空 → sections（自定义同步）；
+ * - 其余（default / advanced 但未勾选）→ undefined（= 全部推荐分区）。
+ */
+export function effectiveSections(sel: SyncSelection): SectionId[] | undefined {
+  if (sel.mode === 'advanced' && sel.sections.length > 0) return [...sel.sections];
+  return undefined;
+}
+
+/** 从单通道对象解析（非法字段回退缺省）。 */
+function parseChannelSelection(obj: Record<string, unknown>): SyncSelection {
+  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): s is SectionId => typeof s === 'string' && s !== '',
+    );
+  }
+  return sel;
+}
+
+/** 读取全部通道的分区选择配置；文件不存在 / 损坏 / 不支持 schema → 缺省值（不抛错）。 */
+export async function readAllSyncSelections(dir: string): Promise<Record<SyncTransportType, SyncSelection>> {
+  const fallback = (): Record<SyncTransportType, SyncSelection> => ({
+    git: defaultSyncSelection(),
+    webdav: defaultSyncSelection(),
+  });
+  const file = path.join(dir, SYNC_SELECTION_FILE);
+  let raw: string;
+  try {
+    raw = await fs.readFile(file, 'utf8');
+  } catch {
+    return fallback();
+  }
+  let parsed: unknown;
+  try {
+    parsed = parseJsonSafe(raw);
+  } catch {
+    return fallback();
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return fallback();
+  const obj = parsed as Record<string, unknown>;
+  // 缺 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 as Record<string, unknown>;
+  const pick = (ns: unknown): SyncSelection =>
+    ns !== null && typeof ns === 'object' && !Array.isArray(ns)
+      ? parseChannelSelection(ns as Record<string, unknown>)
+      : defaultSyncSelection();
+  return { git: pick(ch['git']), webdav: pick(ch['webdav']) };
+}
+
+/** 读取指定通道的分区选择配置；文件不存在 / 损坏 / 不支持 schema → 缺省值（不抛错）。 */
+export async function readSyncSelection(dir: string, channel: SyncTransportType): Promise<SyncSelection> {
+  const all = await readAllSyncSelections(dir);
+  return all[channel];
+}
+
+/** 写入指定通道的分区选择配置（原子写：临时文件 + rename；保留另一通道；自动创建目录）。 */
+export async function writeSyncSelection(dir: string, channel: SyncTransportType, sel: SyncSelection): Promise<void> {
+  await fs.mkdir(dir, { recursive: true });
+  const existing = await readAllSyncSelections(dir);
+  const channels: Record<SyncTransportType, SyncSelection> = {
+    git: channel === 'git' ? sel : existing.git,
+    webdav: channel === 'webdav' ? sel : existing.webdav,
+  };
+  const payload: Record<string, unknown> = {
+    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 });
+}