dsh-config-manager 0.1.12 → 0.1.13

package/src/sync/layout.ts

@@ -0,0 +1,183 @@
+/**
+ * m-sync-transport：散文件目录布局。
+ * 快照根目录 = manifest.json + 按 SECTION_JSON_PATHS 平铺的 JSON 分区
+ *            + 按 SECTION_FILE_PREFIXES 的文件类分区目录（skills 等真实文件）。
+ * 复用 src/schema/config.ts 的路径表；核心逻辑经 SnapshotFs 注入（默认 node:fs/promises）。
+ */
+import path from 'node:path';
+import { parseJsonSafe, stringifyJsonSafe } from '../utils/json.ts';
+import { sha256Hex } from '../utils/hashing.ts';
+import { SECTION_FILE_PREFIXES, SECTION_JSON_PATHS } from '../schema/config.ts';
+import type { FilesSection, SectionData, SectionId } from '../schema/types.ts';
+import { createSnapshotFs, joinFs } from './fs.ts';
+import type { SnapshotFs } from './fs.ts';
+import { hashSection } from './sync-state.ts';
+import type { SyncSnapshot } from './transport.ts';
+
+export const SNAPSHOT_MANIFEST_FILE = 'manifest.json';
+
+/** 快照根目录下的 manifest.json 结构 */
+export interface SnapshotDirManifest {
+  id: string;
+  createdAt: string; // ISO-8601 UTC
+  manifest: SyncSnapshot['manifest'];
+  /** 各分区内容 hash（写入时由 hashSection 计算） */
+  sectionHashes: Partial<Record<SectionId, string>>;
+}
+
+/** 布局支持的分区 = SECTION_JSON_PATHS ∪ SECTION_FILE_PREFIXES（secrets 等不在内） */
+const LAYOUT_SECTION_IDS: readonly SectionId[] = [
+  ...Object.keys(SECTION_JSON_PATHS),
+  ...Object.keys(SECTION_FILE_PREFIXES),
+] as SectionId[];
+
+/**
+ * 文件相对路径安全检查：拒绝空/'.'/'..'、绝对路径、Windows 盘符、反斜杠、
+ * 含 '..' 或 '.' 片段（防穿越快照根目录）。
+ */
+export function isSafeRelPath(rel: string): boolean {
+  if (rel === '' || rel === '.' || rel === '..') return false;
+  if (rel.startsWith('/') || /^[A-Za-z]:[\\/]/.test(rel)) return false;
+  if (rel.includes('\\')) return false;
+  const parts = rel.split('/');
+  if (parts.some((p) => p === '' || p === '.' || p === '..')) return false;
+  return true;
+}
+
+/** 递归列出 dir 下的全部文件（相对 dir 的正斜杠路径，字典序）；目录不存在 → [] */
+export async function listSnapshotFiles(fsx: SnapshotFs, dir: string): Promise<string[]> {
+  const out: string[] = [];
+  const walk = async (abs: string, rel: string): Promise<void> => {
+    const names = await fsx.readdir(abs);
+    for (const name of names) {
+      if (name === '' || name === '.' || name === '..') continue; // 防御异常/恶意 fs
+      const childAbs = joinFs(abs, name);
+      const childRel = rel === '' ? name : `${rel}/${name}`;
+      if (await fsx.isDir(childAbs)) {
+        await walk(childAbs, childRel);
+      } else {
+        out.push(childRel);
+      }
+    }
+  };
+  await walk(dir, '');
+  return out.sort();
+}
+
+/**
+ * 将快照写入散文件目录。
+ * 非法输入（不支持的子分区 / 穿越路径）在任何写入发生前抛错，不留半成品目录。
+ */
+export async function writeSnapshotToDir(
+  snapshot: SyncSnapshot,
+  dir: string,
+  fsx: SnapshotFs = createSnapshotFs(),
+): Promise<SnapshotDirManifest> {
+  const sectionHashes: SnapshotDirManifest['sectionHashes'] = {};
+  for (const [id, data] of Object.entries(snapshot.sections)) {
+    const sid = id as SectionId;
+    if (!LAYOUT_SECTION_IDS.includes(sid)) {
+      throw new Error(`分区 ${sid} 不在散文件布局支持范围（SECTION_JSON_PATHS / SECTION_FILE_PREFIXES）`);
+    }
+    sectionHashes[sid] = hashSection(data as SectionData);
+  }
+  // 预校验全部文件相对路径（不合法 → 抛错且零写入）
+  for (const [sid, data] of Object.entries(snapshot.sections)) {
+    if (!(sid in SECTION_FILE_PREFIXES)) continue;
+    for (const file of (data as FilesSection).files) {
+      if (!isSafeRelPath(file.relativePath)) {
+        throw new Error(`非法文件相对路径: ${file.relativePath}（分区 ${sid}）`);
+      }
+    }
+  }
+
+  await fsx.mkdir(dir);
+  const manifest: SnapshotDirManifest = {
+    id: snapshot.id,
+    createdAt: snapshot.createdAt,
+    manifest: snapshot.manifest,
+    sectionHashes,
+  };
+  await fsx.writeFile(joinFs(dir, SNAPSHOT_MANIFEST_FILE), new TextEncoder().encode(stringifyJsonSafe(manifest, { space: 2 })));
+
+  // JSON 分区：按 SECTION_JSON_PATHS 平铺
+  for (const [sid, rel] of Object.entries(SECTION_JSON_PATHS)) {
+    const data = snapshot.sections[sid as SectionId];
+    if (data === undefined) continue;
+    const abs = joinFs(dir, rel);
+    await fsx.mkdir(path.dirname(abs));
+    await fsx.writeFile(abs, new TextEncoder().encode(stringifyJsonSafe(data, { space: 2 })));
+  }
+
+  // 文件类分区：目录前缀 + 真实文件
+  for (const [sid, prefix] of Object.entries(SECTION_FILE_PREFIXES)) {
+    const data = snapshot.sections[sid as SectionId] as FilesSection | undefined;
+    if (data === undefined) continue;
+    const baseAbs = joinFs(dir, prefix);
+    await fsx.mkdir(baseAbs); // 空文件类分区也保留目录（读回可还原空 files）
+    for (const file of data.files) {
+      const abs = joinFs(baseAbs, file.relativePath);
+      await fsx.mkdir(path.dirname(abs));
+      await fsx.writeFile(abs, file.data);
+    }
+  }
+  return manifest;
+}
+
+/**
+ * 从散文件目录读回快照。
+ * manifest 声明的分区必须可解析：JSON 分区文件缺失 / 文件分区目录缺失 → 抛错（不静默降级）。
+ */
+export async function readSnapshotFromDir(dir: string, fsx: SnapshotFs = createSnapshotFs()): Promise<SyncSnapshot> {
+  const manifestAbs = joinFs(dir, SNAPSHOT_MANIFEST_FILE);
+  if (!(await fsx.exists(manifestAbs))) {
+    throw new Error(`快照目录缺少 ${SNAPSHOT_MANIFEST_FILE}: ${dir}`);
+  }
+  const parsed = parseJsonSafe(Buffer.from(await fsx.readFile(manifestAbs)).toString('utf8'));
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error('manifest.json 损坏：必须是对象');
+  }
+  const m = parsed as Record<string, unknown>;
+  if (typeof m['id'] !== 'string' || typeof m['createdAt'] !== 'string'
+    || m['manifest'] === null || typeof m['manifest'] !== 'object'
+    || m['sectionHashes'] === null || typeof m['sectionHashes'] !== 'object') {
+    throw new Error('manifest.json 损坏：缺少 id/createdAt/manifest/sectionHashes');
+  }
+  const manifest = parsed as SnapshotDirManifest;
+
+  const sections: SyncSnapshot['sections'] = {};
+  const declared = Object.keys(manifest.sectionHashes) as SectionId[];
+  for (const sid of declared) {
+    if (!LAYOUT_SECTION_IDS.includes(sid)) {
+      throw new Error(`manifest 声明了布局不支持的分区 ${sid}`);
+    }
+  }
+
+  // JSON 分区
+  for (const [sid, rel] of Object.entries(SECTION_JSON_PATHS)) {
+    if (!(sid in manifest.sectionHashes)) continue;
+    const abs = joinFs(dir, rel);
+    if (!(await fsx.exists(abs))) {
+      throw new Error(`快照缺少 JSON 分区文件 ${rel}（${sid}）`);
+    }
+    sections[sid as SectionId] = parseJsonSafe(Buffer.from(await fsx.readFile(abs)).toString('utf8')) as SectionData;
+  }
+
+  // 文件类分区
+  for (const [sid, prefix] of Object.entries(SECTION_FILE_PREFIXES)) {
+    if (!(sid in manifest.sectionHashes)) continue;
+    const baseAbs = joinFs(dir, prefix);
+    if (!(await fsx.isDir(baseAbs))) {
+      throw new Error(`快照缺少文件分区目录 ${prefix}（${sid}）`);
+    }
+    const rels = await listSnapshotFiles(fsx, baseAbs);
+    const files: FilesSection['files'] = [];
+    for (const rel of rels) {
+      const data = await fsx.readFile(joinFs(baseAbs, rel));
+      files.push({ relativePath: rel, data, contentHash: sha256Hex(data) });
+    }
+    sections[sid as SectionId] = { version: 1, files };
+  }
+
+  return { id: manifest.id, createdAt: manifest.createdAt, manifest: manifest.manifest, sections };
+}

