dsh-config-manager 0.1.78 → 0.1.80

package/src/sync/gist/gist-conditional-write.test.ts

@@ -0,0 +1,203 @@
+/**
+ * GitHub Gist 通道：本轮借鉴项的**针对性**单测（不重复 gist-transport.test.ts 的既有契约）。
+ *  - ① **不做条件写**（issue #110，2026-10 实测）：`PATCH /gists/{id}` 对任何条件请求头都回 400
+ *    （`Conditional request headers are not allowed in unsafe requests unless supported by the endpoint`），
+ *    与 ETag 强弱无关 ⇒ PATCH 恒不带 if-match（upload 与 delete 两条路径都要钉住）；
+ *  - ② 探针：GET /user 证明令牌有效 → 读 gist → snapshotCount + 非本前缀文件数进 hint（只读，零 PATCH）。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { GistTransport, GistTransportError, GIST_DEFAULT_FILE_PREFIX } from './gist-transport.ts';
+import type { GistRequestFn, GistResponse, GistTransportOptions } from './gist-transport.ts';
+import type { SyncSnapshot } from '../transport.ts';
+import { gistMsg } from './messages.ts';
+
+const GIST_ID = 'aa5a315d61ae9438b18d';
+const TOKEN = 'ghp_ExampleTokenValueThatMustNeverLeak123456';
+const API = 'https://api.github.com';
+const GIST_URL = API + '/gists/' + GIST_ID;
+const INDEX_FILE = GIST_DEFAULT_FILE_PREFIX + '-index.json';
+/** 任何条件请求头（出现即说明破坏了 gist 端点的约束） */
+const CONDITIONAL_HEADERS = ['if-match', 'if-none-match', 'if-modified-since', 'if-unmodified-since'];
+
+interface GistCall { method: string; url: string; headers: Record<string, string>; body?: string }
+
+function res(status: number, bodyText = '', headers?: Record<string, string>): GistResponse {
+  return {
+    status,
+    ok: status >= 200 && status < 300,
+    ...(headers !== undefined ? { headers } : {}),
+    async text() { return bodyText; },
+  };
+}
+
+function record(calls: GistCall[], handler: (m: GistCall) => GistResponse): GistRequestFn {
+  return async (method, url, opts = {}) => {
+    const rec: GistCall = { method, url, headers: opts.headers ?? {}, ...(opts.body !== undefined ? { body: opts.body } : {}) };
+    calls.push(rec);
+    return handler(rec);
+  };
+}
+
+function makeOptions(request: GistRequestFn, overrides: Partial<GistTransportOptions> = {}): GistTransportOptions {
+  return {
+    gistId: GIST_ID,
+    credentials: { getToken: async () => TOKEN },
+    request,
+    ...overrides,
+  };
+}
+
+function sampleSnapshot(overrides: Partial<SyncSnapshot> = {}): SyncSnapshot {
+  return {
+    id: 'snap-001',
+    createdAt: '2026-10-18T10: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: 1, secrets: [] } } },
+    },
+    ...overrides,
+  };
+}
+
+const patches = (calls: GistCall[]): GistCall[] => calls.filter((c) => c.method === 'PATCH');
+
+/** 断言：本次 PATCH 一个条件头都没带（回归 issue #110） */
+function assertNoConditionalHeaders(call: GistCall | undefined, hint: string): void {
+  assert.ok(call !== undefined, hint + '：必须发生 PATCH');
+  const present = CONDITIONAL_HEADERS.filter((h) => call.headers[h] !== undefined);
+  assert.deepEqual(present, [], hint + '：gist 端点拒绝任何条件请求头，带了就会 400');
+}
+
+/* ---------------- ① 不做条件写 ---------------- */
+
+test('不做条件写①：强 ETag 也不得注入 if-match（issue #110 回归，带条件头 GitHub 回 400）', async () => {
+  const calls: GistCall[] = [];
+  const t = new GistTransport(makeOptions(record(calls, (m) => {
+    if (m.method === 'GET' && m.url === GIST_URL) return res(200, JSON.stringify({ files: {} }), { etag: '"strong-etag-1"' });
+    if (m.method === 'PATCH' && m.url === GIST_URL) return res(200, '{}');
+    return res(500, 'unexpected ' + m.method + ' ' + m.url);
+  })));
+
+  await t.upload(sampleSnapshot());
+
+  const patched = patches(calls);
+  assert.equal(patched.length, 1, '必须发生且只发生一次 PATCH');
+  assertNoConditionalHeaders(patched[0], '强 ETag');
+});
+
+test('不做条件写①：弱 ETag（W/…）同样不带 if-match，写入照常发生', async () => {
+  const calls: GistCall[] = [];
+  const t = new GistTransport(makeOptions(record(calls, (m) => {
+    if (m.method === 'GET' && m.url === GIST_URL) return res(200, JSON.stringify({ files: {} }), { etag: 'W/"weak-etag-1"' });
+    if (m.method === 'PATCH' && m.url === GIST_URL) return res(200, '{}');
+    return res(500, 'unexpected ' + m.method + ' ' + m.url);
+  })));
+
+  await t.upload(sampleSnapshot());
+
+  const patched = patches(calls);
+  assert.equal(patched.length, 1, '弱/强 ETag 都不影响写入发生');
+  assertNoConditionalHeaders(patched[0], '弱 ETag');
+});
+
+test('不做条件写①（删除路径）：强 ETag 下 delete 的 PATCH 也不带 if-match', async () => {
+  const snapshotFile = GIST_DEFAULT_FILE_PREFIX + '-snap-001.json';
+  const meta = {
+    id: 'snap-001',
+    createdAt: '2026-10-18T09:00:00.000Z',
+    sections: {},
+    manifest: { schemaVersion: 1, dshVersion: '1', platform: 'win32', sectionIds: [], containsSecrets: false },
+  };
+  const files = { [INDEX_FILE]: { content: JSON.stringify([meta]) }, [snapshotFile]: { content: '{}' } };
+  const calls: GistCall[] = [];
+  const t = new GistTransport(makeOptions(record(calls, (m) => {
+    if (m.method === 'GET' && m.url === GIST_URL) return res(200, JSON.stringify({ files }), { etag: '"strong-del-1"' });
+    if (m.method === 'PATCH' && m.url === GIST_URL) return res(200, '{}');
+    return res(500, 'unexpected ' + m.method + ' ' + m.url);
+  })));
+
+  await t.delete('snap-001');
+
+  const patched = patches(calls);
+  assert.equal(patched.length, 1);
+  assertNoConditionalHeaders(patched[0], '删除路径');
+});
+
+/* ---------------- ② 探针 ---------------- */
+
+test('② 探针：gist 里有非本前缀文件 → hint 非空且含前缀与计数；snapshotCount 正确', async () => {
+  const calls: GistCall[] = [];
+  const meta = {
+    id: 'snap-a',
+    createdAt: '2026-10-18T08:00:00.000Z',
+    sections: {},
+    manifest: { schemaVersion: 1, dshVersion: '1', platform: 'win32', sectionIds: [], containsSecrets: false },
+  };
+  const t = new GistTransport(makeOptions(record(calls, (m) => {
+    if (m.method === 'GET' && m.url === API + '/user') return res(200, JSON.stringify({ login: 'alice' }));
+    if (m.method === 'GET' && m.url === GIST_URL) {
+      return res(200, JSON.stringify({
+        files: {
+          [INDEX_FILE]: { content: JSON.stringify([meta]) },
+          'notes.md': { content: '别人的文件' },
+        },
+      }));
+    }
+    return res(500, 'unexpected ' + m.method + ' ' + m.url);
+  })));
+
+  const result = await t.probe();
+
+  assert.equal(result.snapshotCount, 1, '索引里 1 份快照');
+  assert.equal(result.message, gistMsg('sync.gist.probeOk', { count: '1' }));
+  assert.ok(result.hint !== undefined && result.hint !== '', '有非本前缀文件时必须给出 hint');
+  assert.equal(result.hint, gistMsg('sync.gist.probeForeignContent', { count: '1', prefix: GIST_DEFAULT_FILE_PREFIX }));
+  assert.match(result.hint!, /dsh-sync/, 'hint 必须点明本插件前缀');
+  assert.equal(patches(calls).length, 0, '探针只读：绝不发 PATCH');
+});
+
+test('② 探针：gist 里全是本前缀文件 → hint 省略（不误报「别人的数据」）', async () => {
+  const calls: GistCall[] = [];
+  const t = new GistTransport(makeOptions(record(calls, (m) => {
+    if (m.method === 'GET' && m.url === API + '/user') return res(200, JSON.stringify({ login: 'alice' }));
+    if (m.method === 'GET' && m.url === GIST_URL) {
+      return res(200, JSON.stringify({ files: { [INDEX_FILE]: { content: '[]' } } }));
+    }
+    return res(500, 'unexpected ' + m.method + ' ' + m.url);
+  })));
+
+  const result = await t.probe();
+  assert.equal(result.hint, undefined);
+  assert.equal(result.snapshotCount, 0);
+  assert.equal(result.message, gistMsg('sync.gist.probeOk', { count: '0' }));
+});
+
+test('② 探针：GET /user 401/403 → 抛错（kind=auth），绝不谎报令牌有效', async () => {
+  for (const status of [401, 403]) {
+    const calls: GistCall[] = [];
+    const t = new GistTransport(makeOptions(record(calls, (m) => {
+      if (m.method === 'GET' && m.url === API + '/user') return res(status, 'bad credentials');
+      return res(500, 'unexpected ' + m.method + ' ' + m.url);
+    })));
+
+    await assert.rejects(
+      () => t.probe(),
+      (err: unknown) => {
+        assert.ok(err instanceof GistTransportError);
+        assert.equal(err.kind, 'auth');
+        assert.equal(err.status, status);
+        assert.equal(err.message.includes(TOKEN), false, 'token 绝不进错误消息');
+        return true;
+      },
+    );
+    assert.equal(calls.some((c) => c.url === GIST_URL), false, '令牌校验失败后不得继续读 gist');
+  }
+});

