@logictan/dsh-config-manager 0.1.60

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

@@ -0,0 +1,143 @@
+/**
+ * SyncSessionStore 测试：内存登记临时 ZIP + ImportPlan，TTL 30 分钟，惰性清理，同 id 覆盖。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import crypto from 'node:crypto';
+
+import { SyncSessionStore } from './sync-session.ts';
+import type { SyncConfig } from './sync-config.ts';
+import type { ImportAnalysis, ImportPlan } from '../core/types.ts';
+import type { SectionId } from '../schema/types.ts';
+
+const GIT_CONFIG: SyncConfig = { schemaVersion: 2, transport: 'git', git: { repoUrl: 'https://github.com/foo/bar.git' } };
+
+const DEFAULT_TTL_MS = 30 * 60 * 1000;
+
+function makePlan(seed: string): ImportPlan {
+  return {
+    items: [{ id: `item-${seed}`, kind: 'Update', adapter: 'settings', description: `desc-${seed}`, severity: 'info', target: { adapter: 'settings', ref: 'general' } }],
+    globalStrategy: 'merge',
+    pathMappings: [],
+    missingSecrets: [],
+    needsRestart: false,
+    estimatedActions: { settings: 1 } as unknown as Record<SectionId, number>,
+  };
+}
+
+function makeAnalysis(seed: string): ImportAnalysis {
+  return {
+    valid: true,
+    errors: [],
+    warnings: [],
+    compatibility: 'excellent',
+    sectionsInZip: ['settings'] as SectionId[],
+    unsupportedSections: [],
+    unsupportedVersions: [],
+    pluginSummary: { installed: 0, toInstall: 0 },
+    pathIssues: [],
+    secretCount: 0,
+    dependencyIssues: [],
+    encrypted: false,
+  };
+}
+
+function makeSession(store: SyncSessionStore, opts: { seed: string; nowMs?: number }): string {
+  const now = opts.nowMs ?? Date.now();
+  const id = crypto.randomUUID();
+  store.set({
+    id,
+    zipPath: `/tmp/session-${opts.seed}.zip`,
+    plan: makePlan(opts.seed),
+    analysis: makeAnalysis(opts.seed),
+    snapshotId: `snap-${opts.seed}`,
+    config: GIT_CONFIG,
+    createdAt: now,
+    expiresAt: now + DEFAULT_TTL_MS,
+  });
+  return id;
+}
+
+test('SyncSessionStore: set/get 往返；同 id 覆盖', () => {
+  const store = new SyncSessionStore({ now: () => 5_000_000 });
+  const id = makeSession(store, { seed: 'a', nowMs: 5_000_000 });
+  const s1 = store.get(id);
+  assert.ok(s1, 'get 应返回 session');
+  assert.equal(s1!.zipPath, '/tmp/session-a.zip');
+  assert.equal(s1!.plan.items[0]!.id, 'item-a');
+  assert.equal(s1!.snapshotId, 'snap-a');
+
+  // 同 id 覆盖（仍在有效期内）
+  store.set({
+    id,
+    zipPath: '/tmp/session-b.zip',
+    plan: makePlan('b'),
+    analysis: makeAnalysis('b'),
+    snapshotId: 'snap-b',
+    config: GIT_CONFIG,
+    createdAt: 5_000_000,
+    expiresAt: 5_000_000 + DEFAULT_TTL_MS,
+  });
+  const s2 = store.get(id);
+  assert.equal(s2!.zipPath, '/tmp/session-b.zip');
+  assert.equal(s2!.plan.items[0]!.id, 'item-b');
+  assert.equal(s2!.snapshotId, 'snap-b');
+});
+
+test('SyncSessionStore: get 过期条目 → undefined（惰性清理）', () => {
+  const store = new SyncSessionStore();
+  const now = 1_000_000;
+  const id = crypto.randomUUID();
+  store.set({
+    id,
+    zipPath: '/tmp/expired.zip',
+    plan: makePlan('x'),
+    analysis: makeAnalysis('x'),
+    snapshotId: 'snap-x',
+    config: GIT_CONFIG,
+    createdAt: now - DEFAULT_TTL_MS - 1,
+    expiresAt: now - 1,
+  });
+  const s = store.get(id);
+  assert.equal(s, undefined, '过期条目应返回 undefined');
+});
+
+test('SyncSessionStore: delete 移除条目', () => {
+  const store = new SyncSessionStore({ now: () => 5_000_000 });
+  const id = makeSession(store, { seed: 'del', nowMs: 5_000_000 });
+  assert.ok(store.get(id), 'set 后存在');
+  store.delete(id);
+  assert.equal(store.get(id), undefined, 'delete 后不存在');
+});
+
+test('SyncSessionStore: TTL 边界——过期临界点', () => {
+  const store = new SyncSessionStore({ now: () => 2_000_000 });
+  const now = 2_000_000;
+  const id = crypto.randomUUID();
+  // 恰好在 expiresAt（now === expiresAt）→ 视为过期（惰性清理）
+  store.set({
+    id,
+    zipPath: '/tmp/boundary.zip',
+    plan: makePlan('boundary'),
+    analysis: makeAnalysis('boundary'),
+    snapshotId: 'snap-b',
+    config: GIT_CONFIG,
+    createdAt: now - DEFAULT_TTL_MS,
+    expiresAt: now,
+  });
+  assert.equal(store.get(id), undefined, 'expiresAt === now 视为过期');
+
+  // 还差 1ms → 仍有效
+  const id2 = crypto.randomUUID();
+  store.set({
+    id: id2,
+    zipPath: '/tmp/boundary2.zip',
+    plan: makePlan('boundary2'),
+    analysis: makeAnalysis('boundary2'),
+    snapshotId: 'snap-b2',
+    config: GIT_CONFIG,
+    createdAt: now - DEFAULT_TTL_MS,
+    expiresAt: now + 1,
+  });
+  assert.ok(store.get(id2), 'expiresAt > now 仍应有效');
+});

package/src/sync/sync-session.ts

@@ -0,0 +1,77 @@
+/**
+ * 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';
+import type { ImportAnalysis, ImportPlan } from '../core/types.ts';
+import type { SyncConfig } from './sync-config.ts';
+
+/** 默认会话 TTL（30 分钟） */
+export const DEFAULT_SESSION_TTL_MS = 30 * 60 * 1000;
+
+/** 一次差异确认会话的完整数据 */
+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 class SyncSessionStore {
+  private readonly sessions = new Map<string, SyncSession>();
+  private readonly ttlMs: number;
+  private readonly now: () => number;
+
+  constructor(opts: { ttlMs?: number; now?: () => number } = {}) {
+    this.ttlMs = opts.ttlMs ?? DEFAULT_SESSION_TTL_MS;
+    this.now = opts.now ?? (() => Date.now());
+  }
+
+  /** 登记（或覆盖）会话；id 缺省时自动生成。createdAt/expiresAt 缺省自动填充。返回会话 id。 */
+  set(session: Omit<SyncSession, 'id' | 'createdAt' | 'expiresAt'> & { id?: string; createdAt?: number; expiresAt?: number }): string {
+    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: string): SyncSession | undefined {
+    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: string): void {
+    this.sessions.delete(id);
+  }
+}

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

