dsh-config-manager 0.1.69 → 0.1.71

package/src/routes/foreign.test.ts

@@ -0,0 +1,443 @@
+/**
+ * `GET /api/dsh-config-manager/foreign-sources` 的行为护栏（t22）。
+ *
+ * 为什么单独一条测试：这条路由是 GUI 里「本机装了哪几个外部 agent」的唯一数据源，
+ * 它的失败模式是**静默的**——少一条来源、回传绝对路径、把 projectDir 丢掉，界面上都看不出来。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+
+import { foreignRoutes } from './foreign.ts';
+import { routeSpecOf } from './kit.ts';
+import {
+  foreignSourceContext,
+  isInsideStaging,
+} from './foreign-context.ts';
+
+/**
+ * 最小宿主 env 桩：只提供 foreign 路由真正消费的四个字段。
+ *
+ * 为什么显式给：真实 `RoutesEnv` 由 `src/index.ts` 的 `makeRouteEnv()` 推断，
+ * 全量构造需要一个完整 DSH 宿主。这里只放本组用到的字段 —— 组文件在构建期只解构 env，
+ * 其余依赖都在 handler 内，所以桩足够驱动真实行为（与 route-fence 的 stubEnv 同思路）。
+ */
+async function stubEnv(sessionFormatVersion?: number): Promise<Record<string, unknown>> {
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'dcm-foreign-route-'));
+  return {
+    tmpDir,
+    roots: [tmpDir],
+    /**
+     * **host.homeDir 刻意设成一个「像 \$DSH_HOME 但不是用户 home」的路径**。
+     *
+     * 这是防回归的关键：宿主 context 的 homeDir 是 \$DSH_HOME（≈ ~/.dsh），而来源真值表
+     * 全部相对**用户 home**。此前 POST 用 host.homeDir 拼路径 → 去找 ~/.dsh/.claude（全读不到）→
+     * 稳定回 400 nothing-to-import，而 GET 用 os.homedir() 显示 found=true —— **两个接口自相矛盾**。
+     * 若测试桩把 host.homeDir 设成 os.homedir()，这个缺陷就会被**掩盖**（两边恰好同值）。
+     * 故此处故意给一个不可能存在的目录：任何误用 host.homeDir 的实现都会立刻红。
+     */
+    host: {
+      homeDir: path.join(tmpDir, 'dsh-home-NOT-user-home'),
+      dshVersion: 'test',
+      // 缺省 = 读不到目标版本（内核据此逐条报 session-format-version-unknown，绝不猜）
+      sessionFormatVersion,
+    },
+  };
+}
+
+function fakeRequest(url: string): IncomingMessage {
+  const req = {
+    method: 'GET',
+    url,
+    socket: { remoteAddress: '127.0.0.1' },
+    headers: { host: '127.0.0.1:3080' },
+    async *[Symbol.asyncIterator](): AsyncGenerator<Buffer> {
+      // GET 无体
+    },
+  };
+  return req as unknown as IncomingMessage;
+}
+
+interface FakeResponse {
+  res: ServerResponse;
+  status: number;
+  body: string;
+}
+
+function fakeResponse(): FakeResponse {
+  const state = { status: 0, body: '' };
+  const res = {
+    headersSent: false,
+    writeHead(status: number) {
+      state.status = status;
+      this.headersSent = true;
+      return this;
+    },
+    end(payload?: string) {
+      state.body = payload ?? '';
+      return this;
+    },
+  };
+  return {
+    res: res as unknown as ServerResponse,
+    get status() { return state.status; },
+    get body() { return state.body; },
+  };
+}
+
+interface ForeignSourcesBody {
+  conflictPolicy: string;
+  projectScoped: boolean;
+  sources: { id: string; labelKey: string; found: boolean; paths: string[]; skipped: unknown[] }[];
+}
+
+async function callRoute(url: string): Promise<{ status: number; body: ForeignSourcesBody; raw: string }> {
+  const routes = foreignRoutes({} as never);
+  assert.equal(routes.length, 2, '本组应恰好两条路由（发现 + 产包）');
+  const route = routes[0]!;
+  assert.notEqual(routeSpecOf(route), undefined, '必须经 kit 的 endpoint() 声明（不得裸注册）');
+  const res = fakeResponse();
+  await route.handler(fakeRequest(url), res.res);
+  return { status: res.status, body: JSON.parse(res.body) as ForeignSourcesBody, raw: res.body };
+}
+
+test('foreign-sources：30 条来源的检测结果齐全、冲突策略可见、绝不回传绝对路径', async () => {
+  const { status, body, raw } = await callRoute('/api/dsh-config-manager/foreign-sources');
+  assert.equal(status, 200);
+  assert.equal(body.conflictPolicy, 'skip-no-overwrite');
+  assert.equal(body.projectScoped, false, '未显式给 projectDir 时绝不猜「项目 = 宿主 cwd」');
+  assert.deepEqual(
+    body.sources.map((s) => s.id),
+    [
+      'claude-code', 'hermes', 'cursor', 'codex', 'copilot', 'antigravity',
+      'gemini', 'reasonix', 'opencode', 'mimocode', 'zcode', 'grokbuild', 'openclaw', 'pi',
+      'kimi', 'kilocode', 'qoder', 'chatgpt', 'workbuddy', 'qwen', 'continue', 'cline',
+      'goose', 'dsh4', 'zed', 'crush', 'teleagent', 'trae', 'vibe', 'dsh',
+    ],
+    '30 个来源一个都不能少、顺序稳定',
+  );
+  for (const source of body.sources) {
+    assert.equal(typeof source.found, 'boolean', source.id + ' 的 found 必须是布尔');
+    assert.ok(Array.isArray(source.paths), source.id + ' 的 paths 必须是数组');
+    assert.ok(Array.isArray(source.skipped), source.id + ' 的 skipped 必须是数组');
+    for (const p of source.paths) {
+      assert.ok(!path.isAbsolute(p), source.id + ' 的路径必须是相对位置，实际: ' + p);
+    }
+  }
+  assert.ok(!raw.includes(os.homedir().replace(/\\/g, '\\\\')), '响应体绝不包含用户 home 绝对路径');
+});
+
+test('foreign-sources：?projectDir= 被真正传给来源（项目级真值位置进入检测面）', async () => {
+  const project = path.join(import.meta.dirname, '..', 'foreign', 'fixtures', 'cursor', 'basic', 'project');
+  const { status, body } = await callRoute(
+    '/api/dsh-config-manager/foreign-sources?projectDir=' + encodeURIComponent(project),
+  );
+  assert.equal(status, 200);
+  assert.equal(body.projectScoped, true, '显式给了 projectDir 必须如实标注');
+  const cursor = body.sources.find((s) => s.id === 'cursor');
+  assert.ok(cursor !== undefined);
+  assert.ok(cursor.paths.includes('project/.cursor/mcp.json'), '项目级 mcp.json 必须出现在检测面里');
+  assert.ok(cursor.paths.includes('project/.cursor/rules'), '项目级 rules 必须出现在检测面里');
+});
+
+/* ---------------- foreign-context（纯函数：三处调用点共用同一份构造） ----------------
+
+   两个缺陷的防回归护栏（都由 captain 复验确认）：
+    ① 缺陷 1（严重）：POST 曾用 \`host.homeDir\`（= \$DSH_HOME ≈ ~/.dsh）当来源基准，
+       而来源真值表相对**用户 home** → POST 恒读不到 → 400 nothing-to-import，
+       与 GET（用 os.homedir()）显示 found=true **自相矛盾**；
+    ② 缺陷 2：路由模块曾 \`import { PLUGIN_VERSION } from '../index.ts'\` → 任何直接
+       import 本模块的单测都会连带加载 @deepseek-ai/* 而 ERR_MODULE_NOT_FOUND。
+       本文件现在能跑起来，本身就是缺陷 2 已修的证明（import 链里已无 src/index.ts）。 */
+
+test('foreign-context：来源上下文恒以**用户 home** 为基准，绝不取宿主 homeDir（缺陷 1 防回归）', () => {
+  const ctx = foreignSourceContext()
+  // 不传 userHome → 回退 os.homedir()（= 来源真值表的基准）
+  assert.equal(ctx.homeDir, os.homedir(), '缺省必须是用户 home，不是 $DSH_HOME')
+  // 显式传入优先
+  assert.equal(foreignSourceContext({ userHome: 'C:/users/x' }).homeDir, 'C:/users/x')
+  // 空串视为未给（不产生空 home → 不拼出相对路径）
+  assert.equal(foreignSourceContext({ userHome: '' }).homeDir, os.homedir(), '空串必须回退，不得产出空 homeDir')
+})
+
+test('foreign-context：projectDir / targetSessionFormatVersion 缺省时**该键不出现**（绝不猜）', () => {
+  const bare = foreignSourceContext()
+  assert.equal('projectDir' in bare, false, '未给 projectDir → 键不出现（内核据此不扫项目级，而不是拿空串拼路径）')
+  assert.equal('targetSessionFormatVersion' in bare, false, '未给版本 → 键不出现（内核逐条报码，绝不擅自填默认版本）')
+  assert.equal(foreignSourceContext({ projectDir: '' }).projectDir, undefined, '空串 = 未给')
+  const full = foreignSourceContext({ projectDir: '/proj', targetSessionFormatVersion: 4 })
+  assert.equal(full.projectDir, '/proj')
+  assert.equal(full.targetSessionFormatVersion, 4)
+})
+
+test('foreign-context：受控目录自检用段边界，/tmp-evil 不得通过 /tmp（防前缀误判）', () => {
+  const root = path.resolve('/tmp/dcm-staging')
+  assert.equal(isInsideStaging(path.join(root, 'a.zip'), [root]), true)
+  assert.equal(isInsideStaging(root, [root]), true, '根目录自身算在内')
+  assert.equal(isInsideStaging(root + '-evil/a.zip', [root]), false, '同前缀的另一目录不得通过')
+  assert.equal(isInsideStaging(path.resolve('/elsewhere/a.zip'), [root]), false)
+  assert.equal(isInsideStaging(path.join(root, '..', 'escape.zip'), [root]), false, '上跳后不在根内')
+})
+
+test('foreign-context：模块 import 链里不得出现 src/index.ts（缺陷 2 防回归）', async () => {
+  // 直接断言「本测试文件能 import 成功」还不够 —— 要钉住**成因**：
+  // 路由实现模块不得把宿主入口拉进 import 链。
+  const src = await fs.readFile(path.join(import.meta.dirname, 'foreign.ts'), 'utf8')
+  assert.ok(
+    !/from '\.\.\/index\.ts'/.test(src),
+    'src/routes/foreign.ts 不得 import ../index.ts（会把 @deepseek-ai/* 拉进纯单测环境）',
+  )
+  assert.ok(
+    src.includes("from './foreign-context.ts'"),
+    '必须经纯函数模块构造来源上下文（三处调用点同源的唯一实现）',
+  )
+})
+
+/* ---------------- POST /foreign-import（t17：GUI 侧的产包端点） ----------------
+
+   为什么必须真跑：这条端点是「GUI 从选来源到拿到 zipPath」之间**唯一**的一环，
+   它坏了的表现是「点导入没反应 / 报一句看不懂的错」。以下断言各自对应一种真实失败模式。 */
+
+interface ForeignImportBody {
+  zipPath?: string
+  name?: string
+  source?: string
+  sections?: string[]
+  counts?: Record<string, number>
+  skipped?: { code: string }[]
+  credentialRefs?: string[]
+  detectedPaths?: string[]
+  conflictPolicy?: string
+  code?: string
+}
+
+/** 构造 POST 请求（带 JSON 体）。 */
+function fakePost(url: string, payload: unknown): IncomingMessage {
+  const body = Buffer.from(JSON.stringify(payload), 'utf8')
+  const req = {
+    method: 'POST',
+    url,
+    socket: { remoteAddress: '127.0.0.1' },
+    headers: { host: '127.0.0.1:3080', 'content-length': String(body.length) },
+    async *[Symbol.asyncIterator](): AsyncGenerator<Buffer> {
+      yield body
+    },
+  }
+  return req as unknown as IncomingMessage
+}
+
+/** 取本组的 foreign-import 路由。 */
+function importRoute(env: Record<string, unknown>) {
+  const routes = foreignRoutes(env as never)
+  const route = routes.find((r) => r.path === '/api/dsh-config-manager/foreign-import')
+  assert.ok(route !== undefined, '必须存在 POST /foreign-import（否则 GUI 拿不到 zipPath）')
+  assert.notEqual(routeSpecOf(route), undefined, '必须经 kit 的 endpoint() 声明（不得裸注册）')
+  return route
+}
+
+/**
+ * 调一次 POST /foreign-import。
+ *
+ * `opts.userHome` 通过覆盖 `USERPROFILE`/`HOME` 生效 —— 路由走 `foreignSourceContext()` 的缺省
+ * 分支（`os.homedir()`），而 `os.homedir()` 正是读这两个环境变量。这样测试能用**受控的临时 userHome**
+ * 驱动真实代码路径，而不必在实现里开测试专用口子（也就不必为测试放宽生产语义）。
+ */
+async function callImport(
+  payload: unknown,
+  opts: { userHome?: string; sessionFormatVersion?: number } = {},
+): Promise<{ status: number; body: ForeignImportBody; raw: string }> {
+  const env = await stubEnv(opts.sessionFormatVersion)
+  const prevProfile = process.env['USERPROFILE']
+  const prevHome = process.env['HOME']
+  if (opts.userHome !== undefined) {
+    process.env['USERPROFILE'] = opts.userHome
+    process.env['HOME'] = opts.userHome
+  }
+  try {
+    const res = fakeResponse()
+    await importRoute(env).handler(fakePost('/api/dsh-config-manager/foreign-import', payload), res.res)
+    return { status: res.status, body: JSON.parse(res.body) as ForeignImportBody, raw: res.body }
+  } finally {
+    if (prevProfile === undefined) delete process.env['USERPROFILE']
+    else process.env['USERPROFILE'] = prevProfile
+    if (prevHome === undefined) delete process.env['HOME']
+    else process.env['HOME'] = prevHome
+  }
+}
+
+test('GET 与 POST 对同一来源必须给同一结论（缺陷 1 的另一面：两接口自相矛盾）', async () => {
+  /**
+   * 缺陷 1 的可见症状不是「读不到」，而是 **GET 说 found=true、POST 说 nothing-to-import**。
+   * 根因是两处用了不同的 home（GET os.homedir() / POST host.homeDir）。
+   * 这里直接把两个接口对同一受控 userHome 的结论钉在一起 —— 任何一处改回错 home，本用例立刻红。
+   */
+  const fixtureHome = path.join(import.meta.dirname, '..', 'foreign', 'fixtures', 'hermes', 'basic')
+  const userHome = await fs.mkdtemp(path.join(os.tmpdir(), 'dcm-foreign-consistency-'))
+  const target = process.platform === 'win32'
+    ? path.join(userHome, 'AppData', 'Local', 'Hermes')
+    : path.join(userHome, '.hermes')
+  await fs.mkdir(target, { recursive: true })
+  await fs.cp(fixtureHome, target, { recursive: true })
+  const prev = { profile: process.env['USERPROFILE'], home: process.env['HOME'], local: process.env['LOCALAPPDATA'], hermes: process.env['HERMES_HOME'] }
+  process.env['USERPROFILE'] = userHome
+  process.env['HOME'] = userHome
+  delete process.env['LOCALAPPDATA']
+  delete process.env['HERMES_HOME']
+  const env2 = await stubEnv()
+  try {
+    // GET：检测面
+    const getRes = fakeResponse()
+    await foreignRoutes(env2 as never)[0]!.handler(fakeRequest('/api/dsh-config-manager/foreign-sources'), getRes.res)
+    const detected = (JSON.parse(getRes.body) as { sources: { id: string; found: boolean }[] })
+      .sources.find((s) => s.id === 'hermes')
+    assert.equal(detected?.found, true, 'GET 必须检测到受控 userHome 下的 Hermes')
+
+    // POST：产包面
+    const post = await callImport({ source: 'hermes' }, { userHome })
+    assert.equal(
+      post.status,
+      200,
+      'GET 说 found=true 而 POST 说读不到 —— 两个接口自相矛盾（正是缺陷 1 的症状）：' + post.raw,
+    )
+  } finally {
+    if (prev.profile === undefined) delete process.env['USERPROFILE']; else process.env['USERPROFILE'] = prev.profile
+    if (prev.home === undefined) delete process.env['HOME']; else process.env['HOME'] = prev.home
+    if (prev.local === undefined) delete process.env['LOCALAPPDATA']; else process.env['LOCALAPPDATA'] = prev.local
+    if (prev.hermes === undefined) delete process.env['HERMES_HOME']; else process.env['HERMES_HOME'] = prev.hermes
+    await fs.rm(userHome, { recursive: true, force: true })
+  }
+})
+
+test('foreign-import：未知来源 → 400 + 可用清单，绝不回退到默认来源', async () => {
+  const { status, body, raw } = await callImport({ source: 'nonexistent-source' })
+  assert.equal(status, 400)
+  assert.ok(raw.includes('nonexistent-source'), '错误里必须点名用户给的那个 id')
+  assert.ok(raw.includes('hermes'), '必须给出可用来源清单（否则用户不知道能填什么）')
+  assert.equal(body.code, 'unknown-source', '稳定机器码供客户端判别')
+})
+
+test('foreign-import：缺 source → 400 + 稳定码（不是 500）', async () => {
+  const { status, body } = await callImport({})
+  assert.equal(status, 400)
+  assert.equal(body.code, 'missing-source')
+})
+
+test('foreign-import：空来源 → 400 + nothing-to-import（绝不静默产空包）', async () => {
+  // 本机没有 Antigravity 真盘 → 走「一个分区都产不出来」的分支；
+  // 若开发机恰好装了，则走 200 —— 两种都是正确行为，这里只钉住「不许静默空包」。
+  const { status, body, raw } = await callImport({ source: 'antigravity' })
+  if (status === 400) {
+    assert.ok(raw.includes('nothing-to-import'), '空结果必须给稳定码，而不是 200 + 空分区')
+  } else {
+    assert.ok((body.sections ?? []).length > 0, '200 必须伴随非空分区')
+  }
+})
+
+test('foreign-import：真实 fixture 产包 → 分区非空、路径受控、响应不含凭据值（缺陷 1 的端到端护栏）', async () => {
+  /**
+   * 用仓库内的跨平台 fixture 驱动 Hermes。
+   *
+   * **为什么这里不再用「HERMES_HOME 环境覆盖」**：那条路径会**掩盖缺陷 1** ——
+   * HERMES_HOME 优先于任何 home 拼接，所以即使路由把 homeDir 传成了 \$DSH_HOME 也照样能读到 fixture，
+   * 测试于是恒绿（这正是本机「看起来是好的」的原因，也是我第一版护栏的假绿来源）。
+   *
+   * 现在改为把它当**用户 home** 使用（~/.hermes 形态）：路由必须用用户 home 才能找到它，
+   * 一旦退回 host.homeDir（stub 里是一个不存在的路径）→ 立刻 400 nothing-to-import → 本用例红。
+   * 因此这条用例同时是「产包正确」与「homeDir 用对了」的端到端证据。
+   */
+  const fixtureHome = path.join(import.meta.dirname, '..', 'foreign', 'fixtures', 'hermes', 'basic')
+  /**
+   * 把 fixture 摆到「受控 userHome 之下的真实 Hermes 位置」——**按平台**：
+   *  - win32：\`%LOCALAPPDATA%\Hermes\`（LOCALAPPDATA 缺省 = <userHome>/AppData/Local，见 resolveHermesHome）
+   *  - 其它：\`~/.hermes\`
+   * 刻意**不设 HERMES_HOME**：它会短路掉 homeDir 拼接，从而掩盖缺陷 1（本机就是这样「看起来是好的」）。
+   */
+  const userHome = await fs.mkdtemp(path.join(os.tmpdir(), 'dcm-foreign-userhome-'))
+  const target = process.platform === 'win32'
+    ? path.join(userHome, 'AppData', 'Local', 'Hermes')
+    : path.join(userHome, '.hermes')
+  await fs.mkdir(target, { recursive: true })
+  await fs.cp(fixtureHome, target, { recursive: true })
+  const prev = { local: process.env['LOCALAPPDATA'], hermes: process.env['HERMES_HOME'] }
+  // 清掉这两个：让解析真正走 userHome（而不是被环境变量短路）
+  delete process.env['LOCALAPPDATA']
+  delete process.env['HERMES_HOME']
+  try {
+    const { status, body, raw } = await callImport({ source: 'hermes' }, { userHome })
+    // **不再静默跳过**：fixture 就在这个 userHome 里，读不到就是真失败（不得写成 return 变成假绿）
+    assert.equal(status, 200, 'fixture 位于传入的 userHome 下，必须能读到；若为 400 说明 homeDir 用错了：' + raw)
+    assert.ok((body.sections ?? []).length > 0, '必须产出至少一个分区')
+    assert.equal(body.conflictPolicy, 'skip-no-overwrite')
+    assert.ok((body.zipPath ?? '').endsWith('.zip'), 'zipPath 必须指向 ZIP')
+    assert.ok(!raw.includes('_DO_NOT_SHIP'), '响应体泄露了 fixture 哨兵值（凭据铁律）')
+    for (const p of body.detectedPaths ?? []) {
+      assert.ok(!path.isAbsolute(p), 'detectedPaths 必须是相对位置，实际: ' + p)
+    }
+  } finally {
+    if (prev.local === undefined) delete process.env['LOCALAPPDATA']
+    else process.env['LOCALAPPDATA'] = prev.local
+    if (prev.hermes === undefined) delete process.env['HERMES_HOME']
+    else process.env['HERMES_HOME'] = prev.hermes
+    await fs.rm(userHome, { recursive: true, force: true })
+  }
+})
+
+/** 在受控 userHome 下造一条最小 Claude Code 会话（cwd 写在记录里，DSH 按它归位目录键）。 */
+async function writeClaudeSession(userHome: string, id: string, cwd: string): Promise<void> {
+  const dir = path.join(userHome, '.claude', 'projects', 'D--proj-app')
+  await fs.mkdir(dir, { recursive: true })
+  const lines = [
+    JSON.stringify({
+      type: 'user',
+      uuid: 'aaaaaaaa-0000-4000-8000-000000000001',
+      timestamp: '2026-10-01T10:00:00.000Z',
+      cwd,
+      message: { role: 'user', content: '帮我看看这个 bug' },
+    }),
+    JSON.stringify({
+      type: 'assistant',
+      uuid: 'aaaaaaaa-0000-4000-8000-000000000002',
+      timestamp: '2026-10-01T10:00:05.000Z',
+      cwd,
+      message: { model: 'claude-sonnet-4', content: [{ type: 'text', text: '修好了' }] },
+    }),
+  ]
+  await fs.writeFile(path.join(dir, id + '.jsonl'), lines.join('\n') + '\n', 'utf8')
+}
+
+test('foreign-import：目标机是 v4 时必须照 v4 产出会话（2026-10-08 桌面端整批被跳过的回归护栏）', async () => {
+  /**
+   * 真机事故：DSH 桌面端（0.2.0-rc.2）的会话格式是 v4，而转码器只认 v3 ⇒ 每一条会话都被
+   * `session-format-unsupported` 跳过、产出的包里**没有 sessions 分区**，用户看到「历史对话不见了」。
+   * 本用例把「宿主给的是 v4 就照 v4 产出」钉在**路由层**（GUI 走的正是这条端点）。
+   */
+  const userHome = await fs.mkdtemp(path.join(os.tmpdir(), 'dcm-foreign-v4-'))
+  try {
+    await writeClaudeSession(userHome, '11111111-1111-4111-8111-111111111111', 'D:/proj/app')
+
+    const v4 = await callImport({ source: 'claude-code' }, { userHome, sessionFormatVersion: 4 })
+    assert.equal(v4.status, 200, 'v4 目标下必须产包：' + v4.raw)
+    assert.ok((v4.body.sections ?? []).includes('sessions'), 'v4 目标必须产出 sessions 分区：' + v4.raw)
+    assert.equal(v4.body.counts?.['sessions.transcoded'], 1)
+    assert.equal(
+      (v4.body.skipped ?? []).some((s) => s.code === 'session-format-unsupported'),
+      false,
+      '不得再整批报 session-format-unsupported',
+    )
+
+    // 读不到目标版本时**不猜**：内核如实报码、一个会话都不转 → 整包没有分区（400 nothing-to-import）。
+    // 这是「绝不猜版本」的既有语义，与上面那条并排钉住，避免修复被误读成「以后可以直接硬写 v4」。
+    const unknown = await callImport({ source: 'claude-code' }, { userHome })
+    assert.equal(unknown.status, 400, unknown.raw)
+    assert.equal(unknown.body.code, 'nothing-to-import')
+    assert.ok(
+      (unknown.body.skipped ?? []).some((s) => s.code === 'session-format-version-unknown'),
+      '读不到版本必须如实报码：' + unknown.raw,
+    )
+  } finally {
+    await fs.rm(userHome, { recursive: true, force: true })
+  }
+})

