dsh-config-manager 0.1.12 → 0.1.13

package/src/sync/git/git-transport.test.ts

@@ -0,0 +1,456 @@
+/**
+ * m-git-channel：Git 私有仓库通道测试（TDD：先红后绿）。
+ * - mock exec 单元测试：命令序列 / token 不泄漏（argv、commit message、错误消息、credential 文件生命周期）
+ * - 真实 git 集成测试：本地 bare repo 模拟远端（无真实网络），端到端 list/upload/download/delete
+ */
+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 { execFile } from 'node:child_process';
+
+import { GitTransport, GitTransportError } from './git-transport.ts';
+import type { GitExecFn, GitExecResult, GitTransportOptions } from './git-transport.ts';
+import { computeSnapshotMeta } from '../transport.ts';
+import type { SyncSnapshot } from '../transport.ts';
+
+/* ---------------- helpers ---------------- */
+
+const TEST_TOKEN = 'secret-token-xyz-123';
+
+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,
+  };
+}
+
+/** 记录每次 git 调用的 mock exec：默认全部成功；按需特判 */
+interface CallRecord { cmd: string; args: string[]; }
+function mockExec(
+  calls: CallRecord[],
+  rules: {
+    /** args.join(' ') 包含该子串时返回 code（用于 rev-parse/diff/ls-remote 特判） */
+    codeBy?: Record<string, number>;
+    /** 模拟失败：返回 code + stderr（可含 token 变体，验证 sanitize） */
+    failOn?: { match: string; code: number; stderr: string };
+  } = {},
+): GitExecFn {
+  return async (_cmd, args): Promise<GitExecResult> => {
+    calls.push({ cmd: 'git', args });
+    const joined = args.join(' ');
+    if (rules.failOn && joined.includes(rules.failOn.match)) {
+      return { stdout: '', stderr: rules.failOn.stderr, code: rules.failOn.code };
+    }
+    for (const [sub, code] of Object.entries(rules.codeBy ?? {})) {
+      if (joined.includes(sub)) return { stdout: '', stderr: '', code };
+    }
+    // 默认：diff --cached --quiet = 有变更（code 1）；其余成功
+    if (joined.includes('diff') && joined.includes('--quiet')) return { stdout: '', stderr: '', code: 1 };
+    return { stdout: '', stderr: '', code: 0 };
+  };
+}
+
+async function makeTempDir(t: test.TestContext): Promise<string> {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-git-test-'));
+  t.after(async () => { await fs.rm(dir, { recursive: true, force: true }); });
+  return dir;
+}
+
+/** 真实 git：初始化一个非空 git 工作树（.git 存在，使 ensureRepo 走已 clone 分支） */
+async function makeGitWorkDir(t: test.TestContext): Promise<string> {
+  const dir = await makeTempDir(t);
+  await runRealGit(['init'], dir);
+  await runRealGit(['config', 'user.name', 'test'], dir);
+  await runRealGit(['config', 'user.email', 'test@local'], dir);
+  return dir;
+}
+
+function runRealGit(args: string[], cwd: string): Promise<{ stdout: string; stderr: string; code: number }> {
+  return new Promise((resolve) => {
+    execFile('git', args, { cwd, encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 }, (err, stdout, stderr) => {
+      if (err) {
+        const e = err as { code?: number };
+        resolve({ stdout: String(stdout), stderr: String(stderr), code: e.code ?? 1 });
+      } else {
+        resolve({ stdout: String(stdout), stderr: String(stderr), code: 0 });
+      }
+    });
+  });
+}
+
+/** 本地 bare 仓库（模拟远端，无认证需求） */
+async function makeBareRepo(t: test.TestContext): Promise<string> {
+  const dir = await makeTempDir(t);
+  const bare = path.join(dir, 'remote.git');
+  const r = await runRealGit(['init', '--bare', bare], dir);
+  assert.equal(r.code, 0, `git init --bare 失败: ${r.stderr}`);
+  return bare;
+}
+
+function makeOptions(overrides: Partial<GitTransportOptions> = {}): GitTransportOptions {
+  return {
+    repoUrl: 'https://github.com/example/private-config.git',
+    workDir: 'UNSET',
+    credentials: { getToken: async () => TEST_TOKEN },
+    ...overrides,
+  };
+}
+
+function joinedArgs(calls: CallRecord[], needle: string): string[] {
+  return calls.filter((c) => c.args.join(' ').includes(needle)).map((c) => c.args.join(' '));
+}
+
+/* ---------------- 单元测试（mock exec） ---------------- */
+
+test('非 git 仓库：workDir 非空且无 .git → 报错清晰（含 workDir 路径）', async (t) => {
+  const dir = await makeTempDir(t);
+  await fs.writeFile(path.join(dir, 'stray.txt'), 'not a repo');
+  const calls: CallRecord[] = [];
+  const transport = new GitTransport(makeOptions({ workDir: dir, exec: mockExec(calls) }));
+  await assert.rejects(
+    transport.list(),
+    (err: unknown) => {
+      assert.ok(err instanceof GitTransportError, '必须是 GitTransportError');
+      assert.match(err.message, /不是 git 仓库/);
+      assert.ok(err.message.includes(dir), '错误消息应含 workDir 路径');
+      return true;
+    },
+  );
+});
+
+test('首次使用（空目录无 .git）→ 触发 clone（credential helper 注入，argv 不含 token）', async (t) => {
+  const dir = await makeTempDir(t); // 空目录
+  const calls: CallRecord[] = [];
+  const transport = new GitTransport(makeOptions({ workDir: dir, exec: mockExec(calls) }));
+  await transport.list();
+  const clones = joinedArgs(calls, 'clone');
+  assert.equal(clones.length, 1, '应恰好调用一次 clone');
+  const cloneArgs = calls.find((c) => c.args.includes('clone'))!.args;
+  // credential helper 注入到 clone 参数
+  assert.ok(cloneArgs.some((a) => a.startsWith('credential.helper=') && a.includes('store --file=')), 'clone 应带 store credential helper');
+  // argv 不含 token
+  for (const arg of cloneArgs) assert.ok(!arg.includes(TEST_TOKEN), `argv 泄漏 token: ${arg}`);
+  // clone 的 URL 参数不带 token
+  const urlArg = cloneArgs[cloneArgs.indexOf('clone') + 1]!;
+  assert.ok(!urlArg.includes(TEST_TOKEN), 'clone URL 不得含 token');
+  assert.ok(!urlArg.includes('oauth2:'), 'clone URL 不得含内嵌凭据');
+});
+
+test('token 不泄漏：credential 文件在 git 调用期间存在、用后删除、内容含 token 但 argv 不含', async (t) => {
+  const dir = await makeTempDir(t);
+  const calls: CallRecord[] = [];
+  const credFileContents: string[] = [];
+  const exec: GitExecFn = async (_cmd, args) => {
+    calls.push({ cmd: 'git', args });
+    const helper = args.find((a) => a.startsWith('credential.helper=') && a.includes('store --file='));
+    if (helper) {
+      const file = helper.slice(helper.indexOf('--file=') + '--file='.length).replace(/^"|"$/g, '');
+      credFileContents.push(await fs.readFile(file, 'utf8'));
+    }
+    return { stdout: '', stderr: '', code: 0 };
+  };
+  const transport = new GitTransport(makeOptions({ workDir: dir, exec }));
+  await transport.list(); // 触发 clone（带 credential）
+  // credential 文件在调用期间存在（被读到内容）
+  assert.ok(credFileContents.length >= 1, 'credential 文件应被创建并被 git 调用读取');
+  assert.ok(credFileContents.some((c) => c.includes(TEST_TOKEN)), 'credential 文件应含 token');
+  // 调用后无残留：credential 临时目录已删除（找不到任何含 token 的文件）
+  const tmpRoot = path.join(os.tmpdir());
+  const leftovers = (await fs.readdir(tmpRoot)).filter((n) => n.startsWith('dsh-git-cred-'));
+  for (const n of leftovers) {
+    const p = path.join(tmpRoot, n);
+    try {
+      const stat = await fs.stat(p);
+      if (stat.isDirectory()) {
+        const files = await fs.readdir(p);
+        assert.equal(files.length, 0, `credential 临时目录应有残留: ${n}`);
+      }
+    } catch { /* 已删除 */ }
+  }
+  // argv 不含 token
+  for (const c of calls) for (const arg of c.args) assert.ok(!arg.includes(TEST_TOKEN), `argv 泄漏 token: ${arg}`);
+});
+
+test('upload 契约：写快照目录 + add + commit(add) + push，返回 computeSnapshotMeta', async (t) => {
+  const dir = await makeGitWorkDir(t);
+  const calls: CallRecord[] = [];
+  const transport = new GitTransport(makeOptions({ workDir: dir, exec: mockExec(calls) }));
+  const snap = sampleSnapshot();
+  const meta = await transport.upload(snap);
+  assert.deepEqual(meta, computeSnapshotMeta(snap));
+  // 命令序列：add snapshots/<id> → diff --cached --quiet → commit -m add → push
+  const adds = joinedArgs(calls, 'add');
+  assert.ok(adds.some((a) => a.includes('snapshots/snap-001')), `应 add 快照目录: ${JSON.stringify(adds)}`);
+  assert.equal(joinedArgs(calls, 'diff --cached --quiet').length, 1);
+  const commits = joinedArgs(calls, 'commit');
+  assert.equal(commits.length, 1);
+  assert.match(commits[0]!, /-m sync: add snapshot snap-001/);
+  assert.equal(joinedArgs(calls, 'push').length, 1, 'upload 应 push');
+  // commit message 不含 token
+  for (const c of commits) assert.ok(!c.includes(TEST_TOKEN));
+});
+
+test('upload 幂等：工作树内容与 HEAD 一致 → 不 commit 不 push，仍返回 meta', async (t) => {
+  const dir = await makeGitWorkDir(t);
+  const calls: CallRecord[] = [];
+  const transport = new GitTransport(makeOptions({
+    workDir: dir,
+    exec: mockExec(calls, { codeBy: { 'diff --cached --quiet': 0 } }),
+  }));
+  const meta = await transport.upload(sampleSnapshot());
+  assert.equal(meta.id, 'snap-001');
+  assert.equal(joinedArgs(calls, 'commit').length, 0, '无变更不得 commit');
+  assert.equal(joinedArgs(calls, 'push').length, 0, '无变更不得 push');
+});
+
+test('upload 覆盖：同 id 再次上传 → commit message 为 update', async (t) => {
+  const dir = await makeGitWorkDir(t);
+  const calls: CallRecord[] = [];
+  const transport = new GitTransport(makeOptions({ workDir: dir, exec: mockExec(calls) }));
+  await transport.upload(sampleSnapshot());
+  calls.length = 0; // 清空，模拟第二次 upload（同 id 覆盖）
+  await transport.upload(sampleSnapshot({ createdAt: '2026-08-16T13:00:00.000Z' }));
+  const commits = joinedArgs(calls, 'commit');
+  assert.equal(commits.length, 1);
+  assert.match(commits[0]!, /-m sync: update snapshot snap-001/);
+});
+
+test('download 契约：不存在的 id → 抛错（消息含 id）', async (t) => {
+  const dir = await makeGitWorkDir(t);
+  const calls: CallRecord[] = [];
+  const transport = new GitTransport(makeOptions({ workDir: dir, exec: mockExec(calls) }));
+  await assert.rejects(
+    transport.download('missing-001'),
+    (err: unknown) => {
+      assert.ok(err instanceof GitTransportError);
+      assert.match(err.message, /missing-001/);
+      assert.match(err.message, /不存在/);
+      return true;
+    },
+  );
+});
+
+test('delete 契约：存在 → 删除目录 + add -A + commit(delete) + push；不存在 → 静默成功', async (t) => {
+  const dir = await makeGitWorkDir(t);
+  const calls: CallRecord[] = [];
+  const transport = new GitTransport(makeOptions({ workDir: dir, exec: mockExec(calls) }));
+  // 准备一个已存在快照目录
+  await fs.mkdir(path.join(dir, 'snapshots', 'snap-001'), { recursive: true });
+  await fs.writeFile(path.join(dir, 'snapshots', 'snap-001', 'manifest.json'), '{}');
+  await transport.delete('snap-001');
+  const adds = joinedArgs(calls, 'add -A');
+  assert.ok(adds.some((a) => a.includes('snapshots/snap-001')), 'delete 应 stage 删除');
+  assert.equal(joinedArgs(calls, 'commit').length, 1);
+  assert.match(joinedArgs(calls, 'commit')[0]!, /-m sync: delete snapshot snap-001/);
+  assert.equal(joinedArgs(calls, 'push').length, 1);
+  // 不存在 → 成功且不产生 git 写操作
+  calls.length = 0;
+  await transport.delete('never-existed');
+  assert.equal(joinedArgs(calls, 'commit').length, 0);
+  assert.equal(joinedArgs(calls, 'push').length, 0);
+});
+
+test('错误消息 sanitize：git 失败 stderr 含 token → 抛出消息被替换为 [REDACTED]', async (t) => {
+  const dir = await makeGitWorkDir(t);
+  const calls: CallRecord[] = [];
+  const transport = new GitTransport(makeOptions({
+    workDir: dir,
+    exec: mockExec(calls, {
+      failOn: { match: 'push', code: 128, stderr: `fatal: unable to access 'https://oauth2:${TEST_TOKEN}@github.com/example/private-config.git/': authentication failed` },
+    }),
+  }));
+  await assert.rejects(
+    transport.upload(sampleSnapshot()),
+    (err: unknown) => {
+      assert.ok(err instanceof GitTransportError);
+      assert.ok(!err.message.includes(TEST_TOKEN), `错误消息泄漏 token: ${err.message}`);
+      assert.match(err.message, /\[REDACTED\]/);
+      return true;
+    },
+  );
+});
+
+test('checkIsPrivate：匿名可达 → false；匿名失败+认证可达 → true；都失败 → 抛错', async (t) => {
+  // 匿名成功
+  const c1: CallRecord[] = [];
+  const t1 = new GitTransport(makeOptions({ workDir: await makeTempDir(t), exec: mockExec(c1) }));
+  assert.equal(await t1.checkIsPrivate(), false);
+  assert.equal(t1.isPrivateHint, false);
+
+  // 匿名失败（404），带 credential 成功
+  const c2: CallRecord[] = [];
+  const exec2: GitExecFn = async (_cmd, args) => {
+    c2.push({ cmd: 'git', args });
+    if (args.join(' ').includes('ls-remote')) {
+      const authed = args.some((a) => a.includes('credential.helper='));
+      return authed
+        ? { stdout: '', stderr: '', code: 0 }
+        : { stdout: '', stderr: 'fatal: could not read Username', code: 128 };
+    }
+    return { stdout: '', stderr: '', code: 0 };
+  };
+  const t2 = new GitTransport(makeOptions({ workDir: await makeTempDir(t), exec: exec2 }));
+  assert.equal(await t2.checkIsPrivate(), true);
+  assert.equal(t2.isPrivateHint, true);
+  // 第二次调用走缓存，不重复探测
+  const lsBefore = joinedArgs(c2, 'ls-remote').length;
+  await t2.checkIsPrivate();
+  assert.equal(joinedArgs(c2, 'ls-remote').length, lsBefore);
+
+  // 匿名与认证都失败
+  const c3: CallRecord[] = [];
+  const t3 = new GitTransport(makeOptions({
+    workDir: await makeTempDir(t),
+    exec: mockExec(c3, { codeBy: { 'ls-remote': 128 }, failOn: { match: 'credential.helper=', code: 128, stderr: 'fatal: could not read Username' } }),
+  }));
+  await assert.rejects(t3.checkIsPrivate(), /不可达|认证失败/);
+});
+
+test('快照 id 安全：非法 id（路径穿越/特殊字符）→ upload/download/delete 均拒绝', async (t) => {
+  const dir = await makeGitWorkDir(t);
+  const calls: CallRecord[] = [];
+  const transport = new GitTransport(makeOptions({ workDir: dir, exec: mockExec(calls) }));
+  for (const bad of ['../evil', 'a/b', 'a\\b', '.', '..', 'snap\ninject']) {
+    await assert.rejects(transport.upload(sampleSnapshot({ id: bad })), /非法快照 id/);
+    await assert.rejects(transport.download(bad), /非法快照 id/);
+    await assert.rejects(transport.delete(bad), /非法快照 id/);
+  }
+});
+
+/* ---------------- 集成测试（真实 git，本地 bare repo） ---------------- */
+
+test('集成：upload → list → download → delete 端到端（真实 git + 本地 bare repo）', async (t) => {
+  const bare = await makeBareRepo(t);
+  const workDir = await makeTempDir(t);
+  let tokenReads = 0;
+  const transport = new GitTransport({
+    repoUrl: bare,
+    workDir,
+    credentials: { getToken: async () => { tokenReads += 1; return TEST_TOKEN; } },
+  });
+
+  // upload
+  const snap = sampleSnapshot();
+  const meta = await transport.upload(snap);
+  assert.equal(meta.id, 'snap-001');
+  // 快照散文件目录落在工作副本
+  const manifestAbs = path.join(workDir, 'snapshots', 'snap-001', 'manifest.json');
+  const manifestRaw = JSON.parse(await fs.readFile(manifestAbs, 'utf8'));
+  assert.equal(manifestRaw.id, 'snap-001');
+  assert.equal(manifestRaw.createdAt, snap.createdAt);
+  // 分区文件落盘
+  assert.ok(await fs.stat(path.join(workDir, 'snapshots', 'snap-001', 'config', 'settings.json')));
+
+  // 提交已 push 到远端 bare repo
+  const log = await runRealGit(['log', '--oneline', '--all'], bare);
+  assert.equal(log.code, 0, `git log 失败: ${log.stderr}`);
+  assert.match(log.stdout, /sync: add snapshot snap-001/);
+
+  // list：远端 + 工作副本 → 1 条，createdAt 升序
+  const listed = await transport.list();
+  assert.equal(listed.length, 1);
+  assert.equal(listed[0]!.id, 'snap-001');
+  assert.equal(listed[0]!.createdAt, snap.createdAt);
+  assert.deepEqual(listed[0]!.manifest, snap.manifest);
+
+  // download：读回完整载荷，与上传一致
+  const roundtrip = await transport.download('snap-001');
+  assert.deepEqual(roundtrip, snap);
+
+  // 覆盖：同 id 上传新内容 → update commit，目录唯一
+  const snap2 = sampleSnapshot({ createdAt: '2026-08-16T14:00:00.000Z' });
+  snap2.sections.settings = { version: 1, namespaces: { general: { value: { theme: 'light' }, revision: 2, secrets: [] } } };
+  await transport.upload(snap2);
+  const dirs = await fs.readdir(path.join(workDir, 'snapshots'));
+  assert.deepEqual(dirs, ['snap-001']);
+  const log2 = await runRealGit(['log', '--oneline', '--all'], bare);
+  assert.match(log2.stdout, /sync: update snapshot snap-001/);
+  const roundtrip2 = await transport.download('snap-001');
+  assert.deepEqual(roundtrip2, snap2);
+
+  // delete：存在 → 移除；再 delete 不存在 id → 静默成功
+  await transport.delete('snap-001');
+  assert.equal((await transport.list()).length, 0);
+  const log3 = await runRealGit(['log', '--oneline', '--all'], bare);
+  assert.match(log3.stdout, /sync: delete snapshot snap-001/);
+  await transport.delete('snap-001'); // 不存在视为成功
+  await assert.rejects(transport.download('snap-001'), /不存在/);
+
+  // 本地路径仓库不触发认证读取（token 提供者不被调用）
+  assert.equal(tokenReads, 0, '本地仓库无需 token，getToken 不应被调用');
+});
+
+test('集成：token 不泄漏到快照文件内容与 commit message（真实 git 全链路）', async (t) => {
+  const bare = await makeBareRepo(t);
+  const workDir = await makeTempDir(t);
+  const transport = new GitTransport({
+    repoUrl: bare,
+    workDir,
+    credentials: { getToken: async () => TEST_TOKEN },
+  });
+  await transport.upload(sampleSnapshot());
+  // 工作副本 snapshots 下所有文件内容不得含 token
+  const files: string[] = [];
+  const walk = async (p: string): Promise<void> => {
+    for (const name of await fs.readdir(p)) {
+      const full = path.join(p, name);
+      const stat = await fs.stat(full);
+      if (stat.isDirectory()) await walk(full);
+      else files.push(full);
+    }
+  };
+  await walk(path.join(workDir, 'snapshots'));
+  for (const f of files) {
+    const content = await fs.readFile(f, 'utf8');
+    assert.ok(!content.includes(TEST_TOKEN), `文件内容泄漏 token: ${f}`);
+  }
+  // commit message 不含 token
+  const log = await runRealGit(['log', '--format=%s', '--all'], bare);
+  assert.ok(!log.stdout.includes(TEST_TOKEN), `commit message 泄漏 token: ${log.stdout}`);
+  // 工作副本根目录无 credential 残留文件
+  const rootEntries = await fs.readdir(workDir);
+  assert.ok(!rootEntries.some((n) => n.includes('cred') || n.includes('dsh-git-cred')), `credential 残留: ${rootEntries.join(', ')}`);
+});
+
+test('集成：非 git 仓库报错清晰（真实 git 验证消息）', async (t) => {
+  const workDir = await makeTempDir(t);
+  await fs.writeFile(path.join(workDir, 'placeholder.txt'), 'x');
+  const transport = new GitTransport({
+    repoUrl: 'https://github.com/example/private-config.git',
+    workDir,
+    credentials: { getToken: async () => TEST_TOKEN },
+  });
+  await assert.rejects(
+    transport.list(),
+    (err: unknown) => {
+      assert.ok(err instanceof GitTransportError);
+      assert.match(err.message, /不是 git 仓库/);
+      return true;
+    },
+  );
+});
+
+test('集成：list 按 createdAt 升序（真实 git 多快照）', async (t) => {
+  const bare = await makeBareRepo(t);
+  const workDir = await makeTempDir(t);
+  const transport = new GitTransport({ repoUrl: bare, workDir, credentials: { getToken: async () => TEST_TOKEN } });
+  await transport.upload(sampleSnapshot({ id: 'snap-b', createdAt: '2026-08-16T11:00:00.000Z' }));
+  await transport.upload(sampleSnapshot({ id: 'snap-a', createdAt: '2026-08-16T09:00:00.000Z' }));
+  await transport.upload(sampleSnapshot({ id: 'snap-c', createdAt: '2026-08-16T12:00:00.000Z' }));
+  const listed = await transport.list();
+  assert.deepEqual(listed.map((m) => m.id), ['snap-a', 'snap-b', 'snap-c']);
+});