@codebakers/cli 3.0.1 → 3.2.0

package/dist/commands/doctor.js

@@ -118,13 +118,20 @@ function checkProject() {
         try {
             const files = (0, fs_1.readdirSync)(claudeDir).filter(f => f.endsWith('.md'));
             const moduleCount = files.length;
-            if (moduleCount >= 10) {
-                results.push({ ok: true, message: `${moduleCount} modules present` });
+            if (moduleCount >= 40) {
+                results.push({ ok: true, message: `${moduleCount} modules present (full set)` });
+            }
+            else if (moduleCount >= 10) {
+                results.push({
+                    ok: true,
+                    message: `${moduleCount} modules present (partial set)`,
+                    details: 'Run: codebakers upgrade to get all 47 modules'
+                });
             }
             else if (moduleCount > 0) {
                 results.push({
                     ok: false,
-                    message: `Only ${moduleCount} modules found (expected 10+)`,
+                    message: `Only ${moduleCount} modules found (expected 47)`,
                     details: 'Run: codebakers upgrade to get all modules'
                 });
             }

package/dist/commands/go.d.ts

@@ -1,4 +1,8 @@
+interface GoOptions {
+    verbose?: boolean;
+}
 /**
  * Zero-friction entry point - start using CodeBakers instantly
  */
-export declare function go(): Promise<void>;
+export declare function go(options?: GoOptions): Promise<void>;
+export {};

package/dist/commands/go.js

@@ -24,10 +24,18 @@ function prompt(question) {
         });
     });
 }
+function log(message, options) {
+    if (options?.verbose) {
+        console.log(chalk_1.default.gray(`  [verbose] ${message}`));
+    }
+}
 /**
  * Zero-friction entry point - start using CodeBakers instantly
  */
