@winspan/claude-forge 8.41.0 → 8.51.0

package/tests/unit/ai-provider-retry.test.ts

@@ -0,0 +1,194 @@
+/**
+ * Tests for ClaudeProvider retry + timeout logic.
+ *
+ * The SDK client is replaced with a mock object exposing only
+ * `messages.create`; the provider never hits the network.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { ClaudeProvider, timing } from '../../src/core/ai/provider.js';
+
+/** Shape of what `messages.create` must return for the provider to succeed. */
+function makeOkResponse(text = 'ok') {
+  return {
+    content: [{ type: 'text', text }],
+    usage: { input_tokens: 3, output_tokens: 5 },
+    model: 'claude-sonnet-4-20250514',
+  };
+}
+
+/** Build an error object that mimics an Anthropic APIError. */
+function apiError(status: number, message = `HTTP ${status}`): Error & { status: number } {
+  const err = new Error(message) as Error & { status: number };
+  err.status = status;
+  return err;
+}
+
+function abortError(message = 'Request aborted'): Error {
+  const err = new Error(message);
+  err.name = 'AbortError';
+  return err;
+}
+
+function installMockClient(provider: ClaudeProvider, create: ReturnType<typeof vi.fn>) {
+  // @ts-expect-error — overriding internal client for test isolation
+  provider.client = { messages: { create } };
+}
+
+describe('ClaudeProvider retry + timeout', () => {
+  let provider: ClaudeProvider;
+  let delaySpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    provider = new ClaudeProvider('test-key', 'claude-sonnet-4-20250514');
+    vi.useRealTimers();
+    // Skip the actual backoff wait so tests finish quickly while still being
+    // able to assert the backoff durations via spy call args.
+    delaySpy = vi.spyOn(timing, 'delay').mockResolvedValue();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.useRealTimers();
+  });
+
+  it('retries on 429 rate limit then succeeds', async () => {
+    const create = vi
+      .fn()
+      .mockRejectedValueOnce(apiError(429, 'rate limited'))
+      .mockRejectedValueOnce(apiError(429, 'rate limited'))
+      .mockResolvedValueOnce(makeOkResponse('done'));
+    installMockClient(provider, create);
+
+    const res = await provider.complete('hi', { maxRetries: 2, timeoutMs: 1000 });
+
+    expect(res).toBe('done');
+    expect(create).toHaveBeenCalledTimes(3);
+  });
+
+  it('retries on 5xx errors then succeeds', async () => {
+    const create = vi
+      .fn()
+      .mockRejectedValueOnce(apiError(503, 'unavailable'))
+      .mockRejectedValueOnce(apiError(500, 'boom'))
+      .mockResolvedValueOnce(makeOkResponse('recovered'));
+    installMockClient(provider, create);
+
+    const res = await provider.complete('hi', { maxRetries: 2, timeoutMs: 1000 });
+
+    expect(res).toBe('recovered');
+    expect(create).toHaveBeenCalledTimes(3);
+  });
+
+  it('gives up after maxRetries when errors keep coming', async () => {
+    const create = vi.fn().mockRejectedValue(apiError(500, 'persistent'));
+    installMockClient(provider, create);
+
+    await expect(
+      provider.complete('hi', { maxRetries: 2, timeoutMs: 1000 }),
+    ).rejects.toThrow('persistent');
+
+    // attempt 0 + 2 retries = 3 calls
+    expect(create).toHaveBeenCalledTimes(3);
+  });
+
+  it('does not retry on 4xx other than 429', async () => {
+    const create = vi.fn().mockRejectedValue(apiError(400, 'bad request'));
+    installMockClient(provider, create);
+
+    await expect(
+      provider.complete('hi', { maxRetries: 3, timeoutMs: 1000 }),
+    ).rejects.toThrow('bad request');
+
+    expect(create).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not retry on 401 auth errors', async () => {
+    const create = vi.fn().mockRejectedValue(apiError(401, 'unauthorized'));
+    installMockClient(provider, create);
+
+    await expect(
+      provider.complete('hi', { maxRetries: 3, timeoutMs: 1000 }),
+    ).rejects.toThrow('unauthorized');
+
+    expect(create).toHaveBeenCalledTimes(1);
+  });
+
+  it('timeout triggers retry and eventually surfaces', async () => {
+    // Each call hangs longer than timeoutMs; we reject with AbortError to mirror
+    // what the SDK throws when its signal fires, so we don't have to wire a
+    // real long-running pending promise into the test.
+    const create = vi.fn().mockImplementation(
+      () => new Promise((_resolve, reject) => {
+        setTimeout(() => reject(abortError()), 20);
+      }),
+    );
+    installMockClient(provider, create);
+
+    await expect(
+      provider.complete('hi', { maxRetries: 2, timeoutMs: 10 }),
+    ).rejects.toMatchObject({ name: 'AbortError' });
+
+    expect(create).toHaveBeenCalledTimes(3);
+  });
+
+  it('uses exponential backoff between retries (1000ms, 2000ms, ...)', async () => {
+    const create = vi
+      .fn()
+      .mockRejectedValueOnce(apiError(500))
+      .mockRejectedValueOnce(apiError(500))
+      .mockResolvedValueOnce(makeOkResponse());
+    installMockClient(provider, create);
+
+    const res = await provider.complete('hi', { maxRetries: 2, timeoutMs: 5000 });
+
+    expect(res).toBe('ok');
+    expect(create).toHaveBeenCalledTimes(3);
+    // delay() is called once per retry with exponential durations.
+    const delayCalls = delaySpy.mock.calls.map((args) => args[0]);
+    expect(delayCalls).toEqual([1000, 2000]);
+  });
+
+  it('propagates external signal aborts without retry', async () => {
+    const create = vi.fn().mockImplementation(() => {
+      return new Promise((_resolve, reject) => {
+        // Simulate SDK surfacing AbortError once external signal fires.
+        setTimeout(() => reject(abortError('user abort')), 5);
+      });
+    });
+    installMockClient(provider, create);
+
+    const controller = new AbortController();
+    setTimeout(() => controller.abort(), 1);
+
+    await expect(
+      provider.complete('hi', { maxRetries: 3, timeoutMs: 1000, signal: controller.signal }),
+    ).rejects.toThrow('user abort');
+
+    // Only one attempt: external aborts short-circuit retry.
+    expect(create).toHaveBeenCalledTimes(1);
+  });
+
+  it('completeWithUsage returns usage and model on success', async () => {
+    const create = vi.fn().mockResolvedValue(makeOkResponse('hello'));
+    installMockClient(provider, create);
+
+    const res = await provider.completeWithUsage('prompt', { timeoutMs: 500 });
+    expect(res.text).toBe('hello');
+    expect(res.usage).toEqual({ input_tokens: 3, output_tokens: 5 });
+    expect(res.model).toBe('claude-sonnet-4-20250514');
+  });
+
+  it('passes signal and maxRetries:0 to the SDK', async () => {
+    const create = vi.fn().mockResolvedValue(makeOkResponse());
+    installMockClient(provider, create);
+
+    await provider.complete('hi', { timeoutMs: 1234, maxRetries: 1 });
+
+    expect(create).toHaveBeenCalledTimes(1);
+    const [, requestOptions] = create.mock.calls[0];
+    expect(requestOptions.maxRetries).toBe(0);
+    expect(requestOptions.timeout).toBe(1234);
+    expect(requestOptions.signal).toBeDefined();
+  });
+});

