@boyingliu01/xp-gate 0.8.12 → 0.8.14

package/bin/xp-gate.js

@@ -11,6 +11,7 @@ const { handleBaseline } = require('../lib/baseline.js');
 const { check } = require('../lib/check.js');
 const { principles } = require('../lib/principles.js');
 const { arch } = require('../lib/arch.js');
+const { upgrade } = require('../lib/upgrade.js');
 
 function handleUIReview() {
   const { execSync } = require('child_process');
@@ -115,6 +116,11 @@ const COMMANDS = {
     description: 'Run architecture validation (Gate 6 standalone, uses architecture.yaml)',
     run: subargs => arch(subargs).then(code => process.exit(code)),
     usage: 'xp-gate arch [--config <path>]'
+  },
+  'upgrade': {
+    description: 'Check for xp-gate updates (--preview for JSON, --apply to upgrade)',
+    run: subargs => upgrade(subargs).then(code => process.exit(code)),
+    usage: 'xp-gate upgrade [--preview] [--apply]'
   }
 };
 

package/lib/__tests__/check-version.test.js

@@ -0,0 +1,307 @@
+/**
+ * @test REQ-001-01 check-version.js
+ * @intent 验证版本检查模块所有 7 个导出函数和 8 个 AC 的行为
+ * @covers AC-001-01, AC-001-02, AC-001-03, AC-001-04, AC-001-05, AC-001-06, AC-001-07, AC-001-08
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+function fakeHome() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ckv-'));
+  process.env.HOME = dir;
+  return dir;
+}
+
+function cleanupDir(dir) {
+  if (dir && fs.existsSync(dir)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+// ── suite ──
+
+describe('check-version.js — REQ-001-01', () => {
+  let mod;
+  let origHome;
+  let tmpHome;
+  let origReadFileSync;
+
+  beforeEach(() => {
+    vi.resetModules();
+    origHome = process.env.HOME;
+    tmpHome = fakeHome();
+    origReadFileSync = fs.readFileSync;
+  });
+
+  afterEach(() => {
+    process.env.HOME = origHome;
+    cleanupDir(tmpHome);
+    fs.readFileSync = origReadFileSync;
+  });
+
+  // ──────────────────────────────────────────
+  // AC-001-06: getPackageName()
+  // ──────────────────────────────────────────
+  describe('getPackageName() — AC-001-06', () => {
+    it('reads package name from package.json when available', () => {
+      mod = require('../check-version');
+      expect(mod.getPackageName()).toBe('@boyingliu01/xp-gate');
+    });
+
+    it('falls back to DEFAULT on parse failure', () => {
+      fs.readFileSync = vi.fn().mockImplementation((fp) => {
+        if (fp.endsWith('package.json')) throw new Error('ENOENT');
+        return origReadFileSync(fp);
+      });
+      mod = require('../check-version');
+      expect(mod.getPackageName()).toBe('@boyingliu01/xp-gate');
+    });
+
+    it('falls back to DEFAULT for unscoped names', () => {
+      fs.readFileSync = vi.fn().mockImplementation((fp) => {
+        if (fp.endsWith('package.json')) return JSON.stringify({ name: 'just-xp-gate' });
+        return origReadFileSync(fp);
+      });
+      mod = require('../check-version');
+      expect(mod.getPackageName()).toBe('@boyingliu01/xp-gate');
+    });
+  });
+
+  // ──────────────────────────────────────────
+  // AC-001-01: getLocalVersion()
+  // ──────────────────────────────────────────
+  describe('getLocalVersion() — AC-001-01', () => {
+    it('returns version from package.json', () => {
+      mod = require('../check-version');
+      expect(mod.getLocalVersion()).toBe('0.8.12');
+    });
+
+    it('returns null when read fails', () => {
+      fs.readFileSync = vi.fn().mockImplementation((fp) => {
+        if (fp.endsWith('package.json')) throw new Error('ENOENT');
+        return origReadFileSync(fp);
+      });
+      mod = require('../check-version');
+      expect(mod.getLocalVersion()).toBeNull();
+    });
+
+    it('returns null when version field missing', () => {
+      fs.readFileSync = vi.fn().mockImplementation((fp) => {
+        if (fp.endsWith('package.json')) return JSON.stringify({ name: 'test' });
+        return origReadFileSync(fp);
+      });
+      mod = require('../check-version');
+      expect(mod.getLocalVersion()).toBeNull();
+    });
+  });
+
+  // ──────────────────────────────────────────
+  // compareVersions()
+  // ──────────────────────────────────────────
+  describe('compareVersions()', () => {
+    beforeEach(() => { mod = require('../check-version'); });
+
+    it('a < b → negative', () => {
+      expect(mod.compareVersions('0.8.12', '0.8.13')).toBeLessThan(0);
+    });
+    it('a > b → positive', () => {
+      expect(mod.compareVersions('0.8.13', '0.8.12')).toBeGreaterThan(0);
+    });
+    it('equal → 0', () => {
+      expect(mod.compareVersions('0.8.12', '0.8.12')).toBe(0);
+    });
+    it('handles different segment counts', () => {
+      expect(mod.compareVersions('1.0', '1.0.1')).toBeLessThan(0);
+    });
+    it('handles major version diffs', () => {
+      expect(mod.compareVersions('1.0.0', '2.0.0')).toBeLessThan(0);
+    });
+  });
+
+  // ──────────────────────────────────────────
+  // AC-001-08: calcLagDays() (internal — tested via checkUpgrade)
+  // ──────────────────────────────────────────
+  describe('calcLagDays() behavior via checkUpgrade — AC-001-08', () => {
+    it('checkUpgrade returns lagDays=0 when no remote version', async () => {
+      mod = require('../check-version');
+      const r = await mod.checkUpgrade('@nonexistent/pkg-test-only');
+      expect(r.lagDays).toBe(0);
+    });
+
+    it('checkUpgrade uses calcLagDays with publishedAt when available', async () => {
+      const https = require('https');
+      const origGet = https.get;
+      const body = JSON.stringify({ latest: '99.99.99' });
+      https.get = (_url, _opts, cb) => {
+        const callback = typeof _opts === 'function' ? _opts : cb;
+        if (!callback) return { on: () => this, destroy: () => {} };
+        const mockRes = {
+          statusCode: 200,
+          on: (evt, handler) => { if (evt === 'end') handler(); return mockRes; },
+        };
+        callback(mockRes);
+        return { on: () => this, destroy: () => {} };
+      };
+      vi.resetModules();
+      mod = require('../check-version');
+      const r = await mod.checkUpgrade('@nonexistent/pkg-test-only');
+      expect(r.lagDays).toBe(0);
+      https.get = origGet;
+    });
+  });
+
+  // ──────────────────────────────────────────
+  // AC-001-05: cache operations
+  // ──────────────────────────────────────────
+  describe('cache operations — AC-001-05', () => {
+    beforeEach(() => { mod = require('../check-version'); });
+
+    it('clearCache does not throw when no cache file', () => {
+      expect(() => mod.clearCache()).not.toThrow();
+    });
+
+    it('clearCache does not throw after normal module load', () => {
+      // Verify the function is exported and callable without error
+      expect(() => mod.clearCache()).not.toThrow();
+    });
+
+    it('cachePath returns null when XP_GATE_DIR is inaccessible', () => {
+      // Verify clearCache handles null cachePath gracefully
+      expect(() => mod.clearCache()).not.toThrow();
+    });
+  });
+
+  // ──────────────────────────────────────────
+  // AC-001-04: checkUpgrade() — safe defaults
+  // Uses isolated https mock to avoid real network dependency.
+  // ──────────────────────────────────────────
+  describe('checkUpgrade() — AC-001-04', () => {
+    function evictCache() {
+      const resolved = require.resolve('../check-version');
+      const libPrefix = resolved.replace(/check-version\.js$/, '');
+      Object.keys(require.cache).forEach(key => {
+        if (key.startsWith(libPrefix)) delete require.cache[key];
+      });
+      delete require.cache[resolved];
+    }
+
+    function withMockedHttps(latestVersion, fn) {
+      const fs = require('fs');
+      const os = require('os');
+      const cpPath = require('path').join(os.homedir(), '.xp-gate', 'version-cache.json');
+      if (fs.existsSync(cpPath)) {
+        try { fs.unlinkSync(cpPath); } catch { }
+      }
+      evictCache();
+      const https = require('https');
+      const saved = https.get;
+      const body = JSON.stringify({ latest: latestVersion });
+      https.get = (_url, _opts, cb) => {
+        const callback = typeof _opts === 'function' ? _opts : cb;
+        if (!callback) return { on: () => undefined, destroy: () => undefined };
+        const mockRes = {
+          statusCode: 200,
+          on: (evt, handler) => {
+            if (evt === 'data') handler(body);
+            if (evt === 'end') handler();
+            return mockRes;
+          },
+        };
+        callback(mockRes);
+        return { on: () => undefined, destroy: () => undefined };
+      };
+      try {
+        const m = require('../check-version');
+        return fn(m);
+      } finally {
+        https.get = saved;
+      }
+    }
+
+    it('returns safe defaults (outdated:false) without network', async () => {
+      // Mock https to return the SAME version as local → outdated=false, no network dependency
+      const result = await withMockedHttps('0.8.12', async (m) => m.checkUpgrade('@nonexistent/pkg-test-only'));
+      expect(result.outdated).toBe(false);
+      expect(result.local).toBe('0.8.12');
+      expect(result.remote).toBe('0.8.12');
+      expect(result.lagDays).toBe(0);
+    });
+
+    it('returns outdated=true when remote > local', async () => {
+      const result = await withMockedHttps('99.99.99', async (m) => m.checkUpgrade('@nonexistent/pkg-test-only'));
+      expect(result.outdated).toBe(true);
+      expect(result.local).toBe('0.8.12');
+      expect(result.remote).toBe('99.99.99');
+    });
+  });
+
+  // ──────────────────────────────────────────
+  // AC-001-02 + AC-001-03 + AC-001-07: getRemoteVersion()
+  // ──────────────────────────────────────────
+  describe('getRemoteVersion() — AC-001-02, AC-001-03, AC-001-07', () => {
+    it('gracefully handles network failure', async () => {
+      mod = require('../check-version');
+      const r = await mod.getRemoteVersion('@nonexistent/pkg-test-only');
+      // Without network: null. With network (npm registry proxy): object.
+      expect(r === null || (typeof r.latest === 'string')).toBe(true);
+    });
+  });
+
+  // ──────────────────────────────────────────
+  // formatUpgradeMsg() — not outdated
+  // ──────────────────────────────────────────
+  describe('formatUpgradeMsg() — up to date', () => {
+    beforeEach(() => { mod = require('../check-version'); });
+    const r = { outdated: false, local: '0.8.12', remote: '0.8.12', lagDays: 0 };
+
+    it('cli shows checkmark', () => {
+      expect(mod.formatUpgradeMsg(r, 'cli')).toContain('up to date');
+    });
+    it('doctor returns empty', () => {
+      expect(mod.formatUpgradeMsg(r, 'doctor')).toBe('');
+    });
+    it('plugin returns empty', () => {
+      expect(mod.formatUpgradeMsg(r, 'plugin')).toBe('');
+    });
+  });
+
+  // ──────────────────────────────────────────
+  // formatUpgradeMsg() — outdated (AC-003-01, AC-003-02, AC-003-03)
+  // ──────────────────────────────────────────
+  describe('formatUpgradeMsg() — outdated (AC-003-01/02/03)', () => {
+    beforeEach(() => { mod = require('../check-version'); });
+    const r = { outdated: true, local: '0.8.12', remote: '0.8.13', lagDays: 10 };
+
+    it('cli: full release link + upgrade cmd (AC-003-01)', () => {
+      const msg = mod.formatUpgradeMsg(r, 'cli');
+      expect(msg).toContain('v0.8.13');
+      expect(msg).toContain('github.com');
+      expect(msg).toContain('upgrade --apply');
+    });
+
+    it('doctor: remote version + github + retry (AC-003-02)', () => {
+      const msg = mod.formatUpgradeMsg(r, 'doctor');
+      expect(msg).toContain('v0.8.13');
+      expect(msg).toContain('github.com');
+      expect(msg).toContain('upgrade --apply');
+    });
+
+    it('plugin lagDays >7: strong (AC-003-03)', () => {
+      const msg = mod.formatUpgradeMsg(r, 'plugin');
+      expect(msg).toContain('v0.8.13');
+      expect(msg).toContain('upgrade recommended');
+    });
+
+    it('plugin lagDays 1-7: soft (AC-003-03)', () => {
+      const msg = mod.formatUpgradeMsg({ ...r, lagDays: 3 }, 'plugin');
+      expect(msg).toContain('v0.8.13');
+      expect(msg).not.toContain('upgrade recommended');
+    });
+
+    it('plugin lagDays <1: silent (AC-003-03)', () => {
+      expect(mod.formatUpgradeMsg({ ...r, lagDays: 0 }, 'plugin')).toBe('');
+    });
+  });
+});

package/lib/__tests__/doctor.test.js

@@ -13,8 +13,6 @@ describe('doctor', () => {
   let tmpProject;
   let originalHome;
   let logSpy;
-  let warnSpy;
-  let errorSpy;
   let execSpy;
 
   beforeEach(() => {
@@ -29,8 +27,8 @@ describe('doctor', () => {
     delete require.cache[require.resolve('../detect-deps.js')];
     delete require.cache[require.resolve('../shared-paths')];
     logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
-    warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
-    errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+    vi.spyOn(console, 'error').mockImplementation(() => {});
   });
 
   afterEach(() => {
@@ -56,10 +54,6 @@ describe('doctor', () => {
     return path.join(tmpHome, '.config', 'xp-gate', 'adapters');
   }
 
-  function projectGitDir() {
-    return path.join(tmpProject, '.git');
-  }
-
   function projectHooksDir() {
     return path.join(tmpProject, '.git', 'hooks');
   }
@@ -168,6 +162,17 @@ describe('doctor', () => {
     });
   }
 
+  // doctor() calls checkUpgrade() which hits npm registry; seed cache to skip.
+  // check-version.js uses os.homedir() (not process.env.HOME) for XP_GATE_DIR.
+  function seedVersionCache() {
+    const cacheDir = path.join(os.homedir(), '.xp-gate');
+    fs.mkdirSync(cacheDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(cacheDir, 'version-cache.json'),
+      JSON.stringify({ ts: Date.now(), version: '0.8.12', publishedAt: '' })
+    );
+  }
+
   function mockExecFail() {
     execSpy = vi.spyOn(childProcess, 'execSync').mockImplementation(() => {
       throw new Error('Command failed');
@@ -178,36 +183,22 @@ describe('doctor', () => {
 
   it('AC-05: doctor reports all checks passed for healthy local install', async () => {
     setupLocalInstall();
+    seedVersionCache();
     mockExecSuccess();
     const { doctor } = require('../doctor');
 
     const result = await doctor([]);
 
     expect(result).toBe(0);
-
-    // Should report Config file check
-    expect(logSpy).toHaveBeenCalledWith(
-      expect.stringContaining('Config file')
-    );
-
-    // Should report hooks check
-    expect(logSpy).toHaveBeenCalledWith(
-      expect.stringContaining('Hooks')
-    );
-
-    // Should report Adapters directory check
-    expect(logSpy).toHaveBeenCalledWith(
-      expect.stringContaining('Adapters directory')
-    );
-
-    // Should report all checks passed
-    expect(logSpy).toHaveBeenCalledWith(
-      expect.stringContaining('All checks passed')
-    );
+    expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('Config file'));
+    expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('Hooks'));
+    expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('Adapters directory'));
+    expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('All checks passed'));
   });
 
   it('AC-05: doctor reports all checks passed for healthy global install', async () => {
     setupGlobalInstall();
+    seedVersionCache();
     mockExecSuccess();
     const { doctor } = require('../doctor');
 
@@ -223,6 +214,7 @@ describe('doctor', () => {
 
   it('AC-08: doctor detects missing hooks in partial install', async () => {
     setupLocalInstall();
+    seedVersionCache();
     // Remove hooks to simulate partial state
     fs.unlinkSync(path.join(projectHooksDir(), 'pre-commit'));
     fs.unlinkSync(path.join(projectHooksDir(), 'pre-push'));
@@ -268,6 +260,7 @@ describe('doctor', () => {
 
   it('AC-08: doctor detects missing adapters', async () => {
     setupLocalInstall();
+    seedVersionCache();
     // Remove adapters dir
     fs.rmSync(projectAdaptersDir(), { recursive: true, force: true });
     mockExecSuccess();
@@ -286,6 +279,7 @@ describe('doctor', () => {
 
   it('AC-08: doctor detects wrong core.hooksPath in global mode', async () => {
     setupGlobalInstall();
+    seedVersionCache();
     // Mock hooksPath pointing somewhere else
     execSpy = vi.spyOn(childProcess, 'execSync').mockImplementation((cmd) => {
       if (cmd.includes('git config --global core.hooksPath')) {
@@ -309,13 +303,9 @@ describe('doctor', () => {
       return '';
     });
     const { doctor } = require('../doctor');
-
     const result = await doctor([]);
-
     expect(result).toBe(1);
-    expect(logSpy).toHaveBeenCalledWith(
-      expect.stringContaining('Expected ')
-    );
+    expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('Expected '));
   });
 
   // === AC-10: --fix only when mode === "active" ===
@@ -328,49 +318,41 @@ describe('doctor', () => {
     );
 
     const { doctor } = require('../doctor');
-
     const result = await doctor(['--fix']);
-
     expect(result).toBe(0);
-    // Should NOT attempt fix operations
-    expect(logSpy).toHaveBeenCalledWith(
-      expect.stringContaining('xp-gate is not installed')
-    );
+    expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('xp-gate is not installed'));
   });
 
   it('AC-10: doctor --fix reinstall hooks when mode is active and hooks missing', async () => {
     setupLocalInstall();
+    seedVersionCache();
     // Remove hooks to create a fixable issue
     fs.unlinkSync(path.join(projectHooksDir(), 'pre-commit'));
     fs.unlinkSync(path.join(projectHooksDir(), 'pre-push'));
     mockExecSuccess();
     const { doctor } = require('../doctor');
-
     const result = await doctor(['--fix']);
-
     expect(result).toBe(0);
-    // Should have reinstalled hooks
     expect(fs.existsSync(path.join(projectHooksDir(), 'pre-commit'))).toBe(true);
     expect(fs.existsSync(path.join(projectHooksDir(), 'pre-push'))).toBe(true);
   });
 
   it('AC-10: doctor --fix reinstall adapters when mode is active and adapters missing', async () => {
     setupLocalInstall();
+    seedVersionCache();
     // Remove adapters
     fs.rmSync(projectAdaptersDir(), { recursive: true, force: true });
     mockExecSuccess();
     const { doctor } = require('../doctor');
-
     const result = await doctor(['--fix']);
-
     expect(result).toBe(0);
-    // Should have reinstalled adapters
     expect(fs.existsSync(projectAdaptersDir())).toBe(true);
     expect(fs.existsSync(path.join(projectAdaptersDir(), 'typescript.sh'))).toBe(true);
   });
 
   it('AC-10: doctor --fix corrects core.hooksPath in global mode', async () => {
     setupGlobalInstall();
+    seedVersionCache();
     // Mock hooksPath pointing somewhere else
     execSpy = vi.spyOn(childProcess, 'execSync').mockImplementation((cmd) => {
       if (cmd.includes('git config --global core.hooksPath')) {
@@ -436,6 +418,7 @@ describe('doctor', () => {
 
   it('detects missing environment dependencies', async () => {
     setupLocalInstall();
+    seedVersionCache();
     mockExecFail();
     const { doctor } = require('../doctor');
 
@@ -451,6 +434,7 @@ describe('doctor', () => {
 
   it('detects version mismatch when config version differs from package version', async () => {
     setupLocalInstall();
+    seedVersionCache();
     // Write config with old version
     const cfg = JSON.parse(fs.readFileSync(configFile(), 'utf8'));
     cfg.version = '0.3.1.1';
@@ -471,6 +455,7 @@ describe('doctor', () => {
 
   it('passes version check when config version matches package version', async () => {
     setupLocalInstall();
+    seedVersionCache();
     // Write config with matching version
     const pkg = JSON.parse(fs.readFileSync(
       path.join(path.dirname(path.dirname(require.resolve('../doctor'))), 'package.json'), 'utf8'
@@ -491,6 +476,7 @@ describe('doctor', () => {
 
   it('passes version check when config has no version field (legacy)', async () => {
     setupLocalInstall();
+    seedVersionCache();
     // Config without version field — legacy install, should not fail
     mockExecSuccess();
     const { doctor } = require('../doctor');
@@ -507,6 +493,7 @@ describe('doctor', () => {
 
   it('detects templateDir pointing to wrong platform directory', async () => {
     setupLocalInstall();
+    seedVersionCache();
     // Write config with stale opencode templateDir when qoder is active
     const cfg = JSON.parse(fs.readFileSync(configFile(), 'utf8'));
     cfg.templateDir = path.join(tmpHome, '.config', 'opencode', 'git-hooks-template');
@@ -534,18 +521,20 @@ describe('doctor', () => {
 
   it('passes templateDir check when templateDir matches current platform', async () => {
     setupLocalInstall();
+    seedVersionCache();
     // Write config with correct qoder templateDir
     const cfg = JSON.parse(fs.readFileSync(configFile(), 'utf8'));
     cfg.templateDir = path.join(tmpHome, '.qoder', 'git-hooks-template');
     fs.writeFileSync(configFile(), JSON.stringify(cfg, null, 2));
 
-    // Create qoder marker
+    // Create qoder marker — must exist BEFORE loading shared-paths
     fs.mkdirSync(path.join(tmpHome, '.qoder', 'skills'), { recursive: true });
 
+    // Fresh require so shared-paths detectPlatform() sees .qoder/skills
     delete require.cache[require.resolve('../shared-paths')];
     delete require.cache[require.resolve('../doctor')];
-    const { doctor: doc2 } = require('../doctor');
     mockExecSuccess();
+    const { doctor: doc2 } = require('../doctor');
 
     const result = await doc2([]);
 
@@ -557,6 +546,7 @@ describe('doctor', () => {
 
   it('passes templateDir check when config has no templateDir field (legacy)', async () => {
     setupLocalInstall();
+    seedVersionCache();
     // Config without templateDir — legacy install, should not fail
     mockExecSuccess();
     const { doctor } = require('../doctor');
@@ -569,10 +559,73 @@ describe('doctor', () => {
     );
   });
 
+  // === REQ-001-04: doctor 集成版本升级检查 (AC-004-01/02) ===
+
+  it('AC-004-01: doctor shows upgrade prompt at end when outdated', async () => {
+    setupLocalInstall();
+    mockExecSuccess();
+    // Remove version cache so checkUpgrade hits the real npm registry
+    const cachePath = path.join(tmpHome, '.xp-gate', 'version-cache.json');
+    if (fs.existsSync(cachePath)) fs.unlinkSync(cachePath);
+
+    delete require.cache[require.resolve('../doctor')];
+    delete require.cache[require.resolve('../check-version.js')];
+    const { doctor } = require('../doctor');
+
+    const result = await doctor([]);
+
+    expect(result).toBe(0);
+    // Doctor should output upgrade message when outdated
+    const output = logSpy.mock.calls.map(c => c[0] || '').join('\n');
+    expect(output).toMatch(/newer version|upgrade|v\d+\.\d+\.\d+/);
+  }, 30000);
+
+  it('AC-004-02: doctor does NOT show upgrade prompt when up to date', async () => {
+    setupLocalInstall();
+    mockExecSuccess();
+    // Write a cache with a future version so checkUpgrade says "not outdated"
+    const cachePath = path.join(tmpHome, '.xp-gate', 'version-cache.json');
+    fs.mkdirSync(path.dirname(cachePath), { recursive: true });
+    fs.writeFileSync(cachePath, JSON.stringify({
+      ts: Date.now(),
+      version: '999.999.999',
+      publishedAt: ''
+    }));
+
+    delete require.cache[require.resolve('../doctor')];
+    delete require.cache[require.resolve('../check-version.js')];
+    const { doctor } = require('../doctor');
+
+    const result = await doctor([]);
+
+    expect(result).toBe(0);
+    const output = logSpy.mock.calls.map(c => c[0] || '').join('\n');
+    // Should NOT contain upgrade-related messages
+    expect(output).not.toMatch(/newer version|upgrade/i);
+  });
+
+  it('AC-004-03: doctor does NOT fail when version check throws', async () => {
+    setupLocalInstall();
+    seedVersionCache();
+    mockExecSuccess();
+    // Write corrupt cache to trigger checkUpgrade error path
+    const cachePath = path.join(os.homedir(), '.xp-gate', 'version-cache.json');
+    fs.writeFileSync(cachePath, 'not json');
+
+    delete require.cache[require.resolve('../doctor')];
+    delete require.cache[require.resolve('../check-version.js')];
+    const { doctor } = require('../doctor');
+
+    // Doctor should NOT throw — version check is non-blocking
+    const result = await doctor([]);
+    expect(result).toBe(0);
+  });
+
   // === Issue #186: --fix syncs global hooks from package source ===
 
   it('--fix syncs global hooks when they are outdated', async () => {
     setupGlobalInstall();
+    seedVersionCache();
     // Write an outdated pre-commit hook (different content)
     const oldContent = '#!/bin/bash\n# OpenCode Quality Gates - Pre-Commit Hook - OLD VERSION\n';
     fs.writeFileSync(path.join(globalHooksDir(), 'pre-commit'), oldContent);