package/src/routes/foreign.ts

@@ -0,0 +1,226 @@
+/**
+ * 路由组：外部 agent 来源（foreign）。
+ *
+ * 两条路由，职责严格分开：
+ *  ① `GET  /foreign-sources` —— **只读**的本机来源发现（本机装了哪几个来源；没装的也列出来，
+ *     只是 found=false）。检测与导入共用 src/foreign/registry.ts 的同一份装配，绝不各写一套路径表。
+ *  ② `POST /foreign-import` —— 把一个外部来源**翻译成标准 bundle v1 ZIP**，落到受控临时目录并
+ *     返回 zipPath，供既有导入向导（analyze → plan → execute）消费。
+ *
+ * 为什么必须由宿主做②：`source.build()` 与 `writeForeignBundle()` 要读本机文件系统、
+ * 写 ZIP —— 浏览器半做不了。此前这条能力**只存在于 CLI**（`dcm import --from`），
+ * 于是 GUI 能选来源、能看检测结果，却在「点导入」之后拿不到 zipPath 而断链。
+ *
+ * 四条硬边界：
+ *  ① **只写受控临时目录**：产物落在 `env.tmpDir`（与 /upload、/decrypt-archive 同一套暂存约定），
+ *     响应里的 zipPath 必须过 `isControlledPath` 自检 —— 绝不写到任何配置位置；
+ *  ② **不做导入**：本路由只产包，**绝不**触碰 $DSH_HOME 下的配置。导入仍由既有
+ *     /analyze → /plan → /execute 完成（导入前快照、冲突判定、dry-run 全部自动生效）；
+ *  ③ **凭据值绝不进响应**：只回 skipped 机器码 + 凭据**引用名**（值在转换层就已被剥离，
+ *     见 src/foreign/types.ts 的不变量①）；
+ *  ④ **空结果不静默成功**：一个分区都产不出来 → 400 + 稳定码（与 CLI 的退出码 1 同口径），
+ *     否则用户会拿到一个自检通过却什么都没有的包。
+ *
+ * W1（host-entry#F-02/#F-03）：围栏 / 方法白名单 / 顶层异常处理由 src/routes/kit.ts 的 endpoint() 统一提供。
+ */
+import fs from 'node:fs/promises'
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import { randomBytes } from 'node:crypto'
+
+import { writeForeignBundle } from '../foreign/bundle.ts'
+import {
+  FOREIGN_CONFLICT_POLICY,
+  ForeignSourceError,
+  createBuiltinForeignSourceRegistry,
+  detectForeignSources,
+} from '../foreign/registry.ts'
+import { redact } from '../security/redaction.ts'
+import type { Platform } from '../schema/types.ts'
+import { endpoint, requireJsonObject, writeJson } from './kit.ts'
+import type { WebRoute } from './kit.ts'
+import type { RoutesEnv } from './context.ts'
+import {
+  FOREIGN_IMPORT_EMPTY_CODE,
+  FOREIGN_IMPORT_MISSING_SOURCE_CODE,
+  foreignSourceContext,
+  isInsideStaging,
+} from './foreign-context.ts'
+
+/**
+ * 写进 `manifest.exporter.version` 的插件版本。
+ *
+ * **运行时从 package.json 读取，不 import `../index.ts`** —— 这是本文件的关键约束：
+ * `src/index.ts` 顶部 import 了 `@deepseek-ai/*` 运行时包，一旦本模块（路由实现）把它拉进来，
+ * 任何**直接 import 本模块的单测**都会在纯单测环境 ERR_MODULE_NOT_FOUND 而根本跑不起来。
+ * 既有先例：`src/cli/index.ts` 的 resolveCliVersion 用同一套解法（只依赖 node:fs）。
+ *
+ * 也不硬编码版本：本仓库铁律是「版本必须同步多处」，再加一个常量就等于多一个会漂移的同步点
+ * （CLI 那边实测漂移过：插件升到 0.1.59 后常量仍停在 0.1.58）。读不到时回退中性占位，绝不谎报。
+ */
+function resolvePluginVersion(): string {
+  try {
+    const pkgUrl = new URL('../../package.json', import.meta.url)
+    const parsed = JSON.parse(readFileSync(pkgUrl, 'utf8')) as { version?: unknown }
+    if (typeof parsed.version === 'string' && parsed.version !== '') return parsed.version
+  } catch {
+    // 包结构不可解析（被裁剪 / 单文件打包）：回退中性占位
+  }
+  return '0.0.0-unknown'
+}
+
+/** 进程内缓存（每个宿主进程只读一次 package.json） */
+const PLUGIN_VERSION = resolvePluginVersion()
+
+/**
+ * 该来源当前版本读不了会话（不猜版本）时的稳定提示。
+ *
+ * 为什么宿主侧要显式传 `targetSessionFormatVersion`：会话转码必须知道目标机的格式版本，
+ * 缺省时内核逐条报 session-format-version-unknown 且**不产出 sessions 分区**（绝不猜）。
+ * 宿主能读到真实版本（`host.sessionFormatVersion`），所以 GUI 路径用它 —— 这与离线 CLI
+ * 不同：CLI 拿不到版本，只能如实报码。
+ */
+export function foreignRoutes(env: RoutesEnv): WebRoute[] {
+  const { host, roots, tmpDir } = env
+  return [
+    // ---------------------------------------------------- foreign-sources
+    // 六个来源的本机检测结果（found / 命中的相对位置 / 机器码）；未安装是正常状态，不是错误。
+    endpoint({ path: '/api/dsh-config-manager/foreign-sources', methods: ['GET'] }, async (req, res) => {
+      const url = new URL(req.url ?? '/', 'http://127.0.0.1')
+      const projectDir = url.searchParams.get('projectDir')
+      const projectScoped = projectDir !== null && projectDir !== ''
+      // 与 POST / CLI 共用同一份构造（见 foreign-context.ts 的缺陷记录：三处必须同源）
+      const ctx = foreignSourceContext({ projectDir: projectScoped ? (projectDir as string) : undefined })
+      const sources = await detectForeignSources(createBuiltinForeignSourceRegistry(), ctx)
+      writeJson(res, 200, { conflictPolicy: FOREIGN_CONFLICT_POLICY, projectScoped, sources })
+    }),
+
+    // ----------------------------------------------------- foreign-import
+    // 外部来源 → 标准 bundle v1 ZIP（受控临时目录）→ zipPath。见文件头的四条硬边界。
+    endpoint({ path: '/api/dsh-config-manager/foreign-import', methods: ['POST'] }, async (req, res) => {
+      const body = await requireJsonObject(req)
+      const sourceId = typeof body?.['source'] === 'string' ? body['source'] : ''
+      if (sourceId === '') {
+        writeJson(res, 400, { error: 'source is required', code: FOREIGN_IMPORT_MISSING_SOURCE_CODE })
+        return
+      }
+      /**
+       * 未知来源**最先判定**（在接触任何宿主依赖之前）。
+       *
+       * 为什么顺序要紧：来源 id 非法是**与运行环境无关**的请求错误，必须稳定回 400。
+       * 若把它排在读取宿主环境之后，宿主状态异常时会把它淹没成 500 —— 用户从
+       * 「你填错了来源」变成「插件坏了」，排查方向整个跑偏。
+       */
+      const registry = createBuiltinForeignSourceRegistry()
+      let source
+      try {
+        source = registry.get(sourceId)
+      } catch (error) {
+        if (error instanceof ForeignSourceError) {
+          // 未知来源**绝不回退**到某个默认来源（回退会让用户以为导的是 A、实际导的是 B）
+          writeJson(res, 400, {
+            error: error.message,
+            code: error.code,
+            available: error.available,
+          })
+          return
+        }
+        throw error
+      }
+
+      /**
+       * projectDir 语义（与 GET 一致）：**只在请求显式给出时传入**。
+       * 宿主进程的 cwd 不是用户的项目 —— 绝不猜（猜错会把 A 项目的规则导成 B 项目的）。
+       */
+      const rawProject = body?.['projectDir']
+      const projectDir = typeof rawProject === 'string' && rawProject !== '' ? rawProject : undefined
+      /**
+       * 与 GET / CLI **共用同一份构造**（缺陷修复，见 foreign-context.ts 文件头）。
+       *
+       * 这里的 `homeDir` 必须是**用户 home**，不能用 `host.homeDir` —— 后者是 \$DSH_HOME（≈ ~/.dsh），
+       * 而六来源真值表全部相对用户 home。此前写错会让 POST 去找 ~/.dsh/.claude（全部读不到 →
+       * 稳定回 400 nothing-to-import），而 GET 显示 found=true，两个接口自相矛盾。
+       */
+      const ctx = foreignSourceContext({
+        projectDir,
+        // 本机能读到会话格式版本时必须传（否则会话整批不转码）；读不到就不传，内核如实报码。
+        targetSessionFormatVersion: host.sessionFormatVersion,
+      })
+
+      let result
+      let detection
+      try {
+        detection = await source.detect(ctx)
+        result = await source.build(ctx)
+      } catch (error) {
+        writeJson(res, 500, { error: redact(error instanceof Error ? error.message : String(error)) })
+        return
+      }
+
+      // 空结果**绝不静默成功**：自检能过，但用户拿到的是一个什么都没有的包（与 CLI 同口径）。
+      if (result.sections.length === 0) {
+        writeJson(res, 400, {
+          error: 'nothing to import: the source has no convertible configuration on this machine',
+          code: FOREIGN_IMPORT_EMPTY_CODE,
+          skipped: result.skipped,
+        })
+        return
+      }
+
+      const outPath = path.join(tmpDir, `foreign-${source.id}-${randomBytes(6).toString('hex')}.zip`)
+      try {
+        await fs.mkdir(tmpDir, { recursive: true })
+        await writeForeignBundle({
+          result,
+          outPath,
+          exporterVersion: PLUGIN_VERSION,
+          // 包是为「现在导入到本机」合成的 → 目标机 DSH 版本；读不到就如实标注，绝不谎报
+          dshVersion: host.dshVersion ?? 'unknown',
+          platform: process.platform as Platform,
+          arch: process.arch,
+        })
+      } catch (error) {
+        // 失败即清理半成品（不留孤儿 ZIP 占着 tmp）
+        await fs.rm(outPath, { force: true }).catch(() => undefined)
+        writeJson(res, 500, { error: redact(error instanceof Error ? error.message : String(error)) })
+        return
+      }
+
+      /**
+       * 自检：产物必须落在受控暂存根内。**写出去之前就多一道判定** ——
+       * 这条断言的价值不是「防注入」（tmpDir 是我们自己拼的），而是把
+       * 「受控目录约定」变成**运行期不变量**：将来有人改成别的目录，这里立刻红。
+       */
+      if (!isInsideStaging(outPath, roots)) {
+        await fs.rm(outPath, { force: true }).catch(() => undefined)
+        writeJson(res, 500, { error: 'bundle path escaped the controlled staging area' })
+        return
+      }
+
+      let sizeBytes = 0
+      try {
+        sizeBytes = (await fs.stat(outPath)).size
+      } catch {
+        // 体积只是展示信息，读不到不影响导入（不谎报 0：留给客户端按「未知」处理）
+      }
+
+      writeJson(res, 200, {
+        zipPath: outPath,
+        name: path.basename(outPath),
+        source: source.id,
+        labelKey: source.labelKey,
+        sizeBytes,
+        // 分区与计数：GUI 据此显示「将导入什么」（全部是机器可读的计数，不含任何配置值）
+        sections: result.sections.map((s) => s.sectionId),
+        counts: result.counts,
+        // 未迁移项：只有机器码 + 位置名 + 条数（**没有任何配置值**）
+        skipped: result.skipped,
+        // 凭据只给**引用名**（形如 mcp:gitnexus:GITHUB_TOKEN）：导入后由用户在 DSH 里补录
+        credentialRefs: result.credentialRefs,
+        /** 检测到的本机位置（相对 home），供界面显示「从哪儿读的」 */
+        detectedPaths: detection.paths,
+        conflictPolicy: FOREIGN_CONFLICT_POLICY,
+      })
+    }),
+  ]
+}