package/tests/unit/ai-provider-vision.test.ts

@@ -0,0 +1,224 @@
+/**
+ * Tests for ClaudeProvider.completeWithImage (Vision support).
+ *
+ * The SDK client is replaced with a mock that captures the request body so we
+ * can assert content-block shape, base64 encoding, and that the existing
+ * retry/timeout pipeline is reused. The provider never hits the network.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { ClaudeProvider, timing } from '../../src/core/ai/provider.js';
+import type { ImageInput } from '../../src/core/ai/types.js';
+
+/** Minimal valid response shape the SDK returns. */
+function makeOkResponse(text = 'image described'): unknown {
+  return {
+    content: [{ type: 'text', text }],
+    usage: { input_tokens: 100, output_tokens: 20 },
+    model: 'claude-sonnet-4-20250514',
+  };
+}
+
+/** Build an Anthropic-style API error. */
+function apiError(status: number, message = `HTTP ${status}`): Error & { status: number } {
+  const err = new Error(message) as Error & { status: number };
+  err.status = status;
+  return err;
+}
+
+function installMockClient(provider: ClaudeProvider, create: ReturnType<typeof vi.fn>): void {
+  // @ts-expect-error — overriding internal client for test isolation
+  provider.client = { messages: { create } };
+}
+
+/** Create a tmp file containing the given bytes; returns the absolute path. */
+async function writeTmpImage(bytes: Buffer, suffix = '.png'): Promise<string> {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'forge-vision-'));
+  const file = path.join(dir, `img${suffix}`);
+  await fs.writeFile(file, bytes);
+  return file;
+}
+
+describe('ClaudeProvider.completeWithImage', () => {
+  let provider: ClaudeProvider;
+  // The retry path uses timing.delay; stub it to keep retry tests fast.
+  let delaySpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    provider = new ClaudeProvider('test-key', 'claude-sonnet-4-20250514');
+    delaySpy = vi.spyOn(timing, 'delay').mockResolvedValue();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('encodes image as base64 and packs an image+text user message', async () => {
+    const bytes = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]); // PNG magic
+    const imgPath = await writeTmpImage(bytes, '.png');
+
+    const create = vi.fn().mockResolvedValue(makeOkResponse('a tiny png'));
+    installMockClient(provider, create);
+
+    const text = await provider.completeWithImage('What is this?', {
+      images: [{ path: imgPath, mediaType: 'image/png' }],
+      timeoutMs: 1000,
+    });
+
+    expect(text).toBe('a tiny png');
+    expect(create).toHaveBeenCalledTimes(1);
+
+    const [requestBody] = create.mock.calls[0];
+    expect(requestBody.messages).toHaveLength(1);
+
+    const msg = requestBody.messages[0];
+    expect(msg.role).toBe('user');
+    expect(Array.isArray(msg.content)).toBe(true);
+    expect(msg.content).toHaveLength(2);
+
+    // Image block first, text block second.
+    expect(msg.content[0]).toEqual({
+      type: 'image',
+      source: {
+        type: 'base64',
+        media_type: 'image/png',
+        data: bytes.toString('base64'),
+      },
+    });
+    expect(msg.content[1]).toEqual({ type: 'text', text: 'What is this?' });
+  });
+
+  it('supports multiple images in stable order before the prompt', async () => {
+    const a = await writeTmpImage(Buffer.from('aaaa'), '.jpg');
+    const b = await writeTmpImage(Buffer.from('bbbb'), '.webp');
+
+    const create = vi.fn().mockResolvedValue(makeOkResponse());
+    installMockClient(provider, create);
+
+    const images: ImageInput[] = [
+      { path: a, mediaType: 'image/jpeg' },
+      { path: b, mediaType: 'image/webp' },
+    ];
+
+    await provider.completeWithImage('compare these', { images, timeoutMs: 1000 });
+
+    const [requestBody] = create.mock.calls[0];
+    const content = requestBody.messages[0].content as Array<{ type: string }>;
+    expect(content.map((c) => c.type)).toEqual(['image', 'image', 'text']);
+
+    const block0 = content[0] as { source: { media_type: string; data: string } };
+    const block1 = content[1] as { source: { media_type: string; data: string } };
+    expect(block0.source.media_type).toBe('image/jpeg');
+    expect(block0.source.data).toBe(Buffer.from('aaaa').toString('base64'));
+    expect(block1.source.media_type).toBe('image/webp');
+    expect(block1.source.data).toBe(Buffer.from('bbbb').toString('base64'));
+  });
+
+  it('forwards system / model / maxTokens through to messages.create', async () => {
+    const imgPath = await writeTmpImage(Buffer.from('xy'), '.gif');
+
+    const create = vi.fn().mockResolvedValue(makeOkResponse());
+    installMockClient(provider, create);
+
+    await provider.completeWithImage('describe', {
+      images: [{ path: imgPath, mediaType: 'image/gif' }],
+      system: 'you are a vision expert',
+      model: 'claude-opus-4-20250514',
+      maxTokens: 2048,
+      timeoutMs: 1234,
+    });
+
+    const [requestBody, requestOptions] = create.mock.calls[0];
+    expect(requestBody.system).toBe('you are a vision expert');
+    expect(requestBody.model).toBe('claude-opus-4-20250514');
+    expect(requestBody.max_tokens).toBe(2048);
+    // Confirm we still strip retries (own retry pipeline) and pass timeout.
+    expect(requestOptions.maxRetries).toBe(0);
+    expect(requestOptions.timeout).toBe(1234);
+  });
+
+  it('throws a clear error when the file does not exist', async () => {
+    const create = vi.fn().mockResolvedValue(makeOkResponse());
+    installMockClient(provider, create);
+
+    const missing = path.join(os.tmpdir(), 'forge-vision-missing-' + Date.now() + '.png');
+
+    await expect(
+      provider.completeWithImage('hi', {
+        images: [{ path: missing, mediaType: 'image/png' }],
+        timeoutMs: 1000,
+      }),
+    ).rejects.toThrow(/failed to read image/i);
+
+    // Validation must run before any API request.
+    expect(create).not.toHaveBeenCalled();
+  });
+
+  it('rejects unsupported media types up front', async () => {
+    const create = vi.fn().mockResolvedValue(makeOkResponse());
+    installMockClient(provider, create);
+
+    const imgPath = await writeTmpImage(Buffer.from('xx'), '.bmp');
+
+    await expect(
+      provider.completeWithImage('hi', {
+        // @ts-expect-error — intentionally invalid to test runtime guard
+        images: [{ path: imgPath, mediaType: 'image/bmp' }],
+        timeoutMs: 1000,
+      }),
+    ).rejects.toThrow(/unsupported media type/i);
+
+    expect(create).not.toHaveBeenCalled();
+  });
+
+  it('throws when images array is empty', async () => {
+    const create = vi.fn().mockResolvedValue(makeOkResponse());
+    installMockClient(provider, create);
+
+    await expect(
+      provider.completeWithImage('hi', { images: [], timeoutMs: 1000 }),
+    ).rejects.toThrow(/at least one image/i);
+
+    expect(create).not.toHaveBeenCalled();
+  });
+
+  it('reuses retry pipeline: retries on 429 then succeeds', async () => {
+    const imgPath = await writeTmpImage(Buffer.from('z'), '.png');
+
+    const create = vi
+      .fn()
+      .mockRejectedValueOnce(apiError(429, 'rate limited'))
+      .mockResolvedValueOnce(makeOkResponse('done'));
+    installMockClient(provider, create);
+
+    const text = await provider.completeWithImage('hi', {
+      images: [{ path: imgPath, mediaType: 'image/png' }],
+      maxRetries: 2,
+      timeoutMs: 1000,
+    });
+
+    expect(text).toBe('done');
+    expect(create).toHaveBeenCalledTimes(2);
+    expect(delaySpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('reuses retry pipeline: surfaces non-retriable 400 immediately', async () => {
+    const imgPath = await writeTmpImage(Buffer.from('z'), '.png');
+
+    const create = vi.fn().mockRejectedValue(apiError(400, 'bad image'));
+    installMockClient(provider, create);
+
+    await expect(
+      provider.completeWithImage('hi', {
+        images: [{ path: imgPath, mediaType: 'image/png' }],
+        maxRetries: 3,
+        timeoutMs: 1000,
+      }),
+    ).rejects.toThrow('bad image');
+
+    expect(create).toHaveBeenCalledTimes(1);
+  });
+});

package/tests/unit/claudemd-generator.test.ts

@@ -0,0 +1,68 @@
+/**
+ * Characterization tests for ClaudeMdGenerator — safety-net phase.
+ *
+ * These tests lock down the observable behavior of the SWARM_PROTOCOL
+ * template embedded in claudemd-generator.ts BEFORE the template sync fix.
+ *
+ * NOTE: assertions marked "OLD BEHAVIOR" will be updated in the fix phase
+ * to reflect the new template.
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { ClaudeMdGenerator } from '../../src/claudemd/claudemd-generator.js';
+import type { ClaudeProvider } from '../../src/core/ai/provider.js';
+
+function makeMockAi(response?: string): ClaudeProvider {
+  return {
+    complete: vi.fn().mockRejectedValue(new Error('ai disabled for tests')),
+  } as unknown as ClaudeProvider;
+}
+
+describe('ClaudeMdGenerator — SWARM_PROTOCOL template characterization', () => {
+  let generator: ClaudeMdGenerator;
+
+  beforeEach(() => {
+    generator = new ClaudeMdGenerator(makeMockAi());
+  });
+
+  it('generates output that contains the core behavior rules section', async () => {
+    const result = await generator.generate('/tmp');
+    expect(result).toContain('## 核心行为规则');
+  });
+
+  it('generated output contains the Two-Phase Workflow section with NEW title (BMAD 默认路径)', async () => {
+    const result = await generator.generate('/tmp');
+    // NEW behavior after template sync fix
+    expect(result).toContain('Two-Phase Workflow (BMAD 默认路径)');
+  });
+
+  it('generated output contains the 工作流升级判定 section', async () => {
+    const result = await generator.generate('/tmp');
+    expect(result).toContain('工作流升级判定');
+  });
+
+  it('generated output contains harness-hotfix workflow entry', async () => {
+    const result = await generator.generate('/tmp');
+    expect(result).toContain('harness-hotfix');
+  });
+
+  it('generated output contains refactor-safe workflow entry', async () => {
+    const result = await generator.generate('/tmp');
+    expect(result).toContain('refactor-safe');
+  });
+
+  it('generated output contains 测试覆盖率 < 50% condition', async () => {
+    const result = await generator.generate('/tmp');
+    expect(result).toContain('测试覆盖率 < 50%');
+  });
+
+  it('generated output contains Agent 委托规则 section', async () => {
+    const result = await generator.generate('/tmp');
+    expect(result).toContain('## Agent 委托规则');
+  });
+
+  it('generated output does NOT contain OLD Two-Phase title (Design-First)', async () => {
+    const result = await generator.generate('/tmp');
+    // After fix, old title must be gone
+    expect(result).not.toContain('Two-Phase Workflow (Design-First)');
+  });
+});

package/tests/unit/cli-mcp.test.ts

@@ -0,0 +1,141 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+// Mock 必须在 import 被测模块之前
+vi.mock('node:child_process', () => ({
+  execSync: vi.fn(),
+}));
+vi.mock('node:fs', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('node:fs')>();
+  return {
+    ...actual,
+    existsSync: vi.fn(),
+    readFileSync: vi.fn(),
+  };
+});
+
+import { execSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import {
+  isClaudeCodeInstalled,
+  isMcpRegistered,
+  getMcpServerUrl,
+} from '../../src/cli/commands/mcp.js';
+
+const mockExecSync = vi.mocked(execSync);
+const mockExistsSync = vi.mocked(existsSync);
+const mockReadFileSync = vi.mocked(readFileSync);
+
+describe('cf mcp command', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('isClaudeCodeInstalled', () => {
+    it('returns true when `command -v claude` succeeds', () => {
+      mockExecSync.mockReturnValue(Buffer.from(''));
+      expect(isClaudeCodeInstalled()).toBe(true);
+      // 用 command -v 而不是 which（POSIX 标准）
+      expect(mockExecSync).toHaveBeenCalledWith('command -v claude', { stdio: 'ignore' });
+    });
+
+    it('returns false when execSync throws', () => {
+      mockExecSync.mockImplementation(() => {
+        throw new Error('not found');
+      });
+      expect(isClaudeCodeInstalled()).toBe(false);
+    });
+  });
+
+  describe('isMcpRegistered', () => {
+    it('returns false when `claude mcp get` throws (not registered)', () => {
+      mockExecSync.mockImplementation(() => {
+        throw new Error('No MCP server found');
+      });
+      expect(isMcpRegistered()).toEqual({ registered: false });
+    });
+
+    it('returns true with extracted URL when registered', () => {
+      mockExecSync.mockReturnValue(
+        'claude-forge:\n  Scope: User config\n  Status: ✓ Connected\n  Type: http\n  URL: http://127.0.0.1:3456/mcp\n',
+      );
+      const result = isMcpRegistered();
+      expect(result.registered).toBe(true);
+      expect(result.url).toBe('http://127.0.0.1:3456/mcp');
+    });
+
+    it('returns registered=true with undefined url when output lacks URL line', () => {
+      mockExecSync.mockReturnValue('claude-forge:\n  Scope: User config\n');
+      const result = isMcpRegistered();
+      expect(result.registered).toBe(true);
+      expect(result.url).toBeUndefined();
+    });
+
+    it('uses `claude mcp get claude-forge` command', () => {
+      mockExecSync.mockReturnValue('claude-forge:\n  URL: http://x\n');
+      isMcpRegistered();
+      expect(mockExecSync).toHaveBeenCalledWith(
+        'claude mcp get claude-forge',
+        expect.objectContaining({ encoding: 'utf-8' }),
+      );
+    });
+  });
+
+  describe('getMcpServerUrl', () => {
+    it('builds URL from default port', () => {
+      const url = getMcpServerUrl();
+      // 默认端口是 3456（来自 DEFAULTS.WEB_PORT）
+      expect(url).toMatch(/^http:\/\/127\.0\.0\.1:\d+\/mcp$/);
+    });
+  });
+
+  describe('command syntax sanity', () => {
+    // 这组测试是"防回归"——锁定 cf mcp register 实际执行的命令格式，
+    // 避免再次出现 `--url` 这种不存在的选项
+    it('register command syntax must use --transport http and -H header', () => {
+      // 单纯检查源文件里的 execSync 字符串模板（black-box sanity check）
+      // 不在这里执行 registerCommand，因为它会 process.exit
+      const mcpSource = readFileSync('src/cli/commands/mcp.ts', 'utf-8');
+      // 注意：这里调用的是真实 readFileSync（mock 不影响 import 之外的调用），
+      // 但因为我们 mock 了 readFileSync，这条测试需要 setup 真实读
+      // —— 为了简化，我们做静态字符串断言
+      // (skip if mock returned a fake value)
+    });
+  });
+});
+
+// 单独 describe：通过读取真实源代码验证命令格式
+describe('cf mcp register: command format static check', () => {
+  it('source code uses `claude mcp add --transport http`', async () => {
+    // 用 dynamic import 拿到 node:fs 的真实模块（绕过文件级 mock）
+    const fs = await vi.importActual<typeof import('node:fs')>('node:fs');
+    const src = fs.readFileSync('src/cli/commands/mcp.ts', 'utf-8');
+
+    expect(src, 'must NOT contain deprecated --url flag').not.toMatch(/--url\s/);
+    expect(src, 'must use --transport http').toMatch(/--transport http/);
+    expect(src, 'must use -s user (user scope)').toMatch(/-s\s+\$\{SCOPE\}|-s user/);
+    expect(src, 'must pass Authorization header').toMatch(/Authorization: Bearer/);
+  });
+
+  it('source code uses correct `claude mcp remove` syntax', async () => {
+    const fs = await vi.importActual<typeof import('node:fs')>('node:fs');
+    const src = fs.readFileSync('src/cli/commands/mcp.ts', 'utf-8');
+
+    expect(src).toMatch(/claude mcp remove -s \$\{SCOPE\}|claude mcp remove -s user/);
+  });
+
+  it('source code uses `claude mcp get` for status check (not settings.json)', async () => {
+    const fs = await vi.importActual<typeof import('node:fs')>('node:fs');
+    const src = fs.readFileSync('src/cli/commands/mcp.ts', 'utf-8');
+
+    expect(src).toMatch(/claude mcp get/);
+    // 不应该再用 ~/.claude/settings.json 路径来检查注册状态
+    // （只允许在注释里出现作为历史对比，但 join() 调用不能拼这个路径）
+    expect(src, 'must not join settings.json in code').not.toMatch(
+      /join\([^)]*['"]settings\.json['"]\)/,
+    );
+  });
+});