-async function go() {
+async function go(options = {}) {
+    log('Starting go command...', options);
+    log(`API URL: ${(0, config_js_1.getApiUrl)()}`, options);
+    log(`Working directory: ${process.cwd()}`, options);
     console.log(chalk_1.default.blue(`
   ╔═══════════════════════════════════════════════════════════╗
   ║                                                           ║
@@ -36,14 +44,17 @@ async function go() {
   ╚═══════════════════════════════════════════════════════════╝
   `));
     // Check if user already has an API key (paid user)
+    log('Checking for existing API key...', options);
     const apiKey = (0, config_js_1.getApiKey)();
     if (apiKey) {
+        log(`Found API key: ${apiKey.substring(0, 8)}...`, options);
         console.log(chalk_1.default.green('  ✓ You\'re already logged in with an API key!\n'));
         // Still install patterns if not already installed
-        await installPatternsWithApiKey(apiKey);
-        await configureMCP();
+        await installPatternsWithApiKey(apiKey, options);
+        await configureMCP(options);
         return;
     }
+    log('No API key found, checking trial state...', options);
     // Check existing trial
     const existingTrial = (0, config_js_1.getTrialState)();
     if (existingTrial && !(0, config_js_1.isTrialExpired)()) {
@@ -54,8 +65,8 @@ async function go() {
             console.log(chalk_1.default.cyan('    codebakers extend\n'));
         }
         // Install patterns if not already installed
-        await installPatterns(existingTrial.trialId);
-        await configureMCP();
+        await installPatterns(existingTrial.trialId, options);
+        await configureMCP(options);
         return;
     }
     // Check if trial expired
@@ -132,9 +143,9 @@ async function go() {
         spinner.succeed(`Trial started (${data.daysRemaining} days free)`);
         console.log('');
         // Install patterns (CLAUDE.md and .claude/)
-        await installPatterns(data.trialId);
+        await installPatterns(data.trialId, options);
         // Configure MCP
-        await configureMCP();
+        await configureMCP(options);
         // Show success message
         console.log(chalk_1.default.green(`
   ╔═══════════════════════════════════════════════════════════╗
@@ -164,7 +175,8 @@ async function go() {
         }
     }
 }
-async function configureMCP() {
+async function configureMCP(options = {}) {
+    log('Configuring MCP integration...', options);
     const spinner = (0, ora_1.default)('Configuring Claude Code integration...').start();
     const isWindows = process.platform === 'win32';
     const mcpCmd = isWindows
@@ -231,10 +243,12 @@ async function attemptAutoRestart() {
 /**
  * Install pattern files for API key users (paid users)
  */
-async function installPatternsWithApiKey(apiKey) {
+async function installPatternsWithApiKey(apiKey, options = {}) {
+    log('Installing patterns with API key...', options);
     const spinner = (0, ora_1.default)('Installing CodeBakers patterns...').start();
     const cwd = process.cwd();
     const apiUrl = (0, config_js_1.getApiUrl)();
+    log(`Fetching from: ${apiUrl}/api/content`, options);
     try {
         const response = await fetch(`${apiUrl}/api/content`, {
             method: 'GET',
@@ -243,13 +257,17 @@ async function installPatternsWithApiKey(apiKey) {
             },
         });
         if (!response.ok) {
+            log(`Response not OK: ${response.status} ${response.statusText}`, options);
             spinner.warn('Could not download patterns');
             return;
         }
+        log('Response OK, parsing JSON...', options);
         const content = await response.json();
-        await writePatternFiles(cwd, content, spinner);
+        log(`Received version: ${content.version}, modules: ${Object.keys(content.modules || {}).length}`, options);
+        await writePatternFiles(cwd, content, spinner, options);
     }
     catch (error) {
+        log(`Error: ${error instanceof Error ? error.message : String(error)}`, options);
         spinner.warn('Could not install patterns');
         console.log(chalk_1.default.gray('  Check your internet connection.\n'));
     }
@@ -257,12 +275,14 @@ async function installPatternsWithApiKey(apiKey) {
 /**
  * Install pattern files (CLAUDE.md and .claude/) for trial users
  */
-async function installPatterns(trialId) {
+async function installPatterns(trialId, options = {}) {
+    log(`Installing patterns with trial ID: ${trialId.substring(0, 8)}...`, options);
     const spinner = (0, ora_1.default)('Installing CodeBakers patterns...').start();
     const cwd = process.cwd();
     const apiUrl = (0, config_js_1.getApiUrl)();
     try {
         // Fetch patterns using trial ID
+        log(`Fetching from: ${apiUrl}/api/content`, options);
         const response = await fetch(`${apiUrl}/api/content`, {
             method: 'GET',
             headers: {
@@ -270,6 +290,7 @@ async function installPatterns(trialId) {
             },
         });
         if (!response.ok) {
+            log(`Primary endpoint failed: ${response.status}, trying trial endpoint...`, options);
             // Try without auth - some patterns may be available for trial
             const publicResponse = await fetch(`${apiUrl}/api/content/trial`, {
                 method: 'GET',
@@ -278,22 +299,27 @@ async function installPatterns(trialId) {
                 },
             });
             if (!publicResponse.ok) {
+                log(`Trial endpoint also failed: ${publicResponse.status}`, options);
                 spinner.warn('Could not download patterns (will use MCP tools)');
                 return;
             }
             const content = await publicResponse.json();
-            await writePatternFiles(cwd, content, spinner);
+            log(`Received version: ${content.version}, modules: ${Object.keys(content.modules || {}).length}`, options);
+            await writePatternFiles(cwd, content, spinner, options);
             return;
         }
         const content = await response.json();
-        await writePatternFiles(cwd, content, spinner);
+        log(`Received version: ${content.version}, modules: ${Object.keys(content.modules || {}).length}`, options);
+        await writePatternFiles(cwd, content, spinner, options);
     }
     catch (error) {
+        log(`Error: ${error instanceof Error ? error.message : String(error)}`, options);
         spinner.warn('Could not install patterns (will use MCP tools)');
         console.log(chalk_1.default.gray('  Patterns will be available via MCP tools.\n'));
     }
 }
-async function writePatternFiles(cwd, content, spinner) {
+async function writePatternFiles(cwd, content, spinner, options = {}) {
+    log(`Writing pattern files to ${cwd}...`, options);
     // Check if patterns already exist
     const claudeMdPath = (0, path_1.join)(cwd, 'CLAUDE.md');
     if ((0, fs_1.existsSync)(claudeMdPath)) {

package/dist/config.d.ts

@@ -43,6 +43,8 @@ interface ConfigSchema {
     serviceKeys: ServiceKeys;
     lastKeySync: string | null;
     trial: TrialState | null;
+    lastUpdateCheck: string | null;
+    latestKnownVersion: string | null;
 }
 export declare function getApiKey(): string | null;
 export declare function setApiKey(key: string): void;
@@ -105,4 +107,19 @@ export declare function hasValidAccess(): boolean;
  * Get authentication mode: 'apiKey', 'trial', or 'none'
  */
 export declare function getAuthMode(): 'apiKey' | 'trial' | 'none';
+/**
+ * Get cached update info if still valid (within 24 hours)
+ */
+export declare function getCachedUpdateInfo(): {
+    latestVersion: string;
+    checkedAt: string;
+} | null;
+/**
+ * Cache the latest version from npm registry
+ */
+export declare function setCachedUpdateInfo(latestVersion: string): void;
+/**
+ * Get the current CLI version from package.json
+ */
+export declare function getCliVersion(): string;
 export {};

package/dist/config.js

@@ -32,6 +32,9 @@ exports.isTrialExpired = isTrialExpired;
 exports.getTrialDaysRemaining = getTrialDaysRemaining;
 exports.hasValidAccess = hasValidAccess;
 exports.getAuthMode = getAuthMode;
+exports.getCachedUpdateInfo = getCachedUpdateInfo;
+exports.setCachedUpdateInfo = setCachedUpdateInfo;
+exports.getCliVersion = getCliVersion;
 const conf_1 = __importDefault(require("conf"));
 const fs_1 = require("fs");
 const path_1 = require("path");
@@ -126,6 +129,8 @@ const config = new conf_1.default({
         serviceKeys: defaultServiceKeys,
         lastKeySync: null,
         trial: null,
+        lastUpdateCheck: null,
+        latestKnownVersion: null,
     },
     // Migration to add new keys when upgrading from old version
     migrations: {
@@ -411,3 +416,33 @@ function getAuthMode() {
         return 'trial';
     return 'none';
 }
+// ============================================
+// Update Notification Cache
+// ============================================
+const UPDATE_CHECK_INTERVAL_HOURS = 24;
+/**
+ * Get cached update info if still valid (within 24 hours)
+ */
+function getCachedUpdateInfo() {
+    const lastCheck = config.get('lastUpdateCheck');
+    const latestVersion = config.get('latestKnownVersion');
+    if (!lastCheck || !latestVersion)
+        return null;
+    const hoursSinceCheck = (Date.now() - new Date(lastCheck).getTime()) / (1000 * 60 * 60);
+    if (hoursSinceCheck > UPDATE_CHECK_INTERVAL_HOURS)
+        return null;
+    return { latestVersion, checkedAt: lastCheck };
+}
+/**
+ * Cache the latest version from npm registry
+ */
+function setCachedUpdateInfo(latestVersion) {
+    config.set('lastUpdateCheck', new Date().toISOString());
+    config.set('latestKnownVersion', latestVersion);
+}
+/**
+ * Get the current CLI version from package.json
+ */
+function getCliVersion() {
+    return '3.2.0'; // Keep in sync with package.json
+}

package/dist/index.js

@@ -26,6 +26,53 @@ const push_patterns_js_1 = require("./commands/push-patterns.js");
 const go_js_1 = require("./commands/go.js");
 const extend_js_1 = require("./commands/extend.js");
 const billing_js_1 = require("./commands/billing.js");
+const config_js_2 = require("./config.js");
+// ============================================
+// Automatic Update Notification
+// ============================================
+const CURRENT_VERSION = '3.2.0';
+async function checkForUpdatesInBackground() {
+    // Check if we have a valid cached result first (fast path)
+    const cached = (0, config_js_2.getCachedUpdateInfo)();
+    if (cached) {
+        if (cached.latestVersion !== CURRENT_VERSION) {
+            showUpdateBanner(CURRENT_VERSION, cached.latestVersion);
+        }
+        return;
+    }
+    // Fetch from npm registry (with timeout to not block CLI)
+    try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 3000);
+        const response = await fetch('https://registry.npmjs.org/@codebakers/cli/latest', {
+            headers: { 'Accept': 'application/json' },
+            signal: controller.signal,
+        });
+        clearTimeout(timeout);
+        if (response.ok) {
+            const data = await response.json();
+            const latestVersion = data.version;
+            (0, config_js_2.setCachedUpdateInfo)(latestVersion);
+            if (latestVersion !== CURRENT_VERSION) {
+                showUpdateBanner(CURRENT_VERSION, latestVersion);
+            }
+        }
+    }
+    catch {
+        // Silently fail - don't block CLI for update check
+    }
+}
+function showUpdateBanner(currentVersion, latestVersion) {
+    console.log(chalk_1.default.yellow(`
+  ╭─────────────────────────────────────────────────────────╮
+  │                                                         │
+  │   ${chalk_1.default.bold('Update available!')} ${chalk_1.default.gray(currentVersion)} → ${chalk_1.default.green(latestVersion)}                     │
+  │                                                         │
+  │   Run ${chalk_1.default.cyan('npm i -g @codebakers/cli@latest')} to update        │
+  │                                                         │
+  ╰─────────────────────────────────────────────────────────╯
+  `));
+}
 // Show welcome message when no command is provided
 function showWelcome() {
     console.log(chalk_1.default.blue(`
@@ -67,13 +114,14 @@ const program = new commander_1.Command();
 program
     .name('codebakers')
     .description('CodeBakers CLI - Production patterns for AI-assisted development')
-    .version('2.9.0');
+    .version('3.2.0');
 // Zero-friction trial entry (no signup required)
 program
     .command('go')
     .alias('start')
     .description('Start using CodeBakers instantly (no signup required)')
-    .action(go_js_1.go);
+    .option('-v, --verbose', 'Show detailed debug output for troubleshooting')
+    .action((options) => (0, go_js_1.go)({ verbose: options.verbose }));
 program
     .command('extend')
     .description('Extend your free trial with GitHub')
@@ -198,9 +246,16 @@ program
     .command('mcp-uninstall')
     .description('Remove MCP configuration from Claude Code')
     .action(mcp_config_js_1.mcpUninstall);
+// Add update check hook (runs before every command)
+program.hook('preAction', async () => {
+    await checkForUpdatesInBackground();
+});
 // Show welcome if no command provided
 if (process.argv.length <= 2) {
-    showWelcome();
+    // Still check for updates when showing welcome
+    checkForUpdatesInBackground().then(() => {
+        showWelcome();
+    });
 }
 else {
     program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codebakers/cli",
-  "version": "3.0.1",
+  "version": "3.2.0",
   "description": "CodeBakers CLI - Production patterns for AI-assisted development",
   "main": "dist/index.js",
   "bin": {
@@ -12,7 +12,10 @@
     "build": "tsc",
     "dev": "tsx src/index.ts",
     "start": "node dist/index.js",
-    "mcp": "tsx src/mcp/server.ts"
+    "mcp": "tsx src/mcp/server.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
   },
   "keywords": [
     "codebakers",
@@ -33,7 +36,9 @@
   },
   "devDependencies": {
     "@types/node": "^20.10.0",
+    "@vitest/coverage-v8": "^2.1.9",
     "tsx": "^4.7.0",
-    "typescript": "^5.3.0"
+    "typescript": "^5.3.0",
+    "vitest": "^2.1.9"
   }
 }

package/src/commands/doctor.ts

@@ -134,12 +134,18 @@ function checkProject(): CheckResult[] {
       const files = readdirSync(claudeDir).filter(f => f.endsWith('.md'));
       const moduleCount = files.length;
 
-      if (moduleCount >= 10) {
-        results.push({ ok: true, message: `${moduleCount} modules present` });
+      if (moduleCount >= 40) {
+        results.push({ ok: true, message: `${moduleCount} modules present (full set)` });
+      } else if (moduleCount >= 10) {
+        results.push({
+          ok: true,
+          message: `${moduleCount} modules present (partial set)`,
+          details: 'Run: codebakers upgrade to get all 47 modules'
+        });
       } else if (moduleCount > 0) {
         results.push({
           ok: false,
-          message: `Only ${moduleCount} modules found (expected 10+)`,
+          message: `Only ${moduleCount} modules found (expected 47)`,
           details: 'Run: codebakers upgrade to get all modules'
         });
       } else {

package/src/commands/go.ts

@@ -35,10 +35,24 @@ interface ContentResponse {
   modules: Record<string, string>;
 }
 
+interface GoOptions {
+  verbose?: boolean;
+}
+
+function log(message: string, options?: GoOptions): void {
+  if (options?.verbose) {
+    console.log(chalk.gray(`  [verbose] ${message}`));
+  }
+}
+
 /**
  * Zero-friction entry point - start using CodeBakers instantly
  */
-export async function go(): Promise<void> {
+export async function go(options: GoOptions = {}): Promise<void> {
+  log('Starting go command...', options);
+  log(`API URL: ${getApiUrl()}`, options);
+  log(`Working directory: ${process.cwd()}`, options);
+
   console.log(chalk.blue(`
   ╔═══════════════════════════════════════════════════════════╗
   ║                                                           ║
@@ -48,15 +62,18 @@ export async function go(): Promise<void> {
   `));
 
   // Check if user already has an API key (paid user)
+  log('Checking for existing API key...', options);
   const apiKey = getApiKey();
   if (apiKey) {
+    log(`Found API key: ${apiKey.substring(0, 8)}...`, options);
     console.log(chalk.green('  ✓ You\'re already logged in with an API key!\n'));
 
     // Still install patterns if not already installed
-    await installPatternsWithApiKey(apiKey);
-    await configureMCP();
+    await installPatternsWithApiKey(apiKey, options);
+    await configureMCP(options);
     return;
   }
+  log('No API key found, checking trial state...', options);
 
   // Check existing trial
   const existingTrial = getTrialState();
@@ -71,9 +88,9 @@ export async function go(): Promise<void> {
     }
 
     // Install patterns if not already installed
-    await installPatterns(existingTrial.trialId);
+    await installPatterns(existingTrial.trialId, options);
 
-    await configureMCP();
+    await configureMCP(options);
     return;
   }
 
@@ -162,10 +179,10 @@ export async function go(): Promise<void> {
     console.log('');
 
     // Install patterns (CLAUDE.md and .claude/)
-    await installPatterns(data.trialId);
+    await installPatterns(data.trialId, options);
 
     // Configure MCP
-    await configureMCP();
+    await configureMCP(options);
 
     // Show success message
     console.log(chalk.green(`
@@ -197,7 +214,8 @@ export async function go(): Promise<void> {
   }
 }
 
-async function configureMCP(): Promise<void> {
+async function configureMCP(options: GoOptions = {}): Promise<void> {
+  log('Configuring MCP integration...', options);
   const spinner = ora('Configuring Claude Code integration...').start();
   const isWindows = process.platform === 'win32';
 
@@ -274,11 +292,14 @@ async function attemptAutoRestart(): Promise<void> {
 /**
  * Install pattern files for API key users (paid users)
  */
-async function installPatternsWithApiKey(apiKey: string): Promise<void> {
+async function installPatternsWithApiKey(apiKey: string, options: GoOptions = {}): Promise<void> {
+  log('Installing patterns with API key...', options);
   const spinner = ora('Installing CodeBakers patterns...').start();
   const cwd = process.cwd();
   const apiUrl = getApiUrl();
 
+  log(`Fetching from: ${apiUrl}/api/content`, options);
+
   try {
     const response = await fetch(`${apiUrl}/api/content`, {
       method: 'GET',
@@ -288,14 +309,18 @@ async function installPatternsWithApiKey(apiKey: string): Promise<void> {
     });
 
     if (!response.ok) {
+      log(`Response not OK: ${response.status} ${response.statusText}`, options);
       spinner.warn('Could not download patterns');
       return;
     }
 
+    log('Response OK, parsing JSON...', options);
     const content: ContentResponse = await response.json();
-    await writePatternFiles(cwd, content, spinner);
+    log(`Received version: ${content.version}, modules: ${Object.keys(content.modules || {}).length}`, options);
+    await writePatternFiles(cwd, content, spinner, options);
 
   } catch (error) {
+    log(`Error: ${error instanceof Error ? error.message : String(error)}`, options);
     spinner.warn('Could not install patterns');
     console.log(chalk.gray('  Check your internet connection.\n'));
   }
@@ -304,13 +329,15 @@ async function installPatternsWithApiKey(apiKey: string): Promise<void> {
 /**
  * Install pattern files (CLAUDE.md and .claude/) for trial users
  */
-async function installPatterns(trialId: string): Promise<void> {
+async function installPatterns(trialId: string, options: GoOptions = {}): Promise<void> {
+  log(`Installing patterns with trial ID: ${trialId.substring(0, 8)}...`, options);
   const spinner = ora('Installing CodeBakers patterns...').start();
   const cwd = process.cwd();
   const apiUrl = getApiUrl();
 
   try {
     // Fetch patterns using trial ID
+    log(`Fetching from: ${apiUrl}/api/content`, options);
     const response = await fetch(`${apiUrl}/api/content`, {
       method: 'GET',
       headers: {
@@ -319,6 +346,7 @@ async function installPatterns(trialId: string): Promise<void> {
     });
 
     if (!response.ok) {
+      log(`Primary endpoint failed: ${response.status}, trying trial endpoint...`, options);
       // Try without auth - some patterns may be available for trial
       const publicResponse = await fetch(`${apiUrl}/api/content/trial`, {
         method: 'GET',
@@ -328,25 +356,30 @@ async function installPatterns(trialId: string): Promise<void> {
       });
 
       if (!publicResponse.ok) {
+        log(`Trial endpoint also failed: ${publicResponse.status}`, options);
         spinner.warn('Could not download patterns (will use MCP tools)');
         return;
       }
 
       const content: ContentResponse = await publicResponse.json();
-      await writePatternFiles(cwd, content, spinner);
+      log(`Received version: ${content.version}, modules: ${Object.keys(content.modules || {}).length}`, options);
+      await writePatternFiles(cwd, content, spinner, options);
       return;
     }
 
     const content: ContentResponse = await response.json();
-    await writePatternFiles(cwd, content, spinner);
+    log(`Received version: ${content.version}, modules: ${Object.keys(content.modules || {}).length}`, options);
+    await writePatternFiles(cwd, content, spinner, options);
 
   } catch (error) {
+    log(`Error: ${error instanceof Error ? error.message : String(error)}`, options);
     spinner.warn('Could not install patterns (will use MCP tools)');
     console.log(chalk.gray('  Patterns will be available via MCP tools.\n'));
   }
 }
 
-async function writePatternFiles(cwd: string, content: ContentResponse, spinner: ReturnType<typeof ora>): Promise<void> {
+async function writePatternFiles(cwd: string, content: ContentResponse, spinner: ReturnType<typeof ora>, options: GoOptions = {}): Promise<void> {
+  log(`Writing pattern files to ${cwd}...`, options);
   // Check if patterns already exist
   const claudeMdPath = join(cwd, 'CLAUDE.md');
   if (existsSync(claudeMdPath)) {

package/src/config.ts

@@ -116,6 +116,9 @@ interface ConfigSchema {
   lastKeySync: string | null;  // ISO date of last sync with server
   // Trial state (for zero-friction onboarding)
   trial: TrialState | null;
+  // Update notification cache
+  lastUpdateCheck: string | null;  // ISO date of last npm registry check
+  latestKnownVersion: string | null;  // Cached latest version from npm
 }
 
 // Create default service keys object with all keys set to null
@@ -133,6 +136,8 @@ const config = new Conf<ConfigSchema>({
     serviceKeys: defaultServiceKeys,
     lastKeySync: null,
     trial: null,
+    lastUpdateCheck: null,
+    latestKnownVersion: null,
   },
   // Migration to add new keys when upgrading from old version
   migrations: {
@@ -489,3 +494,39 @@ export function getAuthMode(): 'apiKey' | 'trial' | 'none' {
 
   return 'none';
 }
+
+// ============================================
+// Update Notification Cache
+// ============================================
+
+const UPDATE_CHECK_INTERVAL_HOURS = 24;
+
+/**
+ * Get cached update info if still valid (within 24 hours)
+ */
+export function getCachedUpdateInfo(): { latestVersion: string; checkedAt: string } | null {
+  const lastCheck = config.get('lastUpdateCheck');
+  const latestVersion = config.get('latestKnownVersion');
+
+  if (!lastCheck || !latestVersion) return null;
+
+  const hoursSinceCheck = (Date.now() - new Date(lastCheck).getTime()) / (1000 * 60 * 60);
+  if (hoursSinceCheck > UPDATE_CHECK_INTERVAL_HOURS) return null;
+
+  return { latestVersion, checkedAt: lastCheck };
+}
+
+/**
+ * Cache the latest version from npm registry
+ */
+export function setCachedUpdateInfo(latestVersion: string): void {
+  config.set('lastUpdateCheck', new Date().toISOString());
+  config.set('latestKnownVersion', latestVersion);
+}
+
+/**
+ * Get the current CLI version from package.json
+ */
+export function getCliVersion(): string {
+  return '3.2.0'; // Keep in sync with package.json
+}

package/src/index.ts

@@ -22,6 +22,61 @@ import { pushPatterns, pushPatternsInteractive } from './commands/push-patterns.
 import { go } from './commands/go.js';
 import { extend } from './commands/extend.js';
 import { billing } from './commands/billing.js';
+import { getCachedUpdateInfo, setCachedUpdateInfo, getCliVersion } from './config.js';
+
+// ============================================
+// Automatic Update Notification
+// ============================================
+
+const CURRENT_VERSION = '3.2.0';
+
+async function checkForUpdatesInBackground(): Promise<void> {
+  // Check if we have a valid cached result first (fast path)
+  const cached = getCachedUpdateInfo();
+  if (cached) {
+    if (cached.latestVersion !== CURRENT_VERSION) {
+      showUpdateBanner(CURRENT_VERSION, cached.latestVersion);
+    }
+    return;
+  }
+
+  // Fetch from npm registry (with timeout to not block CLI)
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 3000);
+
+    const response = await fetch('https://registry.npmjs.org/@codebakers/cli/latest', {
+      headers: { 'Accept': 'application/json' },
+      signal: controller.signal,
+    });
+
+    clearTimeout(timeout);
+
+    if (response.ok) {
+      const data = await response.json();
+      const latestVersion = data.version;
+      setCachedUpdateInfo(latestVersion);
+
+      if (latestVersion !== CURRENT_VERSION) {
+        showUpdateBanner(CURRENT_VERSION, latestVersion);
+      }
+    }
+  } catch {
+    // Silently fail - don't block CLI for update check
+  }
+}
+
+function showUpdateBanner(currentVersion: string, latestVersion: string): void {
+  console.log(chalk.yellow(`
+  ╭─────────────────────────────────────────────────────────╮
+  │                                                         │
+  │   ${chalk.bold('Update available!')} ${chalk.gray(currentVersion)} → ${chalk.green(latestVersion)}                     │
+  │                                                         │
+  │   Run ${chalk.cyan('npm i -g @codebakers/cli@latest')} to update        │
+  │                                                         │
+  ╰─────────────────────────────────────────────────────────╯
+  `));
+}
 
 // Show welcome message when no command is provided
 function showWelcome(): void {
@@ -72,14 +127,15 @@ const program = new Command();
 program
   .name('codebakers')
   .description('CodeBakers CLI - Production patterns for AI-assisted development')
-  .version('2.9.0');
+  .version('3.2.0');
 
 // Zero-friction trial entry (no signup required)
 program
   .command('go')
   .alias('start')
   .description('Start using CodeBakers instantly (no signup required)')
-  .action(go);
+  .option('-v, --verbose', 'Show detailed debug output for troubleshooting')
+  .action((options) => go({ verbose: options.verbose }));
 
 program
   .command('extend')
@@ -224,9 +280,17 @@ program
   .description('Remove MCP configuration from Claude Code')
   .action(mcpUninstall);
 
+// Add update check hook (runs before every command)
+program.hook('preAction', async () => {
+  await checkForUpdatesInBackground();
+});
+
 // Show welcome if no command provided
 if (process.argv.length <= 2) {
-  showWelcome();
+  // Still check for updates when showing welcome
+  checkForUpdatesInBackground().then(() => {
+    showWelcome();
+  });
 } else {
   program.parse();
 }

package/tests/api.test.ts

@@ -0,0 +1,216 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// Mock fetch globally
+const mockFetch = vi.fn();
+global.fetch = mockFetch;
+
+describe('API communication', () => {
+  beforeEach(() => {
+    mockFetch.mockClear();
+  });
+
+  describe('content API', () => {
+    it('should fetch content with API key', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({
+          version: '5.1',
+          router: '# Router content',
+          modules: {
+            '00-core.md': '# Core',
+            '02-auth.md': '# Auth',
+          },
+        }),
+      });
+
+      const response = await fetch('https://codebakers.ai/api/content', {
+        headers: { Authorization: 'Bearer test-key' },
+      });
+
+      expect(response.ok).toBe(true);
+      const data = await response.json();
+      expect(data.version).toBe('5.1');
+      expect(Object.keys(data.modules).length).toBe(2);
+    });
+
+    it('should fetch content with trial ID', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({
+          version: '5.1',
+          router: '# Router content',
+          modules: { '00-core.md': '# Core' },
+        }),
+      });
+
+      const response = await fetch('https://codebakers.ai/api/content', {
+        headers: { 'X-Trial-ID': 'trial-123' },
+      });
+
+      expect(response.ok).toBe(true);
+    });
+
+    it('should handle unauthorized response', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 401,
+        json: () => Promise.resolve({ error: 'Unauthorized' }),
+      });
+
+      const response = await fetch('https://codebakers.ai/api/content', {
+        headers: { Authorization: 'Bearer invalid-key' },
+      });
+
+      expect(response.ok).toBe(false);
+      expect(response.status).toBe(401);
+    });
+
+    it('should handle network errors', async () => {
+      mockFetch.mockRejectedValueOnce(new Error('Network error'));
+
+      await expect(
+        fetch('https://codebakers.ai/api/content')
+      ).rejects.toThrow('Network error');
+    });
+  });
+
+  describe('trial API', () => {
+    it('should start a new trial', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({
+          trialId: 'trial-123',
+          stage: 'anonymous',
+          expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString(),
+          daysRemaining: 7,
+        }),
+      });
+
+      const response = await fetch('https://codebakers.ai/api/trial/start', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          deviceHash: 'test-hash',
+          machineId: 'test-machine',
+          platform: 'test',
+          hostname: 'test-host',
+        }),
+      });
+
+      expect(response.ok).toBe(true);
+      const data = await response.json();
+      expect(data.trialId).toBe('trial-123');
+      expect(data.daysRemaining).toBe(7);
+    });
+
+    it('should handle trial not available', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 400,
+        json: () => Promise.resolve({ error: 'trial_not_available' }),
+      });
+
+      const response = await fetch('https://codebakers.ai/api/trial/start', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ deviceHash: 'used-hash' }),
+      });
+
+      expect(response.ok).toBe(false);
+      const data = await response.json();
+      expect(data.error).toBe('trial_not_available');
+    });
+
+    it('should handle expired trial', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({
+          stage: 'expired',
+          canExtend: true,
+        }),
+      });
+
+      const response = await fetch('https://codebakers.ai/api/trial/start', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ deviceHash: 'expired-hash' }),
+      });
+
+      const data = await response.json();
+      expect(data.stage).toBe('expired');
+      expect(data.canExtend).toBe(true);
+    });
+  });
+
+  describe('API key validation', () => {
+    it('should validate a correct API key', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ valid: true }),
+      });
+
+      const response = await fetch('https://codebakers.ai/api/verify', {
+        headers: { Authorization: 'Bearer valid-key' },
+      });
+
+      expect(response.ok).toBe(true);
+      const data = await response.json();
+      expect(data.valid).toBe(true);
+    });
+
+    it('should reject an invalid API key', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 401,
+        json: () => Promise.resolve({ valid: false, error: 'Invalid API key' }),
+      });
+
+      const response = await fetch('https://codebakers.ai/api/verify', {
+        headers: { Authorization: 'Bearer invalid-key' },
+      });
+
+      expect(response.ok).toBe(false);
+    });
+  });
+});
+
+describe('error handling', () => {
+  beforeEach(() => {
+    mockFetch.mockClear();
+  });
+
+  it('should provide helpful error messages for timeout', async () => {
+    mockFetch.mockRejectedValueOnce(new Error('timeout'));
+
+    try {
+      await fetch('https://codebakers.ai/api/content');
+    } catch (error) {
+      expect(error).toBeInstanceOf(Error);
+      if (error instanceof Error) {
+        expect(error.message).toContain('timeout');
+      }
+    }
+  });
+
+  it('should handle rate limiting', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: false,
+      status: 429,
+      json: () => Promise.resolve({ error: 'Too many requests' }),
+    });
+
+    const response = await fetch('https://codebakers.ai/api/content');
+    expect(response.status).toBe(429);
+  });
+
+  it('should handle server errors', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: false,
+      status: 500,
+      json: () => Promise.resolve({ error: 'Internal server error' }),
+    });
+
+    const response = await fetch('https://codebakers.ai/api/content');
+    expect(response.status).toBe(500);
+  });
+});

package/tests/doctor.test.ts

@@ -0,0 +1,168 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { existsSync, writeFileSync, mkdirSync, rmSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+describe('doctor command checks', () => {
+  let testDir: string;
+  let originalCwd: string;
+
+  beforeEach(() => {
+    originalCwd = process.cwd();
+    testDir = join(tmpdir(), `codebakers-doctor-test-${Date.now()}`);
+    mkdirSync(testDir, { recursive: true });
+    process.chdir(testDir);
+  });
+
+  afterEach(() => {
+    process.chdir(originalCwd);
+    try {
+      rmSync(testDir, { recursive: true, force: true });
+    } catch {
+      // Ignore cleanup errors
+    }
+  });
+
+  describe('CLAUDE.md checks', () => {
+    it('should detect missing CLAUDE.md', () => {
+      const claudeMdPath = join(testDir, 'CLAUDE.md');
+      expect(existsSync(claudeMdPath)).toBe(false);
+    });
+
+    it('should detect valid CodeBakers CLAUDE.md', () => {
+      const claudeMdPath = join(testDir, 'CLAUDE.md');
+      writeFileSync(claudeMdPath, '# CODEBAKERS SMART ROUTER\nVersion: 5.1');
+
+      const content = require('fs').readFileSync(claudeMdPath, 'utf-8');
+      const isCodeBakers = content.includes('CODEBAKERS') || content.includes('CodeBakers');
+      expect(isCodeBakers).toBe(true);
+    });
+
+    it('should detect non-CodeBakers CLAUDE.md', () => {
+      const claudeMdPath = join(testDir, 'CLAUDE.md');
+      writeFileSync(claudeMdPath, '# My Custom Instructions');
+
+      const content = require('fs').readFileSync(claudeMdPath, 'utf-8');
+      const isCodeBakers = content.includes('CODEBAKERS') || content.includes('CodeBakers');
+      expect(isCodeBakers).toBe(false);
+    });
+  });
+
+  describe('.claude folder checks', () => {
+    it('should detect missing .claude folder', () => {
+      const claudeDir = join(testDir, '.claude');
+      expect(existsSync(claudeDir)).toBe(false);
+    });
+
+    it('should count modules in .claude folder', () => {
+      const claudeDir = join(testDir, '.claude');
+      mkdirSync(claudeDir, { recursive: true });
+
+      // Create test modules
+      const modules = [
+        '00-core.md',
+        '01-database.md',
+        '02-auth.md',
+        '03-api.md',
+        '04-frontend.md',
+      ];
+
+      for (const mod of modules) {
+        writeFileSync(join(claudeDir, mod), `# ${mod}`);
+      }
+
+      const files = readdirSync(claudeDir).filter(f => f.endsWith('.md'));
+      expect(files.length).toBe(5);
+    });
+
+    it('should detect insufficient modules (less than 10)', () => {
+      const claudeDir = join(testDir, '.claude');
+      mkdirSync(claudeDir, { recursive: true });
+
+      // Create only 3 modules
+      writeFileSync(join(claudeDir, '00-core.md'), '# Core');
+      writeFileSync(join(claudeDir, '01-database.md'), '# Database');
+      writeFileSync(join(claudeDir, '02-auth.md'), '# Auth');
+
+      const files = readdirSync(claudeDir).filter(f => f.endsWith('.md'));
+      expect(files.length).toBeLessThan(10);
+    });
+
+    it('should detect full module set (47+ modules)', () => {
+      const claudeDir = join(testDir, '.claude');
+      mkdirSync(claudeDir, { recursive: true });
+
+      // Create 47 modules
+      for (let i = 0; i < 47; i++) {
+        const name = i.toString().padStart(2, '0');
+        writeFileSync(join(claudeDir, `${name}-module.md`), `# Module ${i}`);
+      }
+
+      const files = readdirSync(claudeDir).filter(f => f.endsWith('.md'));
+      expect(files.length).toBeGreaterThanOrEqual(47);
+    });
+
+    it('should check for required 00-core.md', () => {
+      const claudeDir = join(testDir, '.claude');
+      mkdirSync(claudeDir, { recursive: true });
+
+      const corePath = join(claudeDir, '00-core.md');
+      expect(existsSync(corePath)).toBe(false);
+
+      writeFileSync(corePath, '# Core patterns');
+      expect(existsSync(corePath)).toBe(true);
+    });
+  });
+
+  describe('project state checks', () => {
+    it('should handle missing PROJECT-STATE.md gracefully', () => {
+      const statePath = join(testDir, 'PROJECT-STATE.md');
+      // This is optional, should not fail
+      expect(existsSync(statePath)).toBe(false);
+    });
+
+    it('should detect existing PROJECT-STATE.md', () => {
+      const statePath = join(testDir, 'PROJECT-STATE.md');
+      writeFileSync(statePath, '# Project State\n');
+      expect(existsSync(statePath)).toBe(true);
+    });
+  });
+});
+
+describe('doctor summary', () => {
+  it('should calculate correct pass/fail counts', () => {
+    const checks = [
+      { ok: true, message: 'Check 1' },
+      { ok: true, message: 'Check 2' },
+      { ok: false, message: 'Check 3' },
+      { ok: true, message: 'Check 4' },
+    ];
+
+    const passed = checks.filter(c => c.ok).length;
+    const failed = checks.filter(c => !c.ok).length;
+    const total = checks.length;
+
+    expect(passed).toBe(3);
+    expect(failed).toBe(1);
+    expect(total).toBe(4);
+  });
+
+  it('should provide fix suggestions for common issues', () => {
+    const suggestions: string[] = [];
+
+    // Simulate missing CLAUDE.md
+    const hasClaudeMd = false;
+    if (!hasClaudeMd) {
+      suggestions.push('Run: codebakers install');
+    }
+
+    // Simulate missing hook
+    const hasHook = false;
+    if (!hasHook) {
+      suggestions.push('Run: codebakers install-hook');
+    }
+
+    expect(suggestions).toContain('Run: codebakers install');
+    expect(suggestions).toContain('Run: codebakers install-hook');
+  });
+});

package/tests/go.test.ts

@@ -0,0 +1,142 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { existsSync, writeFileSync, mkdirSync, rmSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+// Mock modules before importing
+vi.mock('../src/config.js', () => ({
+  getApiKey: vi.fn(() => null),
+  getTrialState: vi.fn(() => null),
+  setTrialState: vi.fn(),
+  getApiUrl: vi.fn(() => 'https://codebakers.ai'),
+  isTrialExpired: vi.fn(() => false),
+  getTrialDaysRemaining: vi.fn(() => 7),
+}));
+
+vi.mock('../src/lib/fingerprint.js', () => ({
+  getDeviceFingerprint: vi.fn(() => ({
+    deviceHash: 'test-hash',
+    machineId: 'test-machine',
+    platform: 'test',
+    hostname: 'test-host',
+  })),
+}));
+
+describe('go command', () => {
+  let testDir: string;
+
+  beforeEach(() => {
+    // Create a temp directory for each test
+    testDir = join(tmpdir(), `codebakers-test-${Date.now()}`);
+    mkdirSync(testDir, { recursive: true });
+    process.chdir(testDir);
+  });
+
+  afterEach(() => {
+    // Clean up
+    try {
+      rmSync(testDir, { recursive: true, force: true });
+    } catch {
+      // Ignore cleanup errors
+    }
+  });
+
+  it('should create CLAUDE.md when patterns are installed', async () => {
+    const claudeMdPath = join(testDir, 'CLAUDE.md');
+
+    // Simulate pattern installation
+    writeFileSync(claudeMdPath, '# CodeBakers Router');
+
+    expect(existsSync(claudeMdPath)).toBe(true);
+  });
+
+  it('should create .claude directory with modules', async () => {
+    const claudeDir = join(testDir, '.claude');
+    mkdirSync(claudeDir, { recursive: true });
+
+    // Simulate module installation
+    writeFileSync(join(claudeDir, '00-core.md'), '# Core patterns');
+    writeFileSync(join(claudeDir, '02-auth.md'), '# Auth patterns');
+
+    expect(existsSync(claudeDir)).toBe(true);
+    expect(existsSync(join(claudeDir, '00-core.md'))).toBe(true);
+    expect(existsSync(join(claudeDir, '02-auth.md'))).toBe(true);
+  });
+
+  it('should handle network errors gracefully', async () => {
+    // Mock fetch to fail
+    global.fetch = vi.fn().mockRejectedValue(new Error('Network error'));
+
+    // The go command should not throw, just warn
+    expect(() => {
+      // Simulating the error handling logic
+      try {
+        throw new Error('Network error');
+      } catch (error) {
+        if (error instanceof Error && error.message.includes('Network')) {
+          // Expected behavior - handle gracefully
+        }
+      }
+    }).not.toThrow();
+  });
+});
+
+describe('pattern file writing', () => {
+  let testDir: string;
+
+  beforeEach(() => {
+    testDir = join(tmpdir(), `codebakers-test-${Date.now()}`);
+    mkdirSync(testDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    try {
+      rmSync(testDir, { recursive: true, force: true });
+    } catch {
+      // Ignore cleanup errors
+    }
+  });
+
+  it('should not overwrite existing CLAUDE.md', () => {
+    const claudeMdPath = join(testDir, 'CLAUDE.md');
+    const originalContent = '# My existing CLAUDE.md';
+
+    writeFileSync(claudeMdPath, originalContent);
+
+    // Simulate check before writing
+    if (existsSync(claudeMdPath)) {
+      // Should skip writing
+      const content = require('fs').readFileSync(claudeMdPath, 'utf-8');
+      expect(content).toBe(originalContent);
+    }
+  });
+
+  it('should add .claude/ to .gitignore if exists', () => {
+    const gitignorePath = join(testDir, '.gitignore');
+    writeFileSync(gitignorePath, 'node_modules/\n.env\n');
+
+    // Simulate gitignore update
+    let gitignore = require('fs').readFileSync(gitignorePath, 'utf-8');
+    if (!gitignore.includes('.claude/')) {
+      gitignore += '\n# CodeBakers patterns\n.claude/\n';
+      writeFileSync(gitignorePath, gitignore);
+    }
+
+    const updatedContent = require('fs').readFileSync(gitignorePath, 'utf-8');
+    expect(updatedContent).toContain('.claude/');
+  });
+
+  it('should handle missing .gitignore gracefully', () => {
+    const gitignorePath = join(testDir, '.gitignore');
+
+    // Don't create .gitignore
+    expect(existsSync(gitignorePath)).toBe(false);
+
+    // Should not throw when trying to update non-existent .gitignore
+    expect(() => {
+      if (existsSync(gitignorePath)) {
+        // Would update gitignore
+      }
+    }).not.toThrow();
+  });
+});

package/vitest.config.ts

@@ -0,0 +1,16 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['tests/**/*.test.ts'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'html'],
+      include: ['src/**/*.ts'],
+      exclude: ['src/mcp/**', 'src/templates/**'],
+    },
+    testTimeout: 30000,
+  },
+});