package/src/sync/sync-config.ts

@@ -0,0 +1,72 @@
+/**
+ * m-sync-ui：同步仓库配置的持久化（sync-config.json）。
+ *
+ * 与 sync-state.json 的分工：sync-state 记录「同步了哪些分区、何时同步」（t4 拥有），
+ * 本文件只记录「上次使用的仓库配置」（repoUrl / gitBin），供 UI 打开设置页时回填表单。
+ * - repoUrl 不含 token（token 只存 DSH credentials，见 src/index.ts SYNC_CREDENTIAL_REF）；
+ * - 文件位于同步状态目录（$DSH_HOME/dsh-config-manager/sync/），非敏感（可回显给浏览器）；
+ * - 纯逻辑 + 可注入 fs（node:fs/promises 直用；测试走临时目录）。
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { parseJsonSafe, stringifyJsonSafe } from '../utils/json.ts';
+
+export const SYNC_CONFIG_FILE = 'sync-config.json';
+
+/** 持久化的仓库配置（不含任何凭据） */
+export interface SyncConfig {
+  repoUrl: string;
+  gitBin?: string;
+}
+
+/** 读取仓库配置；文件不存在/损坏 → null（视为未配置，UI 显示空表单） */
+export async function readSyncConfig(dir: string): Promise<SyncConfig | null> {
+  const file = path.join(dir, SYNC_CONFIG_FILE);
+  let raw: string;
+  try {
+    raw = await fs.readFile(file, 'utf8');
+  } catch {
+    return null;
+  }
+  const parsed = parseJsonSafe(raw);
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+  const obj = parsed as Record<string, unknown>;
+  if (typeof obj['repoUrl'] !== 'string' || obj['repoUrl'] === '') return null;
+  const cfg: SyncConfig = { repoUrl: obj['repoUrl'] };
+  if (typeof obj['gitBin'] === 'string' && obj['gitBin'] !== '') cfg.gitBin = obj['gitBin'];
+  return cfg;
+}
+
+/** 保存仓库配置（自动创建目录；覆盖旧值） */
+export async function writeSyncConfig(dir: string, cfg: SyncConfig): Promise<void> {
+  await fs.mkdir(dir, { recursive: true });
+  await fs.writeFile(path.join(dir, SYNC_CONFIG_FILE), stringifyJsonSafe(cfg, { space: 2 }), 'utf8');
+}
+
+/**
+ * 仓库地址合法性校验（返回错误消息；null = 合法）。
+ * 安全约束：token 永不拼入 repoUrl —— http(s) 地址带 userinfo（username[:password]@）直接拒绝，
+ * 引导用户把 token 放凭据字段（DSH credentials），避免 token 经 URL 泄漏进 git 历史/日志。
+ */
+export function validateRepoUrl(repoUrl: string): string | null {
+  if (typeof repoUrl !== 'string' || repoUrl.trim() === '') {
+    return 'repoUrl is required';
+  }
+  const url = repoUrl.trim();
+  if (/\s/.test(url)) {
+    return '仓库地址不能包含空白字符';
+  }
+  if (/^https?:\/\//i.test(url)) {
+    let parsed: URL;
+    try {
+      parsed = new URL(url);
+    } catch {
+      return `无法解析仓库地址: ${url}`;
+    }
+    if (parsed.username !== '' || parsed.password !== '') {
+      return '请勿在仓库地址中包含用户名/密码（认证 token 请使用凭据字段，不会拼入地址）';
+    }
+  }
+  return null;
+}

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