package/src/sync/gist/gist-transport.ts

@@ -33,7 +33,7 @@ import {
   sectionsEqual, SyncTransportError, withSyncRetry,
 } from '../transport.ts';
 import type {
-  SyncRetryOptions, SyncSnapshot, SyncSnapshotMeta, SyncTransport, SyncTransportErrorOptions,
+  SyncProbeResult, SyncRetryOptions, SyncSnapshot, SyncSnapshotMeta, SyncTransport, SyncTransportErrorOptions,
 } from '../transport.ts';
 import { gistMsg } from './messages.ts';
 import { composeMsg } from '../s3/messages.ts';
@@ -55,6 +55,13 @@ const MAX_REDIRECTS = 3;
 const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
 const REDACTED = '[REDACTED]';
 
+/**
+ * **gist 通道不做条件写**（issue #110，2026-10 实测）：`PATCH /gists/{id}` 对**任何**条件请求头
+ * 都直接回 400 —— `Conditional request headers are not allowed in unsafe requests unless supported
+ * by the endpoint`，与 ETag 强弱无关（同一请求去掉 If-Match 即 200）。故本通道的 PATCH 一律不带
+ * `If-Match`，也**没有**写前并发保护；要并发保护请用 git / webdav / s3 通道（那里的索引写是条件写）。
+ */
+
 /** 请求选项：headers / body / 覆盖默认超时（ms；0 = 不超时） */
 export interface GistRequestOptions {
   headers?: Record<string, string>;
@@ -229,7 +236,7 @@ export class GistTransport implements SyncTransport {
     this.assertSafeId(snapshot.id);
     const token = await this.tokenOnce();
     const meta = computeSnapshotMeta(snapshot);
-    const files = await this.readGistFiles(token);
+    const { files } = await this.readGist(token);
     const idxRaw = await this.readFileText(files, this.indexFileName, token);
     const idxBefore = idxRaw === null ? [] : this.parseIndex(idxRaw, this.gistUrl(), token);
     const existing = idxBefore.find((m) => m.id === snapshot.id);
@@ -284,7 +291,7 @@ export class GistTransport implements SyncTransport {
   async delete(id: string): Promise<void> {
     this.assertSafeId(id);
     const token = await this.tokenOnce();
-    const files = await this.readGistFiles(token);
+    const { files } = await this.readGist(token);
     const idxRaw = await this.readFileText(files, this.indexFileName, token);
     const idx = idxRaw === null ? [] : this.parseIndex(idxRaw, this.gistUrl(), token);
     const fileName = this.snapshotFileName(id);
@@ -308,6 +315,37 @@ export class GistTransport implements SyncTransport {
 
   /* ---------------- 内部实现 ---------------- */
 
+  /**
+   * 连通性探针（cloud-sync 借鉴项 ②③）：令牌有效性（GET /user）→ gist 可读 → 快照数 →
+   * 归属提示（gist 里已有不属于本前缀的文件时给出 warning 级 hint，绝不自动删别人的文件）。
+   * 只读：不打任何 PATCH。
+   */
+  async probe(): Promise<SyncProbeResult> {
+    const token = await this.tokenOnce();
+    const userUrl = this.o.apiBaseUrl + '/user';
+    const me = await this.send('GET', userUrl, token);
+    if (me.status === 401 || me.status === 403) {
+      const body = await this.safeText(me);
+      throw new GistTransportError(await this.failText('GET', userUrl, me, token, body), this.classify(me.status, body));
+    }
+    if (!me.ok) {
+      const body = await this.safeText(me);
+      throw new GistTransportError(await this.failText('GET', userUrl, me, token, body), this.classify(me.status, body));
+    }
+    const { files } = await this.readGist(token);
+    const idxRaw = await this.readFileText(files, this.indexFileName, token);
+    const count = idxRaw === null ? 0 : this.parseIndex(idxRaw, this.gistUrl(), token).length;
+    const prefix = this.o.filePrefix + '-';
+    const foreign = Object.keys(files).filter((name) => !name.startsWith(prefix)).length;
+    return {
+      message: this.o.msg('sync.gist.probeOk', { count: String(count) }),
+      snapshotCount: count,
+      ...(foreign > 0
+        ? { hint: this.o.msg('sync.gist.probeForeignContent', { count: String(foreign), prefix: this.o.filePrefix }) }
+        : {}),
+    };
+  }
+
   private assertSafeId(id: string): void {
     if (typeof id !== 'string' || !SAFE_ID_RE.test(id) || RESERVED_IDS.has(id)) {
       throw new GistTransportError(this.o.msg('sync.gist.invalidSnapshotId', { id: JSON.stringify(id) }));
@@ -336,7 +374,7 @@ export class GistTransport implements SyncTransport {
     method: string,
     url: string,
     token: string,
-    opts: { body?: string; raw?: boolean } = {},
+    opts: { body?: string; raw?: boolean; headers?: Record<string, string> } = {},
   ): Promise<GistResponse> {
     const headers: Record<string, string> = opts.raw === true
       ? { accept: 'application/vnd.github.raw', 'User-Agent': 'DSH-Config-Manager (Gist Client)' }
@@ -345,6 +383,8 @@ export class GistTransport implements SyncTransport {
         'content-type': 'application/json',
         'X-GitHub-Api-Version': GITHUB_API_VERSION,
         ...(token !== '' ? { authorization: 'Bearer ' + token } : {}),
+        // 附加请求头（本通道当前不注入条件头：gist 端点拒绝任何条件请求头，见文首说明）
+        ...(opts.headers ?? {}),
       };
     try {
       return await this.o.request(method, url, {
@@ -371,6 +411,14 @@ export class GistTransport implements SyncTransport {
 
   /** 读 gist（含全部文件条目）；404 → 明确「gist 不存在或无权访问」 */
   private async readGistFiles(token: string): Promise<Record<string, GistFileEntry>> {
+    return (await this.readGist(token)).files;
+  }
+
+  /**
+   * 读 gist 全量文件。响应 ETag **不用**：gist 的 PATCH 端点不接受任何条件请求头（issue #110 实测），
+   * 读到强/弱 ETag 都无处可用，故这里不再解析。
+   */
+  private async readGist(token: string): Promise<{ files: Record<string, GistFileEntry> }> {
     const url = this.gistUrl();
     const res = await this.send('GET', url, token);
     if (res.status === 404) {
@@ -399,7 +447,7 @@ export class GistTransport implements SyncTransport {
         { kind: 'protocol', retryable: false },
       );
     }
-    return files as Record<string, GistFileEntry>;
+    return { files: files as Record<string, GistFileEntry> };
   }
 
   /**

package/src/sync/gist/messages.ts

@@ -24,6 +24,9 @@ export const gistZh = {
   'sync.gist.timeout': '{method} {url} 请求超时（{timeout}ms）',
   'sync.gist.indexInvalid': '{url} 解析失败或结构非法: {err}',
   'sync.gist.snapshotInvalid': '快照 {id} 解析失败或结构非法: {err}',
+  // ---- cloud-sync 借鉴项 ②③：探针 / 归属提示（①条件写已按 issue #110 移除，见 gist-transport.ts）----
+  'sync.gist.probeOk': '连接正常（Gist 可读写，远端 {count} 份快照）',
+  'sync.gist.probeForeignContent': '该 Gist 里已有 {count} 个不属于本插件的文件：请确认这是你的同步专用 Gist（前缀 {prefix}），否则可能覆盖别人的数据',
 } as const;
 
 export const gistEn: Record<keyof typeof gistZh, string> = {
@@ -43,6 +46,8 @@ export const gistEn: Record<keyof typeof gistZh, string> = {
   'sync.gist.timeout': '{method} {url} request timed out ({timeout}ms)',
   'sync.gist.indexInvalid': '{url} failed to parse or is structurally invalid: {err}',
   'sync.gist.snapshotInvalid': 'Snapshot {id} failed to parse or is structurally invalid: {err}',
+  'sync.gist.probeOk': 'Connection OK (gist readable and writable, {count} remote snapshots)',
+  'sync.gist.probeForeignContent': 'This gist already contains {count} files that are not ours: confirm it is your dedicated sync gist (prefix {prefix}) or you may overwrite someone else’s data',
 };
 
 /** 缺省（zh）Gist 通道翻译器。 */

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

@@ -0,0 +1,80 @@
+/**
+ * git 通道的连通性探针（cloud-sync 借鉴项 ②，补齐四条通道）。
+ *
+ * 真机背景：git 通道此前没有 probe()，同步页点「测试连接」会得到红色「当前同步通道不支持连通性自检」——
+ * 用户看到的是「操作失败」，而实际只是那条通道没实现自检。本文件钉住修复后的行为：
+ *  - 只读：仅发 ls-remote（不 clone / 不 fetch / 不碰工作副本）；
+ *  - 匿名成功 = 公开仓库可达；匿名失败 + 带凭据成功 = 私有仓库且凭据可用；
+ *  - 两者都失败 → 抛可操作错误，token 绝不出现在消息里；
+ *  - 刻意不报 snapshotCount（统计快照要先 fetch 工作副本 = 写本地状态）。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { GitTransport, GitTransportError } from './git-transport.ts';
+import type { GitExecFn, GitExecResult, GitTransportOptions } from './git-transport.ts';
+import { zhMsg } from '../../core/messages.ts';
+import { engineMsg } from '../messages.ts';
+
+const TOKEN = 'secret-token-probe-001';
+const REPO = 'https://github.com/example/private-config.git';
+
+function execStub(responder: (call: number, args: string[]) => GitExecResult): { fn: GitExecFn; calls: string[][] } {
+  const calls: string[][] = [];
+  let n = 0;
+  const fn: GitExecFn = async (_cmd, args) => {
+    n += 1;
+    calls.push(args);
+    return responder(n, args);
+  };
+  return { fn, calls };
+}
+
+function options(exec: GitExecFn, overrides: Partial<GitTransportOptions> = {}): GitTransportOptions {
+  return {
+    repoUrl: REPO,
+    workDir: 'UNUSED-BY-PROBE',
+    credentials: { getToken: async () => TOKEN },
+    exec,
+    ...overrides,
+  };
+}
+
+test('git probe：匿名 ls-remote 成功 → 连接正常，且**只**发这一条命令（只读）', async () => {
+  const { fn, calls } = execStub(() => ({ stdout: '', stderr: '', code: 0 }));
+  const transport = new GitTransport(options(fn));
+  const result = await transport.probe();
+  assert.equal(result.message, engineMsg('sync.git.probeOk'));
+  assert.equal(result.snapshotCount, undefined, '不得报快照数（统计它需要 fetch 工作副本）');
+  assert.deepEqual(result.createdCollections ?? [], [], 'git 通道不在远端建目录');
+  assert.equal(calls.length, 1, '探针只准发一条 ls-remote');
+  assert.deepEqual(calls[0], ['ls-remote', REPO]);
+});
+
+test('git probe：匿名被拒、带凭据成功 → 连接正常（私有仓库 + 凭据可用）', async () => {
+  const { fn, calls } = execStub((n) => (n === 1
+    ? { stdout: '', stderr: 'fatal: could not read Username', code: 128 }
+    : { stdout: '', stderr: '', code: 0 }));
+  const transport = new GitTransport(options(fn));
+  const result = await transport.probe();
+  assert.equal(result.message, engineMsg('sync.git.probeOk'));
+  assert.equal(calls.length, 2, '匿名 + 带凭据各一次 ls-remote');
+  assert.ok(calls.every((args) => args.includes('ls-remote')));
+});
+
+test('git probe：两者都失败 → 抛可操作错误，且 **token 不出现**在消息里', async () => {
+  const { fn } = execStub(() => ({ stdout: '', stderr: `fatal: Authentication failed for '${TOKEN}'`, code: 128 }));
+  const transport = new GitTransport(options(fn));
+  await assert.rejects(
+    async () => { await transport.probe(); },
+    (err: unknown) => {
+      assert.ok(err instanceof GitTransportError, '必须是通道错误（供上层分类）');
+      const message = (err as Error).message;
+      // 文案 = 既有字典键（URL 经通道自带的 mask 处理，不出现原始地址）
+      assert.equal(message, zhMsg('sync.git.repoUnreachable', { url: '[REPO_URL]' }));
+      assert.ok(!message.includes(TOKEN), 'token 绝不进错误消息');
+      assert.ok(!message.includes(REPO), '远端地址按通道口径脱敏');
+      return true;
+    },
+  );
+});

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

@@ -211,6 +211,39 @@ test('token 不泄漏：credential 文件在 git 调用期间存在、用后删
   for (const c of calls) for (const arg of c.args) assert.ok(!arg.includes(TEST_TOKEN), `argv 泄漏 token: ${arg}`);
 });
 
+test('issue #103：credential.username 必须与 store 文件里的用户名一致（全局 .gitconfig 不得顶掉查找键）', async (t) => {
+  // git credential store 以 URL 里的 username 为查找键；只写 store 文件不钉 username 时，
+  // 全局 .gitconfig 的 credential.<url>.username（GCM / gh 写入）会把键换成别的用户名 →
+  // 查不到口令 → 无 tty 环境直接 fatal。这里把「pin 的值 === store 文件里的用户名」钉成不变量。
+  for (const username of [undefined, 'x-access-token']) {
+    const dir = await makeTempDir(t);
+    const seen: { args: string[]; fileRaw: string }[] = [];
+    const exec: GitExecFn = async (_cmd, 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, '');
+        seen.push({ args, fileRaw: await fs.readFile(file, 'utf8') });
+      }
+      return { stdout: '', stderr: '', code: 0 };
+    };
+    const transport = new GitTransport(makeOptions({
+      workDir: dir,
+      exec,
+      ...(username === undefined ? {} : { credentialUsername: username }),
+    }));
+    await transport.list();
+    assert.ok(seen.length >= 1, '必须发生过带凭据的调用');
+    const expected = username ?? 'oauth2';
+    for (const call of seen) {
+      const pin = call.args.find((a) => a.startsWith('credential.username='));
+      assert.equal(pin, `credential.username=${expected}`, '必须把 username 钉进 git 参数（缺省 oauth2，可用 credentialUsername 覆盖）');
+      const idx = call.args.indexOf(pin as string);
+      assert.equal(call.args[idx - 1], '-c', 'git 只认 `-c key=value` 形态，-c 必须紧邻');
+      assert.ok(call.fileRaw.startsWith(`https://${expected}:`), 'store 文件里的用户名必须与 pin 的值同源');
+    }
+  }
+});
+
 test('upload 契约：写快照目录 + add + commit(add) + push，返回 computeSnapshotMeta', async (t) => {
   const dir = await makeGitWorkDir(t);
   const calls: CallRecord[] = [];
@@ -1079,6 +1112,8 @@ test('issue #79 集成：inspectWorkDir + rebuildWorkDir（relink 非破坏 / re
   assert.equal(after.origin, bare);
   assert.equal(after.ahead, 0, 'relink 不丢弃/不产生本地提交');
   assert.equal(after.dirty, false, 'relink 不动工作树');
+  // issue #104 建议 3：detail 自检必须同时数出远端分支上的快照（预警依据）
+  assert.equal(after.remoteSnapshots, 1, 'detail 自检数出远端分支上的 1 个快照');
 
   await transport.rebuildWorkDir('reclone');
   assert.ok((await fs.stat(path.join(workDir, '.git'))).isDirectory(), 'reclone 后重新 clone 出 .git');
@@ -1091,3 +1126,153 @@ test('issue #79 集成：inspectWorkDir + rebuildWorkDir（relink 非破坏 / re
   await assert.rejects(t3.rebuildWorkDir('reclone'), /不是 git 仓库/);
   assert.ok(await fs.stat(path.join(strayDir, 'stray.txt')), '拒绝时文件必须原样保留');
 });
+/* ---------------------------------------------------------------- issue #104 采纳远端历史（adopt） */
+
+/**
+ * 造一个「另一条历史」的同步仓库：同一个插件布局，但初始提交与现有工作副本不相交。
+ * adopt 的判据是「远端顶层只有快照布局」+「合并原始历史」，所以夹具必须是**假远端**（bare 仓）。
+ */
+async function makeSyncRemote(t: test.TestContext, snapshot: SyncSnapshot & { sections: Record<string, unknown> }): Promise<string> {
+  const bare = await makeBareRepo(t);
+  const workDir = await makeTempDir(t);
+  await new GitTransport({ repoUrl: bare, workDir, credentials: { getToken: async () => TEST_TOKEN } }).upload(snapshot);
+  return bare;
+}
+
+test('issue #104 集成：改成另一条历史的同步仓库 → adopt 合并两条历史（本地提交原样保留、之后能继续 push）', async (t) => {
+  const creds = { getToken: async () => TEST_TOKEN };
+  const bareA = await makeBareRepo(t);
+  const workDir = await makeTempDir(t);
+  await new GitTransport({ repoUrl: bareA, workDir, credentials: creds }).upload(sampleSnapshot({ id: 'snap-001' }));
+
+  const bareC = await makeSyncRemote(t, sampleSnapshot({ id: 'snap-other' }));
+  const localHead = (await runRealGit(['rev-parse', 'HEAD'], workDir)).stdout.trim();
+  const transport = new GitTransport({ repoUrl: bareC, workDir, credentials: creds });
+
+  // 先确认这就是 issue #104 的现场：改地址后 pull --ff-only 因两条历史不相交而失败
+  await assert.rejects(transport.list(), (err: unknown) => {
+    assert.ok(err instanceof SyncTransportError);
+    assert.match(err.message, /不是同一条历史/);
+    return true;
+  });
+
+  await transport.rebuildWorkDir('adopt');
+
+  const facts = await transport.inspectWorkDir({ detail: true });
+  assert.equal(facts.match, true, 'adopt 后 origin 跟随当前配置地址');
+  assert.equal(facts.dirty, false, 'adopt 不留下工作树脏改动');
+  // 2 = 本地原提交（此前只推到过旧地址）+ 这次合并提交：两条都还不在当前地址上，merge 之后需要一次 push。
+  // 断言精确值而不是「>0」：若哪天实现偷偷 rebase 或 force-push，这里会先红。
+  assert.equal(facts.ahead, 2, '本地原提交与合并提交都尚未推到当前地址');
+
+  assert.ok(await fs.stat(path.join(workDir, 'snapshots', 'snap-001')), '本地已有快照保留（不是 reclone）');
+  assert.ok(await fs.stat(path.join(workDir, 'snapshots', 'snap-other')), '远端快照被合并进来');
+
+  const merged = await runRealGit(['log', '--merges', '--oneline'], workDir);
+  assert.match(merged.stdout, /Merge/, '走 merge 而不是 rebase ⇒ 历史里能看到合并提交');
+  const kept = await runRealGit(['merge-base', '--is-ancestor', localHead, 'HEAD'], workDir);
+  assert.equal(kept.code, 0, '本地原提交必须原样保留（rebase 会改写 sha，此断言会红）');
+
+  // adopt 之后普通 push 可用：新快照写进当前地址，旧地址收不到
+  await transport.upload(sampleSnapshot({ id: 'snap-003' }));
+  // issue #104 建议 3 的两个数字必须跟着推送一起收敛：领先 0、远端快照 2
+  const pushed = await transport.inspectWorkDir({ detail: true });
+  assert.equal(pushed.ahead, 0, '推送成功后不再领先远端');
+  // 3 = snap-001（本地历史随合并一起推上去）+ snap-other + snap-003：远端快照数是「远端分支上真实有的」
+  assert.equal(pushed.remoteSnapshots, 3, '远端快照数跟着推送更新（snap-001 + snap-other + snap-003）');
+  const logC = await runRealGit(['log', '--oneline', '--all'], bareC);
+  assert.match(logC.stdout, /snap-003/, '合并后下游能继续 push');
+  const logA = await runRealGit(['log', '--oneline', '--all'], bareA);
+  assert.ok(!logA.stdout.includes('snap-003'), '旧地址不得再收到（否则仍在用旧 origin）');
+});
+
+test('issue #104 集成：远端顶层不是同步布局 → 拒绝合并，且一个字节历史都不动', async (t) => {
+  const creds = { getToken: async () => TEST_TOKEN };
+  const bareA = await makeBareRepo(t);
+  const workDir = await makeTempDir(t);
+  await new GitTransport({ repoUrl: bareA, workDir, credentials: creds }).upload(sampleSnapshot({ id: 'snap-001' }));
+  const localHead = (await runRealGit(['rev-parse', 'HEAD'], workDir)).stdout.trim();
+  const branch = (await runRealGit(['rev-parse', '--abbrev-ref', 'HEAD'], workDir)).stdout.trim();
+
+  // 一个普通代码仓库（顶层是 README.md）：把它的历史合进来 = 把别人的仓库搬进工作副本
+  const bareOther = await makeBareRepo(t);
+  const seed = await makeTempDir(t);
+  await runRealGit(['init'], seed);
+  await runRealGit(['config', 'user.name', 'test'], seed);
+  await runRealGit(['config', 'user.email', 'test@local'], seed);
+  await runRealGit(['checkout', '-B', branch], seed);
+  await fs.writeFile(path.join(seed, 'README.md'), '# notes\n');
+  await runRealGit(['add', '.'], seed);
+  await runRealGit(['commit', '-m', 'unrelated'], seed);
+  await runRealGit(['remote', 'add', 'origin', bareOther], seed);
+  const pushed = await runRealGit(['push', '-u', 'origin', branch], seed);
+  assert.equal(pushed.code, 0, `push 失败: ${pushed.stderr}`);
+
+  const transport = new GitTransport({ repoUrl: bareOther, workDir, credentials: creds });
+  await assert.rejects(transport.rebuildWorkDir('adopt'), (err: unknown) => {
+    assert.ok(err instanceof SyncTransportError);
+    assert.match(err.message, /README\.md/, '必须点出到底撞见了什么（可操作）');
+    assert.match(err.message, /不是本插件的同步仓库/);
+    assert.equal(err.retryable, false, '重试不会自愈');
+    return true;
+  });
+
+  const head = (await runRealGit(['rev-parse', 'HEAD'], workDir)).stdout.trim();
+  assert.equal(head, localHead, '拒绝时历史一步都不许动');
+  await assert.rejects(fs.stat(path.join(workDir, '.git', 'MERGE_HEAD')), '不得留下半截合并');
+  const status = await runRealGit(['status', '--porcelain'], workDir);
+  assert.equal(status.stdout.trim(), '', '拒绝后工作树保持干净');
+});
+
+test('issue #104 集成：工作副本有未提交改动 → 拒绝 adopt（不替用户丢改动）', async (t) => {
+  const creds = { getToken: async () => TEST_TOKEN };
+  const bareA = await makeBareRepo(t);
+  const workDir = await makeTempDir(t);
+  await new GitTransport({ repoUrl: bareA, workDir, credentials: creds }).upload(sampleSnapshot({ id: 'snap-001' }));
+  const localHead = (await runRealGit(['rev-parse', 'HEAD'], workDir)).stdout.trim();
+
+  const bareC = await makeSyncRemote(t, sampleSnapshot({ id: 'snap-other' }));
+  await fs.writeFile(path.join(workDir, 'notes.txt'), 'wip\n');
+
+  const transport = new GitTransport({ repoUrl: bareC, workDir, credentials: creds });
+  await assert.rejects(transport.rebuildWorkDir('adopt'), (err: unknown) => {
+    assert.ok(err instanceof SyncTransportError);
+    assert.match(err.message, /未提交的改动/, '说清为什么拒绝');
+    return true;
+  });
+
+  assert.ok(await fs.stat(path.join(workDir, 'notes.txt')), '用户的文件必须原样保留');
+  const head = (await runRealGit(['rev-parse', 'HEAD'], workDir)).stdout.trim();
+  assert.equal(head, localHead, '被拒绝时不得 merge 任何东西');
+});
+
+test('issue #104 集成：两侧同名快照内容不同 → 合并冲突自动撤销，工作副本回到操作前', async (t) => {
+  const creds = { getToken: async () => TEST_TOKEN };
+  const bareA = await makeBareRepo(t);
+  const workDir = await makeTempDir(t);
+  const manifestA = { schemaVersion: 1, dshVersion: '1.0.0', platform: 'win32' as const, sectionIds: ['settings' as SectionId], containsSecrets: false };
+  await new GitTransport({ repoUrl: bareA, workDir, credentials: creds })
+    .upload(sampleSnapshot({ id: 'snap-c', manifest: manifestA }));
+
+  // 同一个快照 id、不同 manifest.json 内容 ⇒ 合并时 add/add 冲突
+  const bareC = await makeSyncRemote(t, sampleSnapshot({
+    id: 'snap-c',
+    manifest: { ...manifestA, dshVersion: '9.9.9' },
+  }));
+  const localHead = (await runRealGit(['rev-parse', 'HEAD'], workDir)).stdout.trim();
+
+  const transport = new GitTransport({ repoUrl: bareC, workDir, credentials: creds });
+  await assert.rejects(transport.rebuildWorkDir('adopt'), (err: unknown) => {
+    assert.ok(err instanceof SyncTransportError);
+    assert.match(err.message, /合并远端 .* 时发生冲突/);
+    assert.match(err.message, /已撤销这次合并/);
+    return true;
+  });
+
+  await assert.rejects(fs.stat(path.join(workDir, '.git', 'MERGE_HEAD')), 'merge --abort 后不得残留 MERGE_HEAD');
+  const status = await runRealGit(['status', '--porcelain'], workDir);
+  assert.equal(status.stdout.trim(), '', '撤销后工作树必须干净（冲突标记不得留在文件里）');
+  const head = (await runRealGit(['rev-parse', 'HEAD'], workDir)).stdout.trim();
+  assert.equal(head, localHead, '撤销后 HEAD 必须回到操作前的提交');
+});
+