@productbrain/cli 0.1.0-beta.14 → 0.1.0-beta.14010

package/dist/commands/doctor.test.js

@@ -0,0 +1,652 @@
+/**
+ * Tests for pb doctor — health check command.
+ * WP-301 Slice 2 (base checks).
+ * WP-302 Slice 3 (--fix, --dry-run).
+ * WP-302 Review Issue 2 (profile-aware config check).
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+// We test runDoctor by capturing its console output and process.exit calls.
+// Mock dependencies before importing the module under test.
+const upgradeHotkeyMocks = vi.hoisted(() => ({
+    cachedLatestVersion: undefined,
+    // simulateInput drives the positive hotkey tests: 'u' -> upgrade, 'q' -> dismiss, undefined -> no-op
+    simulateInput: undefined,
+    render: vi.fn((node, _options) => {
+        // The UpgradePrompt element is created with onExit as a prop — invoke it synchronously
+        // so `shouldUpgrade` is set before runDoctor awaits waitUntilExit. Driving onExit
+        // sidesteps the un-mounted React tree (useInput would never fire from a mocked render).
+        const onExit = node?.props?.onExit;
+        if (onExit) {
+            if (upgradeHotkeyMocks.simulateInput === 'u')
+                onExit(true);
+            else if (upgradeHotkeyMocks.simulateInput === 'q')
+                onExit(false);
+        }
+        return {
+            waitUntilExit: vi.fn(async () => { }),
+            unmount: vi.fn(),
+        };
+    }),
+    runUpgrade: vi.fn(),
+    useInput: vi.fn(),
+}));
+// Mock config — controls HOME_ENV_PATH, HOME_CONFIG_DIR, and getConfigSafe exports
+const mockHomeEnvPath = '/mock/.config/productbrain/.env';
+const mockHomeConfigDir = '/mock/.config/productbrain';
+const configFailure = vi.hoisted(() => ({
+    value: null,
+}));
+// doctor reads the preview binding through the same effective-binding mirror the PREVIEW banner
+// uses, so a test can bind a preview workspace here instead of writing a real config.local.json.
+const previewBinding = vi.hoisted(() => ({
+    value: null,
+}));
+// What .productbrain/config.local.json declares. Defaults to null — the file is absent — so the
+// checks that assert the profiles-dir / legacy / not-found fall-through stay unaffected.
+const localProjectConfig = vi.hoisted(() => ({
+    value: null,
+}));
+vi.mock('../lib/config.js', () => ({
+    HOME_ENV_PATH: mockHomeEnvPath,
+    HOME_CONFIG_DIR: mockHomeConfigDir,
+    readLocalProjectConfig: () => localProjectConfig.value,
+    getPreviewBinding: () => previewBinding.value,
+    // getConfigSafe reads from process.env so tests can control config state
+    // via beforeEach env manipulation, matching how the real function works.
+    // The failure copy below mirrors configResult.ts verbatim — doctor now derives its own
+    // wording from these fields, so a drifting double would assert copy no surface emits.
+    getConfigSafe: () => {
+        if (configFailure.value)
+            return configFailure.value;
+        const apiKey = process.env.PRODUCTBRAIN_API_KEY ?? '';
+        const siteUrl = (process.env.CONVEX_SITE_URL ?? 'https://trustworthy-kangaroo-277.convex.site').replace(/\/$/, '');
+        if (!apiKey) {
+            return {
+                ok: false,
+                kind: 'missing-key',
+                reason: 'No API key configured.',
+                guidance: 'Run pb connect <token> in your project folder. Get your connect command at https://work.productbrain.io/settings/api-keys.',
+                nextCommand: 'pb connect <token>',
+            };
+        }
+        if (!apiKey.startsWith('pb_sk_')) {
+            // This double resolves from process.env, so it mirrors configResult.ts's ENV branch:
+            // an exported key outranks every stored profile, so `pb login` cannot repair it.
+            return {
+                ok: false,
+                kind: 'invalid-key',
+                reason: 'Invalid API key format, from the PRODUCTBRAIN_API_KEY environment variable. A key starts with pb_sk_ or pb_agent_. Get one from Settings, API Keys.',
+                guidance: 'Unset PRODUCTBRAIN_API_KEY, or replace it with a valid key — it outranks every stored profile, so `pb login` cannot repair this.',
+                nextCommand: 'pb doctor',
+            };
+        }
+        return { ok: true, apiKey, siteUrl, source: 'env' };
+    },
+}));
+// Mock profiles — controls profile-aware config check
+const mockProfilesDir = '/mock/.config/productbrain/profiles';
+let mockProfiles = [];
+vi.mock('../lib/profiles.js', () => ({
+    listProfiles: () => mockProfiles,
+    PROFILES_DIR: mockProfilesDir,
+}));
+// Mock client — controls reachability
+const mockMcpCall = vi.fn();
+vi.mock('../lib/client.js', () => ({
+    kernelCall: (...args) => mockMcpCall(...args),
+}));
+vi.mock('../lib/update-check.js', async () => {
+    const actual = await vi.importActual('../lib/update-check.js');
+    return {
+        ...actual,
+        // readCachedLatestVersion: no longer called from doctor post-Task-6 (live-resolve backstop);
+        // retained only so any other update-check consumer mocked via this factory stays intact.
+        readCachedLatestVersion: () => upgradeHotkeyMocks.cachedLatestVersion,
+        resolveLatestVersion: vi.fn(async () => upgradeHotkeyMocks.cachedLatestVersion ?? null),
+    };
+});
+vi.mock('./upgrade.js', () => ({
+    runUpgrade: (...args) => upgradeHotkeyMocks.runUpgrade(...args),
+}));
+vi.mock('ink', () => ({
+    render: (node, options) => upgradeHotkeyMocks.render(node, options),
+    Box: () => null,
+    Text: () => null,
+    useInput: (handler) => upgradeHotkeyMocks.useInput(handler),
+}));
+// Mock fs for config file check and fix actions
+const mockMkdirSync = vi.fn();
+const mockWriteFileSync = vi.fn();
+vi.mock('node:fs', async () => {
+    const actual = await vi.importActual('node:fs');
+    return {
+        ...actual,
+        existsSync: vi.fn((path) => {
+            if (path === mockHomeEnvPath)
+                return mockLegacyEnvExists;
+            return actual.existsSync(path);
+        }),
+        mkdirSync: (...args) => mockMkdirSync(...args),
+        writeFileSync: (...args) => mockWriteFileSync(...args),
+        readFileSync: actual.readFileSync,
+    };
+});
+let mockLegacyEnvExists = true;
+/**
+ * Status of one doctor check line, read from its icon.
+ *
+ * Matching on the label alone is not enough: a failing check's detail can quote another check's
+ * label (the preview-binding refusal reason contains "API key"), so anchor on the label sitting
+ * immediately after the icon.
+ */
+function statusOf(output, label) {
+    const line = output
+        .split('\n')
+        .map((l) => l.replace(/\u001b\[\d+m/g, ''))
+        .find((l) => l.slice(2).startsWith(label));
+    if (!line)
+        return 'missing';
+    if (line.includes('\u2713'))
+        return 'pass';
+    if (line.includes('\u2717'))
+        return 'fail';
+    if (line.includes('\u26A0'))
+        return 'warn';
+    return 'missing';
+}
+describe('runDoctor', () => {
+    let consoleLogSpy;
+    let processExitSpy;
+    const originalEnv = { ...process.env };
+    const originalStdinIsTTY = process.stdin.isTTY;
+    const originalStdoutIsTTY = process.stdout.isTTY;
+    beforeEach(() => {
+        consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => { });
+        processExitSpy = vi.spyOn(process, 'exit').mockImplementation((() => { }));
+        mockLegacyEnvExists = true;
+        mockProfiles = [];
+        upgradeHotkeyMocks.cachedLatestVersion = undefined;
+        upgradeHotkeyMocks.simulateInput = undefined;
+        upgradeHotkeyMocks.render.mockClear();
+        upgradeHotkeyMocks.runUpgrade.mockClear();
+        upgradeHotkeyMocks.useInput.mockClear();
+        mockMkdirSync.mockClear();
+        mockWriteFileSync.mockClear();
+        configFailure.value = null;
+        previewBinding.value = null;
+        localProjectConfig.value = null;
+        // Set valid env defaults
+        process.env.PRODUCTBRAIN_API_KEY = 'pb_sk_test1234abcd';
+        process.env.CONVEX_SITE_URL = 'https://trustworthy-kangaroo-277.convex.site';
+        delete process.env.PB_ENV;
+        delete process.env.PB_CONNECT_GATEWAY_URL;
+        delete process.env.CI;
+        delete process.env.PB_NO_INTERACTIVE;
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+        // Restore original env
+        process.env = { ...originalEnv };
+        Object.defineProperty(process.stdin, 'isTTY', {
+            value: originalStdinIsTTY,
+            configurable: true,
+        });
+        Object.defineProperty(process.stdout, 'isTTY', {
+            value: originalStdoutIsTTY,
+            configurable: true,
+        });
+    });
+    // ── Normal mode (no flags) ──────────────────────────────────────────
+    it('all checks pass with valid config and reachable server', async () => {
+        mockMcpCall.mockResolvedValueOnce({ ok: true });
+        const { runDoctor } = await import('./doctor.js');
+        await runDoctor();
+        const output = consoleLogSpy.mock.calls.map((c) => c[0]).join('\n');
+        // All six checks should show pass symbol
+        expect(output).toContain('Config file');
+        expect(output).toContain(mockHomeEnvPath);
+        expect(output).toContain('API key');
+        expect(output).toContain('pb_sk_te****');
+        expect(output).toContain('Environment');
+        expect(output).toContain('production (default)');
+        expect(output).toContain('connect redeem');
+        expect(output).toContain('https://trustworthy-kangaroo-277.convex.site');
+        expect(output).toContain('Reachability');
+        expect(output).toContain('OK (');
+        expect(output).toContain('Node');
+        expect(output).toContain(process.version);
+        expect(output).toContain('CLI');
+        // Should NOT exit with failure
+        expect(processExitSpy).not.toHaveBeenCalled();
+    });
+    it('reports missing API key', async () => {
+        delete process.env.PRODUCTBRAIN_API_KEY;
+        mockMcpCall.mockRejectedValueOnce(new Error('No API key'));
+        const { runDoctor } = await import('./doctor.js');
+        await runDoctor();
+        const output = consoleLogSpy.mock.calls.map((c) => c[0]).join('\n');
+        // Copy is the resolver's — with no key doctor renders its `guidance` alone (TASK-562, RULE-662).
+        expect(output).toContain('Run pb connect <token> in your project folder.');
+        expect(output).not.toContain('pb login');
+        // Should exit 1 because API key check failed
+        expect(processExitSpy).toHaveBeenCalledWith(1);
+    });
+    it('S2: reports a missing repo pin and its repair instead of pb login', async () => {
+        delete process.env.PRODUCTBRAIN_API_KEY;
+        configFailure.value = {
+            ok: false,
+            kind: 'missing-pin',
+            reason: 'This repo is a Product Brain project (.productbrain/config.json) but has no tenant pin in .productbrain/config.local.json.',
+            guidance: 'Run `pb profile use --local <profile>` to pin this repo to a workspace.',
+            nextCommand: 'pb profile use --local <profile>',
+        };
+        mockMcpCall.mockRejectedValueOnce(new Error('no tenant pin'));
+        const { runDoctor } = await import('./doctor.js');
+        await runDoctor();
+        const output = consoleLogSpy.mock.calls.map((c) => c[0]).join('\n');
+        expect(output).toContain('no tenant pin');
+        expect(output).toContain('pb profile use --local <profile>');
+        expect(output).not.toContain('pb login');
+        expect(statusOf(output, 'Config file')).toBe('fail');
+    });
+    it('S5: reports a dangling repo pin and its repair instead of pb login', async () => {
+        delete process.env.PRODUCTBRAIN_API_KEY;
+        configFailure.value = {
+            ok: false,
+            kind: 'profile-pin',
+            // The real message from resolvePinnedProfile() — it names the offending file itself, which
+            // is why checkConfigFile() no longer prefixes one.
+            reason: 'This repo is pinned to profile "deleted-workspace" (.productbrain/config.local.json), but that profile has no valid API key.',
+            guidance: 'Run `pb profile use --local <profile>` to fix the repo pin.',
+            nextCommand: 'pb profile use --local <profile>',
+        };
+        mockMcpCall.mockRejectedValueOnce(new Error('pinned to profile "deleted-workspace"'));
+        const { runDoctor } = await import('./doctor.js');
+        await runDoctor();
+        const output = consoleLogSpy.mock.calls.map((c) => c[0]).join('\n');
+        expect(output).toContain('deleted-workspace');
+        expect(output).toContain('pb profile use --local <profile>');
+        expect(output).not.toContain('pb login');
+        // The pinned file IS the fault: doctor must not green-light it on its first line while the
+        // key check below fails for the very same reason.
+        expect(statusOf(output, 'Config file')).toBe('fail');
+        expect(output).toContain('.productbrain/config.local.json');
+        expect(output).not.toContain(mockHomeEnvPath);
+    });
+    it('reports an incomplete preview binding as the Config file fault, not a pass', async () => {
+        delete process.env.PRODUCTBRAIN_API_KEY;
+        // A legacy .env exists, so the pre-refusal fall-through would have passed this check.
+        mockLegacyEnvExists = true;
+        configFailure.value = {
+            ok: false,
+            kind: 'preview-binding',
+            reason: 'This repo has an incomplete preview binding (.productbrain/config.local.json): missing deployment URL. Refusing to use its profile pin or another workspace instead.',
+            guidance: 'Run `npm run pb:preview` to repair the preview binding, or `npm run pb:real` to return to the repo pin.',
+            nextCommand: 'npm run pb:preview',
+        };
+        mockMcpCall.mockRejectedValueOnce(new Error('incomplete preview binding'));
+        const { runDoctor } = await import('./doctor.js');
+        await runDoctor();
+        const output = consoleLogSpy.mock.calls.map((c) => c[0]).join('\n');
+        expect(statusOf(output, 'Config file')).toBe('fail');
+        expect(output).toContain('missing deployment URL');
+        expect(output).toContain('npm run pb:preview');
+        // Neither the legacy .env nor a preview "pass" may stand in for the broken binding.
+        expect(output).not.toContain(mockHomeEnvPath);
+        expect(output).not.toContain('(preview binding)');
+        expect(processExitSpy).toHaveBeenCalledWith(1);
+    });
+    it('names the preview binding on the Config file line when the binding is the effective one', async () => {
+        previewBinding.value = { workspaceName: 'Preview Workspace' };
+        mockMcpCall.mockResolvedValueOnce({ ok: true });
+        const { runDoctor } = await import('./doctor.js');
+        await runDoctor();
+        const output = consoleLogSpy.mock.calls.map((c) => c[0]).join('\n');
+        expect(statusOf(output, 'Config file')).toBe('pass');
+        expect(output).toContain('.productbrain/config.local.json (preview binding)');
+        expect(processExitSpy).not.toHaveBeenCalled();
+    });
+    it('reports the env override on the Config file line instead of denying a shadowed preview marker', async () => {
+        // An exported key wins step 1 of the cascade, so loadEnv() reads nothing out of
+        // config.local.json — and getPreviewBinding() returns null under that override, which is what
+        // used to make doctor claim "no preview marker" about a file carrying preview: true.
+        process.env.PRODUCTBRAIN_API_KEY = 'pb_sk_exported_key';
+        localProjectConfig.value = {
+            apiKey: 'pb_sk_preview_key_0123456789abcdef',
+            siteUrl: 'https://my-preview.convex.site',
+            preview: true,
+            workspaceName: 'Preview Workspace',
+        };
+        mockMcpCall.mockResolvedValueOnce({ ok: true });
+        const { runDoctor } = await import('./doctor.js');
+        await runDoctor();
+        const output = consoleLogSpy.mock.calls.map((c) => c[0]).join('\n');
+        expect(output).toContain('.productbrain/config.local.json (overridden by PRODUCTBRAIN_API_KEY)');
+        expect(output).not.toContain('no preview marker');
+        // Nor may it call the shadowed file the effective binding, preview or otherwise.
+        expect(output).not.toContain('(preview binding)');
+        expect(output).not.toContain('(direct binding');
+        expect(statusOf(output, 'Config file')).toBe('pass');
+        expect(processExitSpy).not.toHaveBeenCalled();
+    });
+    it('leaves a profile pin described as the binding when no env key shadows it', async () => {
+        // The shadow report is conditioned on the env override, not on the file existing.
+        delete process.env.PRODUCTBRAIN_API_KEY;
+        localProjectConfig.value = { profile: 'my-workspace' };
+        configFailure.value = null;
+        mockMcpCall.mockRejectedValueOnce(new Error('No API key'));
+        const { runDoctor } = await import('./doctor.js');
+        await runDoctor();
+        const output = consoleLogSpy.mock.calls.map((c) => c[0]).join('\n');
+        expect(output).toContain('.productbrain/config.local.json (profile "my-workspace")');
+        expect(output).not.toContain('overridden by PRODUCTBRAIN_API_KEY');
+    });
+    it('an unusable site URL faults the Environment and leaves the API key unverified, not failed', async () => {
+        configFailure.value = {
+            ok: false,
+            kind: 'invalid-url',
+            // Copy kept in step with configResult.ts: the origin is named because a file-sourced URL
+            // outranks CONVEX_SITE_URL, so the env var is not the repair here.
+            reason: 'Site URL must use HTTPS (got "http://insecure.example.com…", from .productbrain/config.local.json). API keys must not be sent over unencrypted connections.',
+            guidance: 'Set an https:// URL in .productbrain/config.local.json.',
+            nextCommand: 'pb doctor',
+        };
+        mockMcpCall.mockRejectedValueOnce(new Error('insecure URL'));
+        const { runDoctor } = await import('./doctor.js');
+        await runDoctor();
+        const output = consoleLogSpy.mock.calls.map((c) => c[0]).join('\n');
+        // The key resolved fine — only the gateway is at fault, and Environment owns that repair.
+        expect(statusOf(output, 'API key')).toBe('warn');
+        expect(output).toContain('Not verified — resolution stopped at the site URL');
+        expect(statusOf(output, 'Environment')).toBe('fail');
+        expect(output).toContain('must use HTTPS');
+        expect(output).not.toContain('Invalid API key format');
+        // The repair must name the file that supplied the URL, not a variable that would lose to it.
+        expect(output).toContain('.productbrain/config.local.json');
+    });
+    it('reports unreachable server', async () => {
+        mockMcpCall.mockRejectedValueOnce(new Error('fetch failed'));
+        const { runDoctor } = await import('./doctor.js');
+        await runDoctor();
+        const output = consoleLogSpy.mock.calls.map((c) => c[0]).join('\n');
+        expect(output).toContain('Reachability');
+        expect(output).toContain('fetch failed');
+        // Should exit 1 because reachability failed
+        expect(processExitSpy).toHaveBeenCalledWith(1);
+    });
+    it('reports missing config file when no profiles and no legacy .env', async () => {
+        mockProfiles = [];
+        mockLegacyEnvExists = false;
+        mockMcpCall.mockResolvedValueOnce({ ok: true });
+        const { runDoctor } = await import('./doctor.js');
+        await runDoctor();
+        const output = consoleLogSpy.mock.calls.map((c) => c[0]).join('\n');
+        expect(output).toContain('No profiles');
+        expect(output).toContain('no legacy config');
+        // Should exit 1 because config file check failed
+        expect(processExitSpy).toHaveBeenCalledWith(1);
+    });
+    it('passes config check when profiles exist (even without legacy .env)', async () => {
+        mockProfiles = ['default', 'staging'];
+        mockLegacyEnvExists = false;
+        mockMcpCall.mockResolvedValueOnce({ ok: true });
+        const { runDoctor } = await import('./doctor.js');
+        await runDoctor();
+        const output = consoleLogSpy.mock.calls.map((c) => c[0]).join('\n');
+        expect(output).toContain('Config file');
+        expect(output).toContain(mockProfilesDir);
+        expect(output).toContain('2 profiles');
+        expect(processExitSpy).not.toHaveBeenCalled();
+    });
+    it('passes config check with single profile', async () => {
+        mockProfiles = ['default'];
+        mockLegacyEnvExists = false;
+        mockMcpCall.mockResolvedValueOnce({ ok: true });
+        const { runDoctor } = await import('./doctor.js');
+        await runDoctor();
+        const output = consoleLogSpy.mock.calls.map((c) => c[0]).join('\n');
+        expect(output).toContain('1 profile)');
+        expect(processExitSpy).not.toHaveBeenCalled();
+    });
+    it('suggests --fix when fixable issues exist', async () => {
+        delete process.env.PRODUCTBRAIN_API_KEY;
+        mockMcpCall.mockRejectedValueOnce(new Error('No API key'));
+        const { runDoctor } = await import('./doctor.js');
+        await runDoctor();
+        const output = consoleLogSpy.mock.calls.map((c) => c[0]).join('\n');
+        expect(output).toContain('pb doctor --fix');
+        expect(output).toContain('pb doctor --dry-run');
+    });
+    it('accepts empty options (backwards compatible with WP-301)', async () => {
+        mockMcpCall.mockResolvedValueOnce({ ok: true });
+        const { runDoctor } = await import('./doctor.js');
+        // Both should work without error
+        await runDoctor();
+        mockMcpCall.mockResolvedValueOnce({ ok: true });
+        await runDoctor({});
+        expect(consoleLogSpy).toHaveBeenCalled();
+    });
+    it('does not mount the stale CLI upgrade hotkey prompt in CI', async () => {
+        Object.defineProperty(process.stdin, 'isTTY', { value: true, configurable: true });
+        process.env.CI = 'true';
+        upgradeHotkeyMocks.cachedLatestVersion = '0.1.0-beta.999';
+        mockMcpCall.mockResolvedValueOnce({ ok: true });
+        const { runDoctor } = await import('./doctor.js');
+        await runDoctor();
+        const output = consoleLogSpy.mock.calls.map((c) => c[0]).join('\n');
+        expect(output).toContain('CLI freshness');
+        expect(output).toContain('[u] upgrade');
+        expect(upgradeHotkeyMocks.render).not.toHaveBeenCalled();
+        expect(upgradeHotkeyMocks.runUpgrade).not.toHaveBeenCalled();
+    });
+    it('does not mount the stale CLI upgrade hotkey prompt when PB_NO_INTERACTIVE is set', async () => {
+        Object.defineProperty(process.stdin, 'isTTY', { value: true, configurable: true });
+        process.env.PB_NO_INTERACTIVE = '1';
+        upgradeHotkeyMocks.cachedLatestVersion = '0.1.0-beta.999';
+        mockMcpCall.mockResolvedValueOnce({ ok: true });
+        const { runDoctor } = await import('./doctor.js');
+        await runDoctor();
+        const output = consoleLogSpy.mock.calls.map((c) => c[0]).join('\n');
+        expect(output).toContain('CLI freshness');
+        expect(output).toContain('[u] upgrade');
+        expect(upgradeHotkeyMocks.render).not.toHaveBeenCalled();
+        expect(upgradeHotkeyMocks.runUpgrade).not.toHaveBeenCalled();
+    });
+    it('also treats PB_NO_INTERACTIVE=true (truthy non-1) as suppression', async () => {
+        Object.defineProperty(process.stdin, 'isTTY', { value: true, configurable: true });
+        process.env.PB_NO_INTERACTIVE = 'true';
+        upgradeHotkeyMocks.cachedLatestVersion = '0.1.0-beta.999';
+        mockMcpCall.mockResolvedValueOnce({ ok: true });
+        const { runDoctor } = await import('./doctor.js');
+        await runDoctor();
+        expect(upgradeHotkeyMocks.render).not.toHaveBeenCalled();
+        expect(upgradeHotkeyMocks.runUpgrade).not.toHaveBeenCalled();
+    });
+    it('[u] hotkey triggers runUpgrade and skips exit(1) on freshness fail', async () => {
+        Object.defineProperty(process.stdin, 'isTTY', { value: true, configurable: true });
+        Object.defineProperty(process.stdout, 'isTTY', { value: true, configurable: true });
+        upgradeHotkeyMocks.cachedLatestVersion = '0.1.0-beta.999';
+        upgradeHotkeyMocks.simulateInput = 'u';
+        upgradeHotkeyMocks.runUpgrade.mockResolvedValueOnce(undefined);
+        mockMcpCall.mockResolvedValueOnce({ ok: true });
+        const { runDoctor } = await import('./doctor.js');
+        await runDoctor();
+        expect(upgradeHotkeyMocks.render).toHaveBeenCalledTimes(1);
+        expect(upgradeHotkeyMocks.runUpgrade).toHaveBeenCalledTimes(1);
+        const call = upgradeHotkeyMocks.runUpgrade.mock.calls[0]?.[0];
+        expect(call).toBeDefined();
+        expect(typeof call.currentVersion).toBe('string');
+        // After a successful in-doctor upgrade, freshness fail must not bubble up as exit(1).
+        expect(processExitSpy).not.toHaveBeenCalledWith(1);
+    });
+    it('[q] dismissal does not call runUpgrade', async () => {
+        Object.defineProperty(process.stdin, 'isTTY', { value: true, configurable: true });
+        Object.defineProperty(process.stdout, 'isTTY', { value: true, configurable: true });
+        upgradeHotkeyMocks.cachedLatestVersion = '0.1.0-beta.999';
+        upgradeHotkeyMocks.simulateInput = 'q';
+        mockMcpCall.mockResolvedValueOnce({ ok: true });
+        const { runDoctor } = await import('./doctor.js');
+        await runDoctor();
+        expect(upgradeHotkeyMocks.render).toHaveBeenCalledTimes(1);
+        expect(upgradeHotkeyMocks.runUpgrade).not.toHaveBeenCalled();
+        // Freshness failure remains, so exit(1) IS expected here.
+        expect(processExitSpy).toHaveBeenCalledWith(1);
+    });
+    // ── CLI freshness — live-resolve backstop ──────────────────────────
+    it('freshness check live-resolves and reports newer version even when cache was empty', async () => {
+        // Simulate an offline session: cache is empty (cachedLatestVersion = undefined)
+        // but resolveLatestVersion discovers 0.1.0-beta.140 (e.g. via npm fetch)
+        upgradeHotkeyMocks.cachedLatestVersion = undefined;
+        // Override the mock for this test to return a specific newer version
+        const updateCheck = await import('../lib/update-check.js');
+        vi.mocked(updateCheck.resolveLatestVersion).mockResolvedValueOnce('0.1.0-beta.140');
+        mockMcpCall.mockResolvedValueOnce({ ok: true });
+        const { runDoctor } = await import('./doctor.js');
+        await runDoctor();
+        const output = consoleLogSpy.mock.calls.map((c) => c[0]).join('\n');
+        // Should contain the live-resolved version, NOT "No newer version detected"
+        expect(output).toContain('0.1.0-beta.140');
+        expect(output).not.toContain('No newer version detected');
+    });
+    // ── --dry-run ───────────────────────────────────────────────────────
+    describe('--dry-run', () => {
+        it('shows planned fixes without modifying filesystem', async () => {
+            mockProfiles = [];
+            mockLegacyEnvExists = false;
+            delete process.env.PRODUCTBRAIN_API_KEY;
+            mockMcpCall.mockRejectedValueOnce(new Error('No key'));
+            const { runDoctor } = await import('./doctor.js');
+            await runDoctor({ dryRun: true });
+            const output = consoleLogSpy.mock.calls.map((c) => c[0]).join('\n');
+            // Should mention dry run
+            expect(output).toContain('Dry run');
+            // Should describe the config file fix (TASK-562: connect, never pb login)
+            expect(output).toContain('pb connect <token>');
+            expect(output).not.toContain('pb login');
+            // Should NOT have called fs write functions
+            expect(mockMkdirSync).not.toHaveBeenCalled();
+            expect(mockWriteFileSync).not.toHaveBeenCalled();
+            // Should exit 1 (issues still present)
+            expect(processExitSpy).toHaveBeenCalledWith(1);
+        });
+        it('does nothing when all checks pass', async () => {
+            mockMcpCall.mockResolvedValueOnce({ ok: true });
+            const { runDoctor } = await import('./doctor.js');
+            await runDoctor({ dryRun: true });
+            // No fixes to show, no exit(1)
+            const output = consoleLogSpy.mock.calls.map((c) => c[0]).join('\n');
+            expect(output).not.toContain('Dry run');
+            expect(processExitSpy).not.toHaveBeenCalled();
+        });
+    });
+    // ── --fix ───────────────────────────────────────────────────────────
+    describe('--fix', () => {
+        it('guides to pb connect when no config exists (no longer creates legacy .env)', async () => {
+            mockProfiles = [];
+            mockLegacyEnvExists = false;
+            mockMcpCall.mockResolvedValueOnce({ ok: true }); // first run
+            mockMcpCall.mockResolvedValueOnce({ ok: true }); // re-check
+            const { runDoctor } = await import('./doctor.js');
+            await runDoctor({ fix: true });
+            const output = consoleLogSpy.mock.calls.map((c) => c[0]).join('\n');
+            // Should mention applying fixes
+            expect(output).toContain('Applying fixes');
+            // TASK-562: the fix names the app page that hands out a connect command, never pb login
+            expect(output).toContain('Get your connect command at ');
+            expect(output).toContain('/settings/api-keys.');
+            // Should NOT create legacy .env (profile system is the way forward)
+            expect(mockMkdirSync).not.toHaveBeenCalled();
+            expect(mockWriteFileSync).not.toHaveBeenCalled();
+        });
+        it('prints guidance for API key fix (cannot auto-fix)', async () => {
+            delete process.env.PRODUCTBRAIN_API_KEY;
+            mockMcpCall.mockRejectedValueOnce(new Error('No key')); // first run
+            mockMcpCall.mockRejectedValueOnce(new Error('No key')); // re-check
+            const { runDoctor } = await import('./doctor.js');
+            await runDoctor({ fix: true });
+            const output = consoleLogSpy.mock.calls.map((c) => c[0]).join('\n');
+            // Should mention applying fixes
+            expect(output).toContain('Applying fixes');
+            // Fix action for API key prints the connect command (TASK-562)
+            expect(output).toContain('Run: pb connect <token>');
+        });
+        it('does nothing when all checks pass', async () => {
+            mockMcpCall.mockResolvedValueOnce({ ok: true });
+            const { runDoctor } = await import('./doctor.js');
+            await runDoctor({ fix: true });
+            const output = consoleLogSpy.mock.calls.map((c) => c[0]).join('\n');
+            // Should not attempt fixes
+            expect(output).not.toContain('Applying fixes');
+            expect(mockMkdirSync).not.toHaveBeenCalled();
+            expect(mockWriteFileSync).not.toHaveBeenCalled();
+        });
+        it('is idempotent — running twice with valid config does not break anything', async () => {
+            mockMcpCall.mockResolvedValue({ ok: true });
+            const { runDoctor } = await import('./doctor.js');
+            await runDoctor({ fix: true });
+            await runDoctor({ fix: true });
+            // No failures
+            const exitCalls = processExitSpy.mock.calls.filter((c) => c[0] === 1);
+            expect(exitCalls.length).toBe(0);
+        });
+    });
+    // ── Individual check fix contracts ──────────────────────────────────
+    describe('check fix contracts', () => {
+        it('config file check has a fix when missing (guides to pb connect, TASK-562)', async () => {
+            mockProfiles = [];
+            mockLegacyEnvExists = false;
+            mockMcpCall.mockResolvedValueOnce({ ok: true });
+            const { runDoctor } = await import('./doctor.js');
+            await runDoctor({ dryRun: true });
+            const output = consoleLogSpy.mock.calls.map((c) => c[0]).join('\n');
+            expect(output).toContain('Config file');
+            expect(output).toContain('Run pb connect <token> in your project folder');
+        });
+        it('TASK-562: the API key line is the connect guidance alone, two sentences, never joined to the reason (RULE-662)', async () => {
+            delete process.env.PRODUCTBRAIN_API_KEY;
+            mockMcpCall.mockRejectedValueOnce(new Error('No key'));
+            const { runDoctor } = await import('./doctor.js');
+            await runDoctor({ dryRun: true });
+            const output = consoleLogSpy.mock.calls.map((c) => c[0]).join('\n');
+            const keyLine = output.split('\n').find((l) => l.includes('API key') && l.includes('pb connect'));
+            expect(keyLine).toContain('Run pb connect <token> in your project folder. Get your connect command at');
+            expect(keyLine).not.toContain('No API key configured.');
+            expect(output).not.toContain('pb login');
+        });
+        it('invalid API key format has a fix — and for an exported key it is not pb login', async () => {
+            process.env.PRODUCTBRAIN_API_KEY = 'bad_format_key';
+            mockMcpCall.mockRejectedValueOnce(new Error('Invalid key'));
+            const { runDoctor } = await import('./doctor.js');
+            await runDoctor({ dryRun: true });
+            const output = consoleLogSpy.mock.calls.map((c) => c[0]).join('\n');
+            expect(output).toContain('Invalid API key format');
+            // `pb login` writes where the exported key outranks it, so the repair names the env var.
+            expect(output).toContain('Unset PRODUCTBRAIN_API_KEY');
+        });
+        it('Node version check is info-only (no fix)', async () => {
+            mockMcpCall.mockResolvedValueOnce({ ok: true });
+            const { runDoctor } = await import('./doctor.js');
+            await runDoctor();
+            const output = consoleLogSpy.mock.calls.map((c) => c[0]).join('\n');
+            expect(output).toContain('Node');
+            expect(output).toContain(process.version);
+        });
+        it('CLI version check is info-only (no fix)', async () => {
+            mockMcpCall.mockResolvedValueOnce({ ok: true });
+            const { runDoctor } = await import('./doctor.js');
+            await runDoctor();
+            const output = consoleLogSpy.mock.calls.map((c) => c[0]).join('\n');
+            expect(output).toContain('CLI');
+        });
+        it('reachability check is info-only (no fix)', async () => {
+            mockMcpCall.mockRejectedValueOnce(new Error('timeout'));
+            const { runDoctor } = await import('./doctor.js');
+            await runDoctor({ dryRun: true });
+            const output = consoleLogSpy.mock.calls.map((c) => c[0]).join('\n');
+            // Reachability failure should appear but NOT as a fixable item
+            expect(output).toContain('Reachability');
+            expect(output).toContain('timeout');
+        });
+    });
+});
+//# sourceMappingURL=doctor.test.js.map