@@ -0,0 +1,164 @@
+/**
+ * m-sync-transport：sync-state.json 模型测试。
+ * - hashSection：JSON 分区与文件类分区的内容 hash（确定性、键序无关、文件序无关）
+ * - saveSyncState / loadSyncState：往返、缺省、schemaVersion 校验、损坏 JSON 拒绝
+ */
+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 { hashSection, loadSyncState, saveSyncState, SYNC_STATE_FILE, SYNC_STATE_SCHEMA_VERSION } from './sync-state.ts';
+import type { SyncState } from './sync-state.ts';
+import type { FileEntry, SectionData } from '../schema/types.ts';
+
+test('hashSection: JSON 分区确定性 + 键序无关（同一内容不同插入序 → 相同 hash）', () => {
+  const a: SectionData = { version: 1, namespaces: { general: { value: { theme: 'dark' }, revision: 1, secrets: [] } } };
+  const b: SectionData = {
+    namespaces: { general: { secrets: [], revision: 1, value: { theme: 'dark' } } },
+    version: 1,
+  } as unknown as SectionData;
+  assert.equal(hashSection(a), hashSection(b), '键序无关');
+  const c: SectionData = { version: 1, namespaces: { general: { value: { theme: 'light' }, revision: 1, secrets: [] } } };
+  assert.notEqual(hashSection(a), hashSection(c), '内容变化 hash 必须变化');
+  // 确定性：同对象多次调用
+  assert.equal(hashSection(a), hashSection(a));
+});
+
+test('hashSection: 文件类分区确定性 + 文件序无关，内容变化 → hash 变化', () => {
+  const mk = (files: { relativePath: string; data: Uint8Array; contentHash?: string }[]): SectionData => ({
+    version: 1,
+    files: files.map((f): FileEntry => ({ relativePath: f.relativePath, data: f.data, contentHash: f.contentHash ?? '' })),
+  });
+  const f1 = { relativePath: 'a.md', data: new TextEncoder().encode('# A\n') };
+  const f2 = { relativePath: 'b/skill.md', data: new TextEncoder().encode('# B\n') };
+  const x = hashSection(mk([f1, f2]));
+  const y = hashSection(mk([f2, f1]));
+  assert.equal(x, y, '文件数组顺序无关');
+  const z = hashSection(mk([{ ...f1, data: new TextEncoder().encode('# A changed\n') }, f2]));
+  assert.notEqual(x, z, '文件内容变化 hash 必须变化');
+  // contentHash 字段不参与（以字节为准）
+  const w = hashSection(mk([{ relativePath: f1.relativePath, data: f1.data, contentHash: 'trusted' }, f2]));
+  assert.equal(x, w, 'contentHash 字段值不影响分区 hash');
+});
+
+test('hashSection: JSON 分区与文件类分区 hash 空间不冲突', () => {
+  const jsonHash = hashSection({ version: 1, namespaces: {} } as SectionData);
+  const fileHash = hashSection({ version: 1, files: [] } as SectionData);
+  assert.notEqual(jsonHash, fileHash);
+  assert.equal(jsonHash.length, 64);
+  assert.equal(fileHash.length, 64);
+});
+
+test('saveSyncState / loadSyncState: 完整往返（含 transport 字段）', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-sync-state-'));
+  try {
+    const state: SyncState = {
+      schemaVersion: SYNC_STATE_SCHEMA_VERSION,
+      lastSyncAt: '2026-08-16T12:00:00.000Z',
+      sections: {
+        settings: { hash: 'a'.repeat(64), updatedAt: '2026-08-16T12:00:00.000Z' },
+        skills: { hash: 'b'.repeat(64), updatedAt: '2026-08-16T12:00:00.000Z' },
+      },
+      transport: { type: 'git', ref: 'main' },
+      lastSnapshotId: 'sync-abc',
+    };
+    await saveSyncState(tmp, state);
+    const raw = JSON.parse(await fs.readFile(path.join(tmp, SYNC_STATE_FILE), 'utf8'));
+    assert.equal(raw.schemaVersion, SYNC_STATE_SCHEMA_VERSION);
+    assert.deepEqual(await loadSyncState(tmp), state);
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('loadSyncState: 文件不存在 → 返回缺省空状态（lastSyncAt 为空串，lastSnapshotId 为空串）', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-sync-state-missing-'));
+  try {
+    const state = await loadSyncState(tmp);
+    assert.equal(state.schemaVersion, SYNC_STATE_SCHEMA_VERSION);
+    assert.equal(state.lastSyncAt, '');
+    assert.equal(state.lastSnapshotId, '');
+    assert.deepEqual(state.sections, {});
+    assert.equal(state.transport, undefined);
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('loadSyncState: 不支持的 schemaVersion → 拒绝', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-sync-state-ver-'));
+  try {
+    await fs.writeFile(path.join(tmp, SYNC_STATE_FILE), JSON.stringify({ schemaVersion: 99, lastSyncAt: '', sections: {} }), 'utf8');
+    await assert.rejects(() => loadSyncState(tmp), /schemaVersion/);
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('loadSyncState: 损坏 JSON → 拒绝（不静默降级）', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-sync-state-bad-'));
+  try {
+    await fs.writeFile(path.join(tmp, SYNC_STATE_FILE), '{not-json', 'utf8');
+    await assert.rejects(() => loadSyncState(tmp));
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('saveSyncState: 自动创建目录', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-sync-state-mkdir-'));
+  try {
+    const dir = path.join(tmp, 'nested', 'sync');
+    await saveSyncState(dir, { schemaVersion: SYNC_STATE_SCHEMA_VERSION, lastSyncAt: '', sections: {}, lastSnapshotId: '' });
+    const state = await loadSyncState(dir);
+    assert.equal(state.schemaVersion, SYNC_STATE_SCHEMA_VERSION);
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('loadSyncState: v1 文件 → 内存迁移到 v2 形态（lastSnapshotId=""），不动磁盘', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-sync-state-v1-'));
+  try {
+    // 写入一个 schemaVersion=1 的旧文件（缺 lastSnapshotId）
+    await fs.writeFile(
+      path.join(tmp, SYNC_STATE_FILE),
+      JSON.stringify({
+        schemaVersion: 1,
+        lastSyncAt: '2026-08-15T00:00:00.000Z',
+        sections: { settings: { hash: 'c'.repeat(64), updatedAt: '2026-08-15T00:00:00.000Z' } },
+      }),
+      'utf8',
+    );
+    const state = await loadSyncState(tmp);
+    assert.equal(state.schemaVersion, SYNC_STATE_SCHEMA_VERSION, '内存中应已升级为 v2');
+    assert.equal(state.lastSnapshotId, '', 'v1 文件缺祖先指针时迁移为 ""');
+    assert.equal(state.lastSyncAt, '2026-08-15T00:00:00.000Z');
+    assert.equal(state.sections.settings?.hash, 'c'.repeat(64));
+    // 磁盘上仍是 v1（不就地升级）
+    const onDisk = JSON.parse(await fs.readFile(path.join(tmp, SYNC_STATE_FILE), 'utf8'));
+    assert.equal(onDisk.schemaVersion, 1);
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('saveSyncState / loadSyncState: lastSnapshotId 非空往返', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-sync-state-ancestor-'));
+  try {
+    const state: SyncState = {
+      schemaVersion: SYNC_STATE_SCHEMA_VERSION,
+      lastSyncAt: '2026-08-16T12:00:00.000Z',
+      sections: {},
+      lastSnapshotId: 'sync-deadbeef-1234',
+    };
+    await saveSyncState(tmp, state);
+    const loaded = await loadSyncState(tmp);
+    assert.equal(loaded.lastSnapshotId, 'sync-deadbeef-1234');
+    assert.deepEqual(loaded, state);
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});

package/src/sync/sync-state.ts

@@ -0,0 +1,131 @@
+/**
+ * m-sync-transport：sync-state.json 模型。
+ * 记录上次同步时间与各分区内容 hash，供变更检测（与远端快照对比决定是否重传）。
+ * 纯逻辑 + 可注入 fs；不触碰真实 ~/.dsh。
+ */
+import { sha256Hex } from '../utils/hashing.ts';
+import { parseJsonSafe, stringifyJsonSafe } from '../utils/json.ts';
+import { zhMsg } from '../core/messages.ts';
+import type { MsgFunc } from '../core/messages.ts';
+import type { FilesSection, SectionData, SectionId } from '../schema/types.ts';
+import { createSnapshotFs, joinFs } from './fs.ts';
+import type { SnapshotFs } from './fs.ts';
+
+export const SYNC_STATE_SCHEMA_VERSION = 2;
+/** 历史可读取版本：v1 缺 lastSnapshotId 时做内存迁移到 v2（lastSnapshotId=''）。 */
+export const SYNC_STATE_SUPPORTED_VERSIONS: readonly number[] = [1, 2];
+export const SYNC_STATE_FILE = 'sync-state.json';
+
+/** 单个分区的同步状态：内容 hash + 最近变更时间 */
+export interface SyncSectionState {
+  hash: string;
+  updatedAt: string; // ISO-8601 UTC
+}
+
+/** sync-state.json 结构 */
+export interface SyncState {
+  schemaVersion: number;
+  lastSyncAt: string; // ISO-8601 UTC；'' = 从未同步
+  sections: Partial<Record<SectionId, SyncSectionState>>;
+  /** 当前绑定的传输通道（type = SyncTransport.type，ref = 通道内引用，如 git 分支） */
+  transport?: { type: string; ref: string };
+  /** 最近一次同步的快照 ID（= 共同祖先指针）；'' = 从未同步或无祖先 */
+  lastSnapshotId: string;
+}
+
+/** 文件类分区判定：{ version: 1, files: [...] }（duck-typing，与 JSON 分区区分） */
+function isFilesSection(data: SectionData): data is FilesSection {
+  const obj = data as { version?: unknown; files?: unknown };
+  return data !== null && typeof data === 'object' && obj.version === 1 && Array.isArray(obj.files);
+}
+
+/** 键序规范化的 JSON 序列化（跨机器/跨解析稳定，用于内容 hash） */
+function canonicalJson(value: unknown): string {
+  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 as Record<string, unknown>;
+  const parts: string[] = [];
+  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: SectionData): string {
+  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: string, fsx: SnapshotFs = createSnapshotFs(), msg: MsgFunc = zhMsg): Promise<SyncState> {
+  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 as Record<string, unknown>;
+  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: SyncState['sections'] = {};
+  for (const [sid, rec] of Object.entries(obj['sections'] as Record<string, unknown>)) {
+    if (rec === null || typeof rec !== 'object' || Array.isArray(rec)) {
+      throw new Error(msg('sync.state.sectionRecord', { section: sid }));
+    }
+    const r = rec as Record<string, unknown>;
+    if (typeof r['hash'] !== 'string' || typeof r['updatedAt'] !== 'string') {
+      throw new Error(msg('sync.state.sectionFields', { section: sid }));
+    }
+    sections[sid as SectionId] = { hash: r['hash'], updatedAt: r['updatedAt'] };
+  }
+  const state: SyncState = {
+    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 as Record<string, unknown>)['type'] !== 'string' || typeof (t as Record<string, unknown>)['ref'] !== 'string') {
+      throw new Error(msg('sync.state.transport'));
+    }
+    state.transport = { type: (t as { type: string }).type, ref: (t as { ref: string }).ref };
+  }
+  return state;
+}
+
+/** 保存同步状态（自动创建目录） */
+export async function saveSyncState(dir: string, state: SyncState, fsx: SnapshotFs = createSnapshotFs()): Promise<void> {
+  await fsx.mkdir(dir);
+  await fsx.writeFile(joinFs(dir, SYNC_STATE_FILE), new TextEncoder().encode(stringifyJsonSafe(state, { space: 2 })));
+}

package/src/sync/transport.test.ts

@@ -0,0 +1,111 @@
+/**
+ * m-sync-transport：SyncTransport 抽象层测试。
+ * - computeSnapshotMeta：sections hash 记录 + manifest 摘要透传
+ * - manifestSummaryFrom：Manifest → 摘要
+ * - 接口形状由类型系统保证（编译期），此处验证纯 helper 行为。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { computeSnapshotMeta, manifestSummaryFrom } from './transport.ts';
+import { hashSection } from './sync-state.ts';
+import type { ManifestSummary, SyncSnapshot, SyncTransport } from './transport.ts';
+import type { Manifest, SectionData, SectionId } from '../schema/types.ts';
+
+function sampleSnapshot(overrides: Partial<SyncSnapshot> = {}): SyncSnapshot {
+  return {
+    id: 'snap-001',
+    createdAt: '2026-08-16T12:00:00.000Z',
+    manifest: {
+      schemaVersion: 1,
+      dshVersion: '1.2.3',
+      platform: 'win32',
+      sectionIds: ['settings', 'providers'],
+      containsSecrets: false,
+    },
+    sections: {
+      settings: { version: 1, namespaces: { general: { value: { theme: 'dark' }, revision: 1, secrets: [] } } },
+      providers: { version: 1, providers: { deepseek: { route: '/v1' } } },
+    },
+    ...overrides,
+  };
+}
+
+test('computeSnapshotMeta: 透传 id/createdAt/manifest，sections 为各分区内容 hash', () => {
+  const snap = sampleSnapshot();
+  const meta = computeSnapshotMeta(snap);
+  assert.equal(meta.id, 'snap-001');
+  assert.equal(meta.createdAt, snap.createdAt);
+  assert.deepEqual(meta.manifest, snap.manifest);
+  const snapPlain = snap.sections as Partial<Record<string, unknown>>;
+  assert.equal(meta.sections['settings'], hashSection(snapPlain['settings'] as SectionData));
+  assert.equal(meta.sections['providers'], hashSection(snapPlain['providers'] as SectionData));
+  assert.equal(Object.keys(meta.sections).length, 2);
+});
+
+test('computeSnapshotMeta: 空 sections → 空 hash 记录', () => {
+  const meta = computeSnapshotMeta(sampleSnapshot({ sections: {} }));
+  assert.deepEqual(meta.sections, {});
+});
+
+test('computeSnapshotMeta: hash 与分区内容一一对应，内容变化 → hash 变化', () => {
+  const a = computeSnapshotMeta(sampleSnapshot());
+  const b = computeSnapshotMeta(sampleSnapshot({
+    sections: {
+      settings: { version: 1, namespaces: { general: { value: { theme: 'light' }, revision: 1, secrets: [] } } },
+      providers: { version: 1, providers: { deepseek: { route: '/v1' } } },
+    },
+  }));
+  assert.notEqual(a.sections['settings'], b.sections['settings'], 'settings 内容变化 hash 必须变化');
+  assert.equal(a.sections['providers'], b.sections['providers'], 'providers 未变化 hash 必须相同');
+});
+
+test('manifestSummaryFrom: 从导出 Manifest 提取摘要（只含启用分区）', () => {
+  const manifest: Manifest = {
+    schemaVersion: 1,
+    exporter: { name: 'dsh-config-manager', version: '0.1.0' },
+    source: { dshVersion: '2.0.0', platform: 'linux', arch: 'x64' },
+    exportedAt: '2026-08-16T12:00:00.000Z',
+    sections: {
+      settings: true, ui: true, providers: true, plugins: false, mcp: false,
+      prompts: false, skills: true, agentPresets: false, agentInstructions: false, workspaces: false,
+      pluginFiles: false, credentialsStatus: false, secrets: false, sessions: false, self: false,
+    },
+    security: { containsSecrets: true, encrypted: false, encryption: null },
+  };
+  const summary = manifestSummaryFrom(manifest);
+  assert.equal(summary.schemaVersion, 1);
+  assert.equal(summary.dshVersion, '2.0.0');
+  assert.equal(summary.platform, 'linux');
+  assert.deepEqual(summary.sectionIds, ['settings', 'ui', 'providers', 'skills']);
+  assert.equal(summary.containsSecrets, true);
+});
+
+test('SyncTransport 契约形状：实现对象必须具备 list/upload/download/delete', async () => {
+  const fake: SyncTransport = {
+    type: 'memory',
+    async list() { return []; },
+    async upload(s) { return computeSnapshotMeta(s); },
+    async download(id: string) { return sampleSnapshot({ id }); },
+    async delete(_id: string) {},
+  };
+  const snap = sampleSnapshot();
+  const meta = computeSnapshotMeta(snap);
+  assert.equal(fake.type, 'memory');
+  assert.equal((await fake.list()).length, 0);
+  assert.equal((await fake.download('x')).id, 'x');
+  assert.equal((await fake.upload(snap)).id, meta.id);
+  assert.doesNotThrow(() => fake.delete('x'));
+});
+
+test('ManifestSummary 类型形状（编译期保证 + 运行期检查）', () => {
+  const s: ManifestSummary = {
+    schemaVersion: 1,
+    dshVersion: '1.0.0',
+    platform: 'darwin',
+    sectionIds: [] as SectionId[],
+    containsSecrets: false,
+  };
+  assert.equal(s.schemaVersion, 1);
+  assert.ok(Array.isArray(s.sectionIds));
+});