@@ -0,0 +1,299 @@
+/**
+ * m-sync-flow：SyncEngine push/pull 编排测试。
+ * - push：收集 portable 分区 → 组装 SyncSnapshot → 更新 sync-state → 上传 transport
+ * - push：secret 断言（凭据值/敏感字段永不进入快照；不含 credentials/secrets 分区）
+ * - push：portable 过滤（deviceSpecific/platformSpecific 分区不参与同步）
+ * - pull：复用 Importer 预览流程（analyzeImport/createImportPlan），绝不直接写配置、绝不执行导入
+ * - pull：无远端快照 / containsSecrets 拒绝 / 冲突 → needsReview
+ */
+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 { SyncEngine } from './sync-engine.ts';
+import { hashSection, loadSyncState, SYNC_STATE_FILE } from './sync-state.ts';
+import { computeSnapshotMeta } from './transport.ts';
+import type { SyncSnapshot, SyncSnapshotMeta, SyncTransport } from './transport.ts';
+import { createAdapters } from '../adapters/index.ts';
+import { makeContext, MemSnapshotStore } from '../adapters/test-helpers.ts';
+import { Importer } from '../core/importer.ts';
+import type { SectionId } from '../schema/types.ts';
+
+/** 内存 SyncTransport：记录方法调用（spy），供断言「pull 不写远端」 */
+class MemSyncTransport implements SyncTransport {
+  readonly type = 'memory';
+  snapshots = new Map<string, SyncSnapshot>();
+  metas: SyncSnapshotMeta[] = [];
+  calls: string[] = [];
+  async list(): Promise<SyncSnapshotMeta[]> {
+    this.calls.push('list');
+    return [...this.metas].sort((a, b) => (a.createdAt < b.createdAt ? -1 : 1));
+  }
+  async upload(snapshot: SyncSnapshot): Promise<SyncSnapshotMeta> {
+    this.calls.push('upload');
+    this.snapshots.set(snapshot.id, snapshot);
+    this.metas.push(computeSnapshotMeta(snapshot));
+    return computeSnapshotMeta(snapshot);
+  }
+  async download(id: string): Promise<SyncSnapshot> {
+    this.calls.push('download');
+    const s = this.snapshots.get(id);
+    if (!s) throw new Error(`快照不存在: ${id}`);
+    return s;
+  }
+  async delete(id: string): Promise<void> {
+    this.calls.push('delete');
+    this.snapshots.delete(id);
+  }
+}
+
+const NS = ['general', 'theme'];
+
+function seedSource(ctx: ReturnType<typeof makeContext>): void {
+  ctx.settings.ns.set('general', { value: { theme: 'dark', language: 'zh-CN' }, revision: 3, secrets: [] });
+  ctx.settings.ns.set('theme', { value: { mode: 'dark' }, revision: 1, secrets: [] });
+  ctx.plugins.installed.set('@deepseek-ai/dsh-ssh', { name: '@deepseek-ai/dsh-ssh', version: '1.0.0', enabled: true });
+}
+
+function makeEngine(opts: {
+  ctx: ReturnType<typeof makeContext>;
+  transport: MemSyncTransport;
+  stateDir: string;
+  localSnapshotsDir?: string;
+  extra?: ConstructorParameters<typeof SyncEngine>[0];
+}) {
+  const adapters = createAdapters({ namespaces: NS });
+  const importer = new Importer({ ctx: opts.ctx, adapters, snapshotStore: new MemSnapshotStore() });
+  return new SyncEngine({
+    ctx: opts.ctx,
+    transport: opts.transport,
+    stateDir: opts.stateDir,
+    localSnapshotsDir: opts.localSnapshotsDir,
+    adapters,
+    importer,
+    now: () => new Date('2026-08-16T12:00:00.000Z'),
+    ...opts.extra,
+  });
+}
+
+test('push: 收集 portable 分区 → 上传快照 → 更新 sync-state → 本地散文件副本', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-sync-engine-push-'));
+  try {
+    const ctx = makeContext('win32', 'C:\\Users\\alice');
+    seedSource(ctx);
+    await ctx.fs.writeFile('skills/coding.md', Buffer.from('# Coding\n', 'utf8'));
+    const transport = new MemSyncTransport();
+    const local = path.join(tmp, 'local-snapshots');
+    const engine = makeEngine({ ctx, transport, stateDir: tmp, localSnapshotsDir: local });
+
+    const report = await engine.push({ snapshotId: 'sync-001' });
+    assert.equal(report.ok, true);
+    assert.equal(report.snapshotId, 'sync-001');
+    assert.ok(report.sections.includes('settings'), 'settings 进入同步');
+    assert.ok(report.sections.includes('skills'), 'skills（文件类 portable）进入同步');
+    assert.ok(!report.sections.includes('credentialsStatus'), 'credentials 不进入同步');
+
+    // 上传载荷：内容 + manifest 摘要
+    const uploaded = transport.snapshots.get('sync-001')!;
+    assert.ok(uploaded, '快照已上传');
+    assert.equal(uploaded.createdAt, '2026-08-16T12:00:00.000Z');
+    assert.equal(uploaded.manifest.containsSecrets, false);
+    const exportedGeneral = (uploaded.sections['settings'] as { namespaces: Record<string, { value: unknown; revision: number; secrets: unknown[] }> }).namespaces['general']!;
+    assert.ok(exportedGeneral, 'settings.general 已导出');
+    assert.deepEqual(exportedGeneral.value, { theme: 'dark', language: 'zh-CN' });
+    assert.equal(exportedGeneral.revision, 3);
+    assert.deepEqual(exportedGeneral.secrets, []);
+    assert.equal((uploaded.sections['skills'] as { files: unknown[] }).files.length, 1);
+
+    // sync-state 更新：每分区 hash + updatedAt + lastSyncAt + transport 绑定
+    const state = await loadSyncState(tmp);
+    assert.equal(state.lastSyncAt, '2026-08-16T12:00:00.000Z');
+    assert.equal(state.sections['settings']?.hash, hashSection(uploaded.sections['settings']!));
+    assert.equal(state.sections['settings']?.updatedAt, '2026-08-16T12:00:00.000Z');
+    assert.deepEqual(state.transport, { type: 'memory', ref: '' });
+    const raw = JSON.parse(await fs.readFile(path.join(tmp, SYNC_STATE_FILE), 'utf8'));
+    assert.equal(raw.schemaVersion, 1);
+
+    // 本地散文件副本（复用 t2 layout 布局）
+    assert.ok((await fs.stat(path.join(local, 'sync-001', 'manifest.json'))).isFile());
+    assert.ok((await fs.stat(path.join(local, 'sync-001', 'config', 'settings.json'))).isFile());
+    assert.equal(await fs.readFile(path.join(local, 'sync-001', 'custom', 'skills', 'coding.md'), 'utf8'), '# Coding\n');
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('push: secret 断言——敏感字段值被剥离、凭据分区绝不参与、快照序列化不含秘密值', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-sync-engine-secret-'));
+  try {
+    const ctx = makeContext('win32', 'C:\\Users\\alice');
+    ctx.settings.ns.set('general', {
+      value: { theme: 'dark', apiToken: 'sk-super-secret-value', password: 'p@ss' },
+      revision: 3,
+      secrets: [{ path: ['apiToken'], set: true }],
+    });
+    // deviceSpecific 凭据分区即使有值也不得进入快照
+    ctx.credentials.values.set('DEEPSEEK_API_KEY', 'sk-credential-secret');
+    const transport = new MemSyncTransport();
+    const engine = makeEngine({ ctx, transport, stateDir: tmp });
+
+    const report = await engine.push({ snapshotId: 'sync-sec' });
+    assert.equal(report.ok, true);
+    const uploaded = transport.snapshots.get('sync-sec')!;
+    const serialized = JSON.stringify(uploaded);
+    assert.ok(!serialized.includes('sk-super-secret-value'), '敏感字段值不得进入快照');
+    assert.ok(!serialized.includes('p@ss'), '密码值不得进入快照');
+    assert.ok(!serialized.includes('sk-credential-secret'), '凭据值不得进入快照');
+    for (const forbidden of ['credentials', 'credentialsStatus', 'secrets'] as SectionId[]) {
+      assert.ok(!(forbidden in uploaded.sections), `分区 ${forbidden} 不得进入快照`);
+    }
+    // 剥离后保留字段名与空值（供「需补录」提示）
+    const general = (uploaded.sections['settings'] as { namespaces: Record<string, unknown> }).namespaces['general'] as { value: Record<string, unknown> };
+    assert.equal(general.value['apiToken'], '');
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('push: portable 过滤——deviceSpecific/platformSpecific 分区不参与同步', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-sync-engine-portable-'));
+  try {
+    const ctx = makeContext('win32', 'C:\\Users\\alice');
+    seedSource(ctx);
+    ctx.workspace.records.set('w1', { id: 'w1', path: 'C:\\work', title: 'work', sessionIds: [] });
+    ctx.credentials.values.set('DEEPSEEK_API_KEY', 'sk-x');
+    await ctx.fs.writeFile('dsh-ssh.json', Buffer.from('{"hosts":{}}', 'utf8')); // pluginFiles 白名单
+    const transport = new MemSyncTransport();
+    const engine = makeEngine({ ctx, transport, stateDir: tmp });
+
+    await engine.push({ snapshotId: 'sync-p' });
+    const uploaded = transport.snapshots.get('sync-p')!;
+    for (const forbidden of ['workspaces', 'mcp', 'credentialsStatus', 'credentials', 'pluginFiles', 'sessions'] as SectionId[]) {
+      assert.ok(!(forbidden in uploaded.sections), `非 portable 分区 ${forbidden} 不得进入快照`);
+    }
+    assert.ok(!uploaded.manifest.sectionIds.includes('workspaces' as SectionId));
+    assert.ok(uploaded.manifest.sectionIds.includes('settings'));
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('pull: 复用 Importer 预览流程，绝不直接写配置，产出差异报告', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-sync-engine-pull-'));
+  try {
+    const remote: SyncSnapshot = {
+      id: 'remote-1',
+      createdAt: '2026-08-16T12:00:00.000Z',
+      manifest: { schemaVersion: 1, dshVersion: '1.2.3', platform: 'win32', sectionIds: ['settings'], containsSecrets: false },
+      sections: {
+        settings: { version: 1, namespaces: { general: { value: { theme: 'dark', language: 'zh-CN' }, revision: 5, secrets: [] } } },
+      },
+    };
+    const transport = new MemSyncTransport();
+    transport.snapshots.set('remote-1', remote);
+    transport.metas.push(computeSnapshotMeta(remote));
+
+    // 本地目标：general 已注册但从未配置 → Create（初始化），无需人工决策
+    const ctx = makeContext('win32', 'C:\\Users\\alice');
+    for (const n of NS) ctx.settings.registered.add(n);
+    const engine = makeEngine({ ctx, transport, stateDir: tmp });
+
+    const report = await engine.pull();
+    assert.equal(report.ok, true);
+    assert.equal(report.snapshotId, 'remote-1');
+    const createItem = report.changes.find((c) => c.id === 'settings:general');
+    assert.ok(createItem, '差异报告含 settings:general');
+    assert.equal(createItem?.kind, 'Create');
+    assert.equal(createItem?.adapter, 'settings');
+    assert.equal(report.needsReview, false, '纯 Create 无需人工决策');
+
+    // 零写入：目标配置未被修改，远端未被写
+    assert.equal(ctx.settings.ns.get('general'), undefined, '目标 settings 未被写入');
+    assert.deepEqual(transport.calls, ['list', 'download'], 'pull 只读远端（list/download），不 upload/delete');
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('pull: 冲突项 → needsReview=true，仍零写入', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-sync-engine-conflict-'));
+  try {
+    const remote: SyncSnapshot = {
+      id: 'remote-2',
+      createdAt: '2026-08-16T12:00:00.000Z',
+      manifest: { schemaVersion: 1, dshVersion: '1.2.3', platform: 'win32', sectionIds: ['settings'], containsSecrets: false },
+      sections: {
+        settings: { version: 1, namespaces: { general: { value: { theme: 'dark' }, revision: 5, secrets: [] } } },
+      },
+    };
+    const transport = new MemSyncTransport();
+    transport.snapshots.set('remote-2', remote);
+    transport.metas.push(computeSnapshotMeta(remote));
+
+    const ctx = makeContext('win32', 'C:\\Users\\alice');
+    for (const n of NS) ctx.settings.registered.add(n);
+    ctx.settings.ns.set('general', { value: { theme: 'light' }, revision: 9, secrets: [] });
+    const engine = makeEngine({ ctx, transport, stateDir: tmp });
+
+    const report = await engine.pull();
+    assert.equal(report.ok, true);
+    assert.ok(report.changes.some((c) => c.kind === 'Conflict'), '本地与远端不同 → Conflict');
+    assert.equal(report.needsReview, true, '冲突需人工决策');
+    assert.deepEqual(ctx.settings.ns.get('general')?.value, { theme: 'light' }, '目标未被覆盖');
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('pull: 远端无快照 → 空报告（不报错）', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-sync-engine-none-'));
+  try {
+    const ctx = makeContext('win32', 'C:\\Users\\alice');
+    const engine = makeEngine({ ctx, transport: new MemSyncTransport(), stateDir: tmp });
+    const report = await engine.pull();
+    assert.equal(report.ok, true);
+    assert.equal(report.snapshotId, '');
+    assert.deepEqual(report.changes, []);
+    assert.equal(report.needsReview, false);
+    assert.ok(report.message && report.message.includes('无快照'));
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('pull: 远端快照声明 containsSecrets=true → 拒绝（同步通道永不携带秘密）', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-sync-engine-leak-'));
+  try {
+    const remote: SyncSnapshot = {
+      id: 'remote-bad',
+      createdAt: '2026-08-16T12:00:00.000Z',
+      manifest: { schemaVersion: 1, dshVersion: '1.2.3', platform: 'win32', sectionIds: ['settings'], containsSecrets: true },
+      sections: { settings: { version: 1, namespaces: {} } },
+    };
+    const transport = new MemSyncTransport();
+    transport.snapshots.set('remote-bad', remote);
+    transport.metas.push(computeSnapshotMeta(remote));
+    const ctx = makeContext('win32', 'C:\\Users\\alice');
+    const engine = makeEngine({ ctx, transport, stateDir: tmp });
+    await assert.rejects(() => engine.pull(), /秘密|containsSecrets/);
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('push: 全部 portable 分区导出失败 → ok=false + 明确 message', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-sync-engine-fail-'));
+  try {
+    const ctx = makeContext('win32', 'C:\\Users\\alice'); // 无任何 namespace/文件/插件
+    const transport = new MemSyncTransport();
+    const engine = makeEngine({ ctx, transport, stateDir: tmp });
+    const report = await engine.push({ snapshotId: 'sync-fail' });
+    // 空数据仍视为「成功导出（空分区）」还是失败？settings 无 namespace 时 adapter 返回空（不抛错）
+    assert.equal(report.ok, true, '空配置导出为空快照而非失败');
+    assert.equal(transport.snapshots.has('sync-fail'), true);
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});