chatccc 0.2.16 → 0.2.18

package/src/__tests__/config.test.ts

@@ -1,11 +1,22 @@
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, vi } from "vitest";
+
+// 注意：这里特意 import 自 `../config-utils.ts` 而不是 `../config.ts`。
+// `../config.ts` 在模块顶层会执行 loadConfig()——在生产环境下，当 config.json
+// 不存在时它会从 config.sample.json 自动复制一份过去。我们额外靠 VITEST 环境
+// 变量在 loadConfig() 里跳过这次写文件，但能不触发就尽量不触发。
+import { existsSync } from "node:fs";
+import { join } from "node:path";
 
 import {
   DEFAULT_GIT_TIMEOUT_SECONDS,
   MAX_GIT_TIMEOUT_SECONDS,
   MIN_GIT_TIMEOUT_SECONDS,
+  autoDetectCodexPath,
+  autoDetectCursorPath,
+  normalizeOptionalConfigField,
   parseGitTimeoutSeconds,
-} from "../config.ts";
+  readToolCliPath,
+} from "../config-utils.ts";
 
 describe("parseGitTimeoutSeconds", () => {
   it("returns default when raw is undefined", () => {
@@ -110,6 +121,95 @@ describe("parseGitTimeoutSeconds", () => {
   });
 });
 
+describe("normalizeOptionalConfigField", () => {
+  it("returns fallback (default empty string) when value is undefined", () => {
+    expect(normalizeOptionalConfigField(undefined, { label: "x" })).toBe("");
+  });
+
+  it("returns fallback (default empty string) when value is null", () => {
+    expect(normalizeOptionalConfigField(null, { label: "x" })).toBe("");
+  });
+
+  it("returns fallback when value is not a string (number / boolean / object)", () => {
+    expect(normalizeOptionalConfigField(123, { label: "x" })).toBe("");
+    expect(normalizeOptionalConfigField(true, { label: "x" })).toBe("");
+    expect(normalizeOptionalConfigField({}, { label: "x" })).toBe("");
+  });
+
+  it("uses explicit fallback when value is missing", () => {
+    expect(
+      normalizeOptionalConfigField(undefined, { label: "x", fallback: "FB" }),
+    ).toBe("FB");
+    expect(
+      normalizeOptionalConfigField(42, { label: "x", fallback: "FB" }),
+    ).toBe("FB");
+  });
+
+  it("returns empty string as-is (treated as 'do not pass to SDK/CLI')", () => {
+    expect(normalizeOptionalConfigField("", { label: "x" })).toBe("");
+    expect(
+      normalizeOptionalConfigField("", { label: "x", fallback: "FB" }),
+    ).toBe("");
+  });
+
+  it("returns value as-is when it is a normal non-default string", () => {
+    expect(normalizeOptionalConfigField("high", { label: "x" })).toBe("high");
+    expect(
+      normalizeOptionalConfigField("claude-sonnet-4-6", { label: "x" }),
+    ).toBe("claude-sonnet-4-6");
+  });
+
+  it("preserves surrounding whitespace (trim handled by callers)", () => {
+    expect(normalizeOptionalConfigField("  high  ", { label: "x" })).toBe(
+      "  high  ",
+    );
+  });
+
+  it("treats 'default' (any case, with whitespace) as empty string and warns", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      expect(normalizeOptionalConfigField("default", { label: "x" })).toBe("");
+      expect(normalizeOptionalConfigField("DEFAULT", { label: "x" })).toBe("");
+      expect(normalizeOptionalConfigField("Default", { label: "x" })).toBe("");
+      expect(normalizeOptionalConfigField("  default  ", { label: "x" })).toBe(
+        "",
+      );
+      expect(warn).toHaveBeenCalledTimes(4);
+      const msg = String(warn.mock.calls[0]?.[0] ?? "");
+      expect(msg).toContain("已废弃");
+      expect(msg).toContain("x");
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it("ignores fallback for 'default' (still returns empty string)", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      expect(
+        normalizeOptionalConfigField("default", {
+          label: "x",
+          fallback: "FB",
+        }),
+      ).toBe("");
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it("does NOT treat substrings like 'default-foo' as the deprecated literal", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      expect(
+        normalizeOptionalConfigField("default-foo", { label: "x" }),
+      ).toBe("default-foo");
+      expect(warn).not.toHaveBeenCalled();
+    } finally {
+      warn.mockRestore();
+    }
+  });
+});
+
 describe("GIT timeout constants", () => {
   it("DEFAULT_GIT_TIMEOUT_SECONDS is 180", () => {
     expect(DEFAULT_GIT_TIMEOUT_SECONDS).toBe(180);
@@ -121,3 +221,160 @@ describe("GIT timeout constants", () => {
     expect(DEFAULT_GIT_TIMEOUT_SECONDS).toBeLessThan(MAX_GIT_TIMEOUT_SECONDS);
   });
 });
+
+describe("autoDetectCursorPath", () => {
+  it("Windows 优先返回 LocalAppData 默认安装路径（agent.cmd 存在）", () => {
+    const calls: string[] = [];
+    const result = autoDetectCursorPath({
+      platform: "win32",
+      localAppData: "C:\\Users\\u\\AppData\\Local",
+      existsSync: (p) => {
+        calls.push(p);
+        return p.endsWith("agent.cmd");
+      },
+      whichSync: () => {
+        throw new Error("不该走 PATH 查找");
+      },
+    });
+    expect(result).toMatch(/cursor-agent[\\/]agent\.cmd$/);
+    // 至少检查过一次默认安装路径
+    expect(calls.some((c) => c.endsWith("agent.cmd"))).toBe(true);
+  });
+
+  it("Windows 但 LocalAppData 不存在 → 退回 whichSync(cursor-agent)", () => {
+    const result = autoDetectCursorPath({
+      platform: "win32",
+      localAppData: "C:\\Users\\u\\AppData\\Local",
+      existsSync: () => false,
+      whichSync: (cmd) => (cmd === "cursor-agent" ? "C:\\tools\\cursor-agent.exe" : null),
+    });
+    expect(result).toBe("C:\\tools\\cursor-agent.exe");
+  });
+
+  it("非 Windows 跳过 LocalAppData，直接用 whichSync 查 cursor-agent → agent", () => {
+    const tried: string[] = [];
+    const result = autoDetectCursorPath({
+      platform: "linux",
+      localAppData: undefined,
+      existsSync: () => {
+        throw new Error("非 Windows 不应该 stat LocalAppData");
+      },
+      whichSync: (cmd) => {
+        tried.push(cmd);
+        return cmd === "agent" ? "/usr/local/bin/agent" : null;
+      },
+    });
+    expect(result).toBe("/usr/local/bin/agent");
+    expect(tried).toEqual(["cursor-agent", "agent"]);
+  });
+
+  it("全部命中失败时返回 null（不抛、由调用方决定留空）", () => {
+    const result = autoDetectCursorPath({
+      platform: "darwin",
+      localAppData: undefined,
+      existsSync: () => false,
+      whichSync: () => null,
+    });
+    expect(result).toBeNull();
+  });
+});
+
+describe("autoDetectCodexPath", () => {
+  it("命中 PATH 中的 codex → 返回绝对路径", () => {
+    const result = autoDetectCodexPath({
+      whichSync: (cmd) => (cmd === "codex" ? "/usr/local/bin/codex" : null),
+    });
+    expect(result).toBe("/usr/local/bin/codex");
+  });
+
+  it("PATH 中没有 codex → 返回 null", () => {
+    const result = autoDetectCodexPath({ whichSync: () => null });
+    expect(result).toBeNull();
+  });
+});
+
+describe("readToolCliPath", () => {
+  it("优先返回新字段 path（command 同时存在也忽略）", () => {
+    const onLegacy = vi.fn();
+    expect(
+      readToolCliPath(
+        { path: "/new/path", command: "/old/cmd" },
+        { label: "cursor", onLegacyField: onLegacy },
+      ),
+    ).toBe("/new/path");
+    expect(onLegacy).not.toHaveBeenCalled();
+  });
+
+  it("仅有旧字段 command 时 → 用 command 的值并触发 onLegacyField 回调", () => {
+    const onLegacy = vi.fn();
+    expect(
+      readToolCliPath(
+        { command: "/old/cmd" },
+        { label: "codex", onLegacyField: onLegacy },
+      ),
+    ).toBe("/old/cmd");
+    expect(onLegacy).toHaveBeenCalledWith("codex", "/old/cmd");
+  });
+
+  it("path 为空字符串 / 全空白 → 视作未填，回退到 command", () => {
+    const onLegacy = vi.fn();
+    expect(
+      readToolCliPath(
+        { path: "  ", command: "/fallback" },
+        { label: "cursor", onLegacyField: onLegacy },
+      ),
+    ).toBe("/fallback");
+    expect(onLegacy).toHaveBeenCalledTimes(1);
+  });
+
+  it("两边都空 / undefined → 返回 ''，不触发回调", () => {
+    const onLegacy = vi.fn();
+    expect(readToolCliPath(undefined, { label: "x", onLegacyField: onLegacy })).toBe("");
+    expect(readToolCliPath({}, { label: "x", onLegacyField: onLegacy })).toBe("");
+    expect(
+      readToolCliPath({ path: "", command: "" }, { label: "x", onLegacyField: onLegacy }),
+    ).toBe("");
+    expect(onLegacy).not.toHaveBeenCalled();
+  });
+
+  it("非字符串字段 → 当作未填", () => {
+    expect(
+      readToolCliPath({ path: 42, command: null } as unknown as { path?: unknown }, {
+        label: "cursor",
+      }),
+    ).toBe("");
+  });
+});
+
+describe("test environment side-effects (regression guard)", () => {
+  // 历史 bug：跑单测会让仓库根目录"自己长出" config.json——
+  // src/config.ts 顶层执行的 loadConfig() 在生产环境下会自动把
+  // config.sample.json 复制成 config.json。这一行为不应在测试环境发生：
+  // (1) 单测不应改动工作区文件；
+  // (2) 误生成的 config.json 会污染 git status，干扰真实改动的提交。
+  it("仅 import config 模块不会让仓库根目录自动生成 config.json", async () => {
+    // 这里通过 import.meta.url 反推项目根目录，避免依赖 PROJECT_ROOT（后者来自 config.ts）。
+    const projectRoot = join(
+      new URL(".", import.meta.url).pathname.replace(/^\/([A-Za-z]:)/, "$1"),
+      "..",
+      "..",
+    );
+    const configJsonPath = join(projectRoot, "config.json");
+    const sampleExists = existsSync(join(projectRoot, "config.sample.json"));
+    expect(sampleExists).toBe(true);
+
+    const existedBefore = existsSync(configJsonPath);
+
+    // 触发 config.ts 顶层副作用（其它单测也会通过 session.ts/adapters/* 间接 import 它，
+    // 这里直接 import 模拟最坏情况）。
+    await import("../config.ts");
+
+    const existsAfter = existsSync(configJsonPath);
+    // 如果 import 之前就不存在，import 之后也不应该被创建出来。
+    if (!existedBefore) {
+      expect(existsAfter).toBe(false);
+    } else {
+      expect(existsAfter).toBe(true);
+    }
+  });
+});

package/src/__tests__/crash-logging.test.ts

@@ -0,0 +1,210 @@
+import { describe, it, expect, vi } from "vitest";
+
+import { buildCrashLoggingHandlers, installCrashLogging } from "../shared.ts";
+
+describe("buildCrashLoggingHandlers", () => {
+  it("uncaughtException: 写诊断、刷新日志、调用 onFatal", () => {
+    const tracer = vi.fn();
+    const flush = vi.fn();
+    const onFatal = vi.fn();
+    const handlers = buildCrashLoggingHandlers({ tracer, flush, onFatal });
+
+    const err = new Error("boom");
+    handlers.uncaughtException(err);
+
+    expect(tracer).toHaveBeenCalledWith(
+      "FATAL uncaughtException",
+      expect.objectContaining({
+        message: "boom",
+        stack: expect.stringContaining("Error: boom"),
+      })
+    );
+    expect(flush).toHaveBeenCalledTimes(1);
+    expect(onFatal).toHaveBeenCalledWith("uncaughtException", err);
+  });
+
+  it("unhandledRejection: 字符串 reason 也能转成 Error", () => {
+    const tracer = vi.fn();
+    const onFatal = vi.fn();
+    const handlers = buildCrashLoggingHandlers({ tracer, onFatal });
+
+    handlers.unhandledRejection("string-reason");
+
+    expect(tracer).toHaveBeenCalledWith(
+      "FATAL unhandledRejection",
+      expect.objectContaining({ message: "string-reason" })
+    );
+    const fatalArgs = onFatal.mock.calls[0];
+    expect(fatalArgs[0]).toBe("unhandledRejection");
+    expect(fatalArgs[1]).toBeInstanceOf(Error);
+    expect((fatalArgs[1] as Error).message).toBe("string-reason");
+  });
+
+  it("unhandledRejection: undefined reason 不会爆炸", () => {
+    const tracer = vi.fn();
+    const onFatal = vi.fn();
+    const handlers = buildCrashLoggingHandlers({ tracer, onFatal });
+
+    handlers.unhandledRejection(undefined);
+
+    expect(tracer).toHaveBeenCalledTimes(1);
+    expect(onFatal).toHaveBeenCalledTimes(1);
+    expect((onFatal.mock.calls[0][1] as Error).message.length).toBeGreaterThan(0);
+  });
+
+  it("unhandledRejection: 对象 reason 序列化为 JSON 文本", () => {
+    const tracer = vi.fn();
+    const onFatal = vi.fn();
+    const handlers = buildCrashLoggingHandlers({ tracer, onFatal });
+
+    handlers.unhandledRejection({ code: 500, msg: "internal" });
+
+    const traceExtra = tracer.mock.calls[0][1] as { message: string };
+    expect(traceExtra.message).toContain("500");
+    expect(traceExtra.message).toContain("internal");
+  });
+
+  it("过长堆栈会被截断并打上 truncated 标记", () => {
+    const tracer = vi.fn();
+    const longStack = "x".repeat(8000);
+    const err = Object.assign(new Error("long"), { stack: longStack });
+    const handlers = buildCrashLoggingHandlers({ tracer, onFatal: () => {} });
+
+    handlers.uncaughtException(err);
+
+    const extra = tracer.mock.calls[0][1] as { stack: string };
+    expect(extra.stack.length).toBeLessThanOrEqual(4100);
+    expect(extra.stack).toContain("...(truncated)");
+  });
+
+  it("signalLogger: 写入信号名并调用 onSignal", () => {
+    const tracer = vi.fn();
+    const onSignal = vi.fn();
+    const handlers = buildCrashLoggingHandlers({ tracer, onSignal });
+
+    handlers.signalLogger("SIGINT");
+
+    expect(tracer).toHaveBeenCalledWith("signal received", { signal: "SIGINT" });
+    expect(onSignal).toHaveBeenCalledWith("SIGINT");
+  });
+
+  it("beforeExit: 写入退出码", () => {
+    const tracer = vi.fn();
+    const onBeforeExit = vi.fn();
+    const handlers = buildCrashLoggingHandlers({ tracer, onBeforeExit });
+
+    handlers.beforeExit(0);
+
+    expect(tracer).toHaveBeenCalledWith("beforeExit", { code: 0 });
+    expect(onBeforeExit).toHaveBeenCalledWith(0);
+  });
+
+  it("tracer 本身抛错也不会阻断 onFatal", () => {
+    const tracer = vi.fn(() => {
+      throw new Error("tracer broken");
+    });
+    const onFatal = vi.fn();
+    const handlers = buildCrashLoggingHandlers({ tracer, onFatal });
+
+    expect(() => handlers.uncaughtException(new Error("boom"))).not.toThrow();
+    expect(onFatal).toHaveBeenCalledTimes(1);
+  });
+
+  it("flush 本身抛错也不会阻断 onFatal", () => {
+    const tracer = vi.fn();
+    const flush = vi.fn(() => {
+      throw new Error("flush broken");
+    });
+    const onFatal = vi.fn();
+    const handlers = buildCrashLoggingHandlers({ tracer, flush, onFatal });
+
+    expect(() => handlers.uncaughtException(new Error("boom"))).not.toThrow();
+    expect(onFatal).toHaveBeenCalledTimes(1);
+  });
+
+  it("默认 onFatal 行为：调用 console.error 然后 process.exit(1)", () => {
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const exitSpy = vi.spyOn(process, "exit").mockImplementation(((code?: number) => {
+      throw new Error(`__exit_${code}__`);
+    }) as never);
+
+    const handlers = buildCrashLoggingHandlers({ tracer: () => {} });
+
+    expect(() => handlers.uncaughtException(new Error("boom"))).toThrow("__exit_1__");
+    expect(errSpy).toHaveBeenCalled();
+    const message = (errSpy.mock.calls[0] ?? []).join(" ");
+    expect(message).toContain("uncaughtException");
+    expect(message).toContain("boom");
+
+    errSpy.mockRestore();
+    exitSpy.mockRestore();
+  });
+});
+
+describe("installCrashLogging", () => {
+  it("注册所有相关事件监听器", () => {
+    const before = {
+      uncaught: process.listenerCount("uncaughtException"),
+      rejection: process.listenerCount("unhandledRejection"),
+      beforeExit: process.listenerCount("beforeExit"),
+      sigint: process.listenerCount("SIGINT"),
+      sigterm: process.listenerCount("SIGTERM"),
+    };
+
+    const { cleanup } = installCrashLogging({
+      tracer: () => {},
+      onFatal: () => {},
+      onSignal: () => {},
+    });
+
+    expect(process.listenerCount("uncaughtException")).toBe(before.uncaught + 1);
+    expect(process.listenerCount("unhandledRejection")).toBe(before.rejection + 1);
+    expect(process.listenerCount("beforeExit")).toBe(before.beforeExit + 1);
+    expect(process.listenerCount("SIGINT")).toBe(before.sigint + 1);
+    expect(process.listenerCount("SIGTERM")).toBe(before.sigterm + 1);
+
+    cleanup();
+
+    expect(process.listenerCount("uncaughtException")).toBe(before.uncaught);
+    expect(process.listenerCount("unhandledRejection")).toBe(before.rejection);
+    expect(process.listenerCount("beforeExit")).toBe(before.beforeExit);
+    expect(process.listenerCount("SIGINT")).toBe(before.sigint);
+    expect(process.listenerCount("SIGTERM")).toBe(before.sigterm);
+  });
+
+  it("cleanup 之后再触发不会再调用 tracer", () => {
+    const tracer = vi.fn();
+    const { handlers, cleanup } = installCrashLogging({
+      tracer,
+      onFatal: () => {},
+      onSignal: () => {},
+    });
+
+    handlers.signalLogger("SIGTERM");
+    expect(tracer).toHaveBeenCalledTimes(1);
+
+    cleanup();
+    tracer.mockClear();
+
+    process.emit("SIGTERM");
+    expect(tracer).not.toHaveBeenCalled();
+  });
+
+  it("通过 process.emit 触发 SIGINT 会走到 tracer 与 onSignal", () => {
+    const tracer = vi.fn();
+    const onSignal = vi.fn();
+    const { cleanup } = installCrashLogging({
+      tracer,
+      onFatal: () => {},
+      onSignal,
+    });
+
+    try {
+      process.emit("SIGINT");
+      expect(tracer).toHaveBeenCalledWith("signal received", { signal: "SIGINT" });
+      expect(onSignal).toHaveBeenCalledWith("SIGINT");
+    } finally {
+      cleanup();
+    }
+  });
+});

package/src/__tests__/session.test.ts

@@ -142,7 +142,7 @@ describe("getSessionStatus", () => {
     mockSessionInfo("chat-claude", { tool: "claude" });
     const status = await getSessionStatus("chat-claude");
     expect(status!.effort).not.toBeNull();
-    // model 必为非空字符串（默认 'default' 或环境变量值）；不应是占位符
+    // model 必为字符串（留空时显示 '(留空)'，否则为环境变量值）；不应是占位符
     expect(typeof status!.model).toBe("string");
     expect(status!.model.length).toBeGreaterThan(0);
   });
@@ -171,7 +171,7 @@ describe("getSessionStatus", () => {
     expect(status!.model).toBe("Composer 2 Fast");
   });
 
-  it("Cursor 会话：adapter 没返回 model 时使用占位符（区别于硬塞 'default'）", async () => {
+  it("Cursor 会话：adapter 没返回 model 时使用占位符（不应硬塞任何模型字面量）", async () => {
     mockSessionInfo("chat-cursor", { sessionId: "sid-cur", tool: "cursor" });
     _setAdapterForToolForTest(
       "cursor",

package/src/__tests__/web-ui.test.ts

@@ -0,0 +1,178 @@
+import { describe, it, expect } from "vitest";
+import {
+  applyClaudeApiMode,
+  chooseStartPath,
+  detectClaudeApiMode,
+} from "../web-ui.ts";
+
+// ---------------------------------------------------------------------------
+// detectClaudeApiMode — 加载已有 config 时如何判定 UI 初始模式
+// 契约：apiKey 或 baseUrl 任一非空（trim 后） → "thirdparty"，否则 "official"。
+// ---------------------------------------------------------------------------
+
+describe("detectClaudeApiMode", () => {
+  it("两者都缺失 → official", () => {
+    expect(detectClaudeApiMode(undefined)).toBe("official");
+    expect(detectClaudeApiMode({})).toBe("official");
+  });
+
+  it("两者都为空字符串 → official", () => {
+    expect(detectClaudeApiMode({ apiKey: "", baseUrl: "" })).toBe("official");
+  });
+
+  it("两者都全空白 → official", () => {
+    expect(detectClaudeApiMode({ apiKey: "  ", baseUrl: "\t\n" })).toBe(
+      "official",
+    );
+  });
+
+  it("apiKey 非空 → thirdparty（即使 baseUrl 为空）", () => {
+    expect(detectClaudeApiMode({ apiKey: "sk-x", baseUrl: "" })).toBe(
+      "thirdparty",
+    );
+  });
+
+  it("baseUrl 非空 → thirdparty（即使 apiKey 为空）", () => {
+    expect(
+      detectClaudeApiMode({ apiKey: "", baseUrl: "https://gw/anthropic" }),
+    ).toBe("thirdparty");
+  });
+
+  it("两者都非空 → thirdparty", () => {
+    expect(
+      detectClaudeApiMode({
+        apiKey: "sk-x",
+        baseUrl: "https://gw/anthropic",
+      }),
+    ).toBe("thirdparty");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// applyClaudeApiMode — 服务端写入前归一化扁平 vars
+// 关键契约：
+//   - mode=official 时即使 vars 不含这两个键，也要写入 ""（覆盖原 config.json）
+//   - mode=thirdparty 时原样保留（包括前端传 ""）
+//   - mode 未传 默认按 official 兌底（不保留可能误填的密钥）
+// ---------------------------------------------------------------------------
+
+describe("applyClaudeApiMode", () => {
+  it("mode=official 时清空 CLAUDE_API_KEY / CLAUDE_BASE_URL（即使 vars 没传）", () => {
+    const out = applyClaudeApiMode({ CHATCCC_APP_ID: "x" }, "official");
+    expect(out).toEqual({
+      CHATCCC_APP_ID: "x",
+      CLAUDE_API_KEY: "",
+      CLAUDE_BASE_URL: "",
+    });
+  });
+
+  it("mode=official 时覆盖前端误传的非空 apiKey / baseUrl", () => {
+    const out = applyClaudeApiMode(
+      {
+        CLAUDE_API_KEY: "sk-leftover",
+        CLAUDE_BASE_URL: "https://leftover/anthropic",
+        CHATCCC_APP_ID: "x",
+      },
+      "official",
+    );
+    expect(out.CLAUDE_API_KEY).toBe("");
+    expect(out.CLAUDE_BASE_URL).toBe("");
+    expect(out.CHATCCC_APP_ID).toBe("x");
+  });
+
+  it("mode=thirdparty 时原样保留前端值", () => {
+    const out = applyClaudeApiMode(
+      {
+        CLAUDE_API_KEY: "sk-test",
+        CLAUDE_BASE_URL: "https://gw/anthropic",
+      },
+      "thirdparty",
+    );
+    expect(out).toEqual({
+      CLAUDE_API_KEY: "sk-test",
+      CLAUDE_BASE_URL: "https://gw/anthropic",
+    });
+  });
+
+  it("mode=thirdparty 时保留前端主动提交的 ''（允许局部清空）", () => {
+    const out = applyClaudeApiMode(
+      { CLAUDE_API_KEY: "", CLAUDE_BASE_URL: "https://gw/anthropic" },
+      "thirdparty",
+    );
+    expect(out.CLAUDE_API_KEY).toBe("");
+    expect(out.CLAUDE_BASE_URL).toBe("https://gw/anthropic");
+  });
+
+  it("mode 未传（undefined） → 按 official 兌底清空", () => {
+    const out = applyClaudeApiMode(
+      { CLAUDE_API_KEY: "sk-x" },
+      undefined,
+    );
+    expect(out.CLAUDE_API_KEY).toBe("");
+    expect(out.CLAUDE_BASE_URL).toBe("");
+  });
+
+  it("mode 是未知字符串 → 按 official 兌底清空", () => {
+    const out = applyClaudeApiMode(
+      { CLAUDE_API_KEY: "sk-x" },
+      "garbage-mode",
+    );
+    expect(out.CLAUDE_API_KEY).toBe("");
+    expect(out.CLAUDE_BASE_URL).toBe("");
+  });
+
+  it("不修改入参对象（返回新对象）", () => {
+    const input = { CLAUDE_API_KEY: "sk-x" };
+    const out = applyClaudeApiMode(input, "official");
+    expect(input).toEqual({ CLAUDE_API_KEY: "sk-x" }); // 原对象未变
+    expect(out).not.toBe(input);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// chooseStartPath — /api/start 的路径选择
+// 关键护栏：
+//   - setup 模式（hasInplaceActivateHook=true）下 isServiceRunning 永远为 true
+//     （setup 进程自己占着 PID 文件），必须无条件走 inplace；否则用户点
+//     "保存并启动"将永远拿到 "Service is already running"。
+//   - dashboard 模式 + service 已运行（通常就是当前进程自己）→ "reload"：
+//     用户点"保存并启动"想让新 config 生效，但服务正在跑——不真重启，仅
+//     调用 reloadConfigFromDisk() 刷新进程内 export let 常量。绝不能再
+//     返回"already running"挡用户路。
+//   - dashboard 模式 + service 未运行 → spawn 一个新的（旧 service 退出后场景）。
+// ---------------------------------------------------------------------------
+
+describe("chooseStartPath", () => {
+  it("setup 模式（注入 inplace hook）→ inplace（不管 PID 文件状态）", () => {
+    expect(
+      chooseStartPath({
+        hasInplaceActivateHook: true,
+        isServiceRunning: true,
+      }),
+    ).toBe("inplace");
+    expect(
+      chooseStartPath({
+        hasInplaceActivateHook: true,
+        isServiceRunning: false,
+      }),
+    ).toBe("inplace");
+  });
+
+  it("dashboard 模式 + service 已运行 → reload（仅刷新 config，不真重启）", () => {
+    expect(
+      chooseStartPath({
+        hasInplaceActivateHook: false,
+        isServiceRunning: true,
+      }),
+    ).toBe("reload");
+  });
+
+  it("dashboard 模式 + service 未运行 → spawn", () => {
+    expect(
+      chooseStartPath({
+        hasInplaceActivateHook: false,
+        isServiceRunning: false,
+      }),
+    ).toBe("spawn");
+  });
+});