wiggum-cli 0.11.13 → 0.11.15

package/dist/utils/env.d.ts

@@ -11,12 +11,27 @@
  * - Strips matching surrounding quotes (single or double) from values.
  */
 export declare function parseEnvContent(content: string): Record<string, string>;
+/**
+ * Write API keys to an env file, preserving existing content.
+ *
+ * - Merges keys into existing file content (preserves other keys).
+ * - Replaces existing key values if the key already exists.
+ * - Creates parent directories if they don't exist.
+ * - Creates the file if it doesn't exist.
+ * - Skips empty values (keys with empty strings are ignored).
+ *
+ * @param filePath - Absolute path to the .env.local file
+ * @param keys - Record of environment variable names to values
+ */
+export declare function writeKeysToEnvFile(filePath: string, keys: Record<string, string>): void;
 /**
  * Load known AI provider API keys from .ralph/.env.local into process.env.
  *
+ * - Prefers .ralph/.env.local as the canonical source (if it exists).
+ * - Falls back to root .env.local if .ralph/.env.local does not exist (backward compatibility).
  * - Only keys in KNOWN_API_KEYS are loaded; all others are ignored.
  * - File values override existing process.env values (file takes precedence).
- * - If the file does not exist or cannot be read, this is a silent no-op.
+ * - If neither file exists or cannot be read, this is a silent no-op.
  * - Malformed lines are skipped without aborting.
  */
 export declare function loadApiKeysFromEnvLocal(): void;

package/dist/utils/env.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/utils/env.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA2BvE;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAgB9C"}
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/utils/env.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA2BvE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CA8BvF;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CA0B9C"}

package/dist/utils/env.js

@@ -39,18 +39,69 @@ export function parseEnvContent(content) {
     }
     return result;
 }
+/**
+ * Write API keys to an env file, preserving existing content.
+ *
+ * - Merges keys into existing file content (preserves other keys).
+ * - Replaces existing key values if the key already exists.
+ * - Creates parent directories if they don't exist.
+ * - Creates the file if it doesn't exist.
+ * - Skips empty values (keys with empty strings are ignored).
+ *
+ * @param filePath - Absolute path to the .env.local file
+ * @param keys - Record of environment variable names to values
+ */
+export function writeKeysToEnvFile(filePath, keys) {
+    // Ensure parent directory exists
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    // Read existing content if file exists
+    let envContent = '';
+    if (fs.existsSync(filePath)) {
+        envContent = fs.readFileSync(filePath, 'utf-8');
+    }
+    // Merge keys into content
+    const escapeRegex = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    for (const [envVar, value] of Object.entries(keys)) {
+        if (!value)
+            continue; // Skip empty values
+        const keyRegex = new RegExp(`^${escapeRegex(envVar)}=.*$`, 'm');
+        if (keyRegex.test(envContent)) {
+            // Replace existing key
+            envContent = envContent.replace(keyRegex, `${envVar}=${value}`);
+        }
+        else {
+            // Append new key
+            envContent = envContent.trimEnd() + (envContent ? '\n' : '') + `${envVar}=${value}\n`;
+        }
+    }
+    fs.writeFileSync(filePath, envContent);
+}
 /**
  * Load known AI provider API keys from .ralph/.env.local into process.env.
  *
+ * - Prefers .ralph/.env.local as the canonical source (if it exists).
+ * - Falls back to root .env.local if .ralph/.env.local does not exist (backward compatibility).
  * - Only keys in KNOWN_API_KEYS are loaded; all others are ignored.
  * - File values override existing process.env values (file takes precedence).
- * - If the file does not exist or cannot be read, this is a silent no-op.
+ * - If neither file exists or cannot be read, this is a silent no-op.
  * - Malformed lines are skipped without aborting.
  */
 export function loadApiKeysFromEnvLocal() {
     try {
-        const envPath = path.join(process.cwd(), '.ralph', '.env.local');
-        if (!fs.existsSync(envPath))
+        const ralphEnvPath = path.join(process.cwd(), '.ralph', '.env.local');
+        const rootEnvPath = path.join(process.cwd(), '.env.local');
+        // Prefer .ralph/.env.local, fall back to root .env.local
+        let envPath = null;
+        if (fs.existsSync(ralphEnvPath)) {
+            envPath = ralphEnvPath;
+        }
+        else if (fs.existsSync(rootEnvPath)) {
+            envPath = rootEnvPath;
+        }
+        if (!envPath)
             return;
         const content = fs.readFileSync(envPath, 'utf8');
         const parsed = parseEnvContent(content);
@@ -61,7 +112,7 @@ export function loadApiKeysFromEnvLocal() {
         }
     }
     catch (err) {
-        logger.debug(`Failed to load .ralph/.env.local: ${err instanceof Error ? err.message : String(err)}`);
+        logger.debug(`Failed to load env file: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
 //# sourceMappingURL=env.js.map

package/dist/utils/env.js.map

@@ -1 +1 @@
-{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/utils/env.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,OAAe;IAC7C,MAAM,MAAM,GAA2B,EAAE,CAAC;IAE1C,KAAK,MAAM,OAAO,IAAI,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;QAC7C,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;QAC5B,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAS;QAE5C,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,GAAG,KAAK,CAAC,CAAC;YAAE,SAAS;QAEzB,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;QACtC,IAAI,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAEvC,oCAAoC;QACpC,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;YACtB,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;YACvB,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;YACrC,IAAI,CAAC,KAAK,KAAK,GAAG,IAAI,IAAI,KAAK,GAAG,CAAC,IAAI,CAAC,KAAK,KAAK,GAAG,IAAI,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;gBACvE,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;YAC7B,CAAC;QACH,CAAC;QAED,IAAI,CAAC,GAAG;YAAE,SAAS;QACnB,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACtB,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,uBAAuB;IACrC,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,QAAQ,EAAE,YAAY,CAAC,CAAC;QACjE,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC;YAAE,OAAO;QAEpC,MAAM,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACjD,MAAM,MAAM,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;QAExC,KAAK,MAAM,GAAG,IAAI,cAAc,EAAE,CAAC;YACjC,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,SAAS,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,CAAC;gBACpD,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;YACjC,CAAC;QACH,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,CAAC,KAAK,CAAC,qCAAqC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACxG,CAAC;AACH,CAAC"}
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/utils/env.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiggum-cli",
-  "version": "0.11.13",
+  "version": "0.11.15",
   "description": "AI-powered feature development loop CLI",
   "type": "module",
   "main": "dist/index.js",

package/src/commands/config.test.ts

@@ -0,0 +1,225 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import fs from 'fs';
+import path from 'path';
+import { handleConfigCommand } from './config.js';
+import type { SessionState } from '../repl/session-state.js';
+
+// Mock logger to suppress console output during tests
+vi.mock('../utils/logger.js', () => ({
+  logger: {
+    error: vi.fn(),
+    success: vi.fn(),
+  },
+}));
+
+// Mock colors to avoid picocolors output during tests
+vi.mock('../utils/colors.js', () => ({
+  simpson: {
+    yellow: (s: string) => s,
+  },
+}));
+
+describe('handleConfigCommand - init guard', () => {
+  const mockState: SessionState = {
+    projectRoot: '/fake/project',
+    provider: 'openai',
+    model: 'gpt-4',
+    conversationHistory: [],
+  };
+
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    // Clear process.env
+    delete process.env.TAVILY_API_KEY;
+    delete process.env.CONTEXT7_API_KEY;
+    delete process.env.BRAINTRUST_API_KEY;
+  });
+
+  it('throws error when .ralph/ does not exist', async () => {
+    const ralphDir = path.join(mockState.projectRoot, '.ralph');
+
+    vi.spyOn(fs, 'existsSync').mockImplementation((p) => {
+      // .ralph/ directory does not exist
+      return p !== ralphDir;
+    });
+
+    const writeSpy = vi.spyOn(fs, 'writeFileSync');
+    const mkdirSpy = vi.spyOn(fs, 'mkdirSync');
+
+    const args = ['set', 'tavily', 'tvly-test-key-1234567890'];
+
+    await handleConfigCommand(args, mockState);
+
+    // Should not create .ralph/ directory
+    expect(mkdirSpy).not.toHaveBeenCalled();
+
+    // Should not write to .env.local
+    expect(writeSpy).not.toHaveBeenCalled();
+
+    // Should not set environment variable
+    expect(process.env.TAVILY_API_KEY).toBeUndefined();
+  });
+
+  it('writes to .ralph/.env.local when .ralph/ exists', async () => {
+    const ralphDir = path.join(mockState.projectRoot, '.ralph');
+    const envLocalPath = path.join(ralphDir, '.env.local');
+
+    vi.spyOn(fs, 'existsSync').mockImplementation((p) => {
+      // .ralph/ directory exists
+      if (p === ralphDir) return true;
+      // .env.local does not exist yet
+      if (p === envLocalPath) return false;
+      return false;
+    });
+
+    vi.spyOn(fs, 'statSync').mockReturnValue({
+      isDirectory: () => true,
+    } as any);
+
+    vi.spyOn(fs, 'readFileSync').mockReturnValue('');
+    vi.spyOn(fs, 'mkdirSync').mockReturnValue(undefined);
+    const writeSpy = vi.spyOn(fs, 'writeFileSync').mockReturnValue(undefined);
+
+    const args = ['set', 'tavily', 'tvly-test-key-1234567890'];
+
+    await handleConfigCommand(args, mockState);
+
+    // Should write to .ralph/.env.local
+    expect(writeSpy).toHaveBeenCalledWith(
+      envLocalPath,
+      'TAVILY_API_KEY=tvly-test-key-1234567890\n'
+    );
+
+    // Should set environment variable
+    expect(process.env.TAVILY_API_KEY).toBe('tvly-test-key-1234567890');
+  });
+
+  it('merges new key into existing .ralph/.env.local', async () => {
+    const ralphDir = path.join(mockState.projectRoot, '.ralph');
+    const envLocalPath = path.join(ralphDir, '.env.local');
+    const existingContent = 'CONTEXT7_API_KEY=c7-existing-123\n';
+
+    vi.spyOn(fs, 'existsSync').mockImplementation((p) => {
+      // Both .ralph/ and .env.local exist
+      if (p === ralphDir) return true;
+      if (p === envLocalPath) return true;
+      return false;
+    });
+
+    vi.spyOn(fs, 'statSync').mockReturnValue({
+      isDirectory: () => true,
+    } as any);
+
+    vi.spyOn(fs, 'readFileSync').mockReturnValue(existingContent);
+    const writeSpy = vi.spyOn(fs, 'writeFileSync').mockReturnValue(undefined);
+
+    const args = ['set', 'tavily', 'tvly-test-key-1234567890'];
+
+    await handleConfigCommand(args, mockState);
+
+    const writtenContent = (writeSpy as any).mock.calls[0][1];
+
+    // Should preserve existing key
+    expect(writtenContent).toContain('CONTEXT7_API_KEY=c7-existing-123');
+
+    // Should add new key
+    expect(writtenContent).toContain('TAVILY_API_KEY=tvly-test-key-1234567890');
+  });
+
+  it('replaces existing key value in .ralph/.env.local', async () => {
+    const ralphDir = path.join(mockState.projectRoot, '.ralph');
+    const envLocalPath = path.join(ralphDir, '.env.local');
+    const existingContent = 'TAVILY_API_KEY=old-key-value\n';
+
+    vi.spyOn(fs, 'existsSync').mockImplementation((p) => {
+      if (p === ralphDir) return true;
+      if (p === envLocalPath) return true;
+      return false;
+    });
+
+    vi.spyOn(fs, 'statSync').mockReturnValue({
+      isDirectory: () => true,
+    } as any);
+
+    vi.spyOn(fs, 'readFileSync').mockReturnValue(existingContent);
+    const writeSpy = vi.spyOn(fs, 'writeFileSync').mockReturnValue(undefined);
+
+    const args = ['set', 'tavily', 'tvly-new-key-9876543210'];
+
+    await handleConfigCommand(args, mockState);
+
+    const writtenContent = (writeSpy as any).mock.calls[0][1];
+
+    // Should replace old value
+    expect(writtenContent).not.toContain('old-key-value');
+    expect(writtenContent).toContain('TAVILY_API_KEY=tvly-new-key-9876543210');
+  });
+
+  it('validates API key length', async () => {
+    const ralphDir = path.join(mockState.projectRoot, '.ralph');
+
+    vi.spyOn(fs, 'existsSync').mockReturnValue(true);
+    vi.spyOn(fs, 'statSync').mockReturnValue({
+      isDirectory: () => true,
+    } as any);
+
+    const writeSpy = vi.spyOn(fs, 'writeFileSync');
+
+    // Key too short (< 10 chars)
+    const args = ['set', 'tavily', 'short'];
+
+    await handleConfigCommand(args, mockState);
+
+    // Should not write
+    expect(writeSpy).not.toHaveBeenCalled();
+  });
+
+  it('rejects unknown service names', async () => {
+    const ralphDir = path.join(mockState.projectRoot, '.ralph');
+
+    vi.spyOn(fs, 'existsSync').mockReturnValue(true);
+    vi.spyOn(fs, 'statSync').mockReturnValue({
+      isDirectory: () => true,
+    } as any);
+
+    const writeSpy = vi.spyOn(fs, 'writeFileSync');
+
+    const args = ['set', 'unknown-service', 'some-key-1234567890'];
+
+    await handleConfigCommand(args, mockState);
+
+    // Should not write
+    expect(writeSpy).not.toHaveBeenCalled();
+  });
+
+  it('handles all supported services', async () => {
+    const ralphDir = path.join(mockState.projectRoot, '.ralph');
+    const envLocalPath = path.join(ralphDir, '.env.local');
+
+    vi.spyOn(fs, 'existsSync').mockImplementation((p) => {
+      if (p === ralphDir) return true;
+      if (p === envLocalPath) return false;
+      return false;
+    });
+
+    vi.spyOn(fs, 'statSync').mockReturnValue({
+      isDirectory: () => true,
+    } as any);
+
+    vi.spyOn(fs, 'readFileSync').mockReturnValue('');
+    vi.spyOn(fs, 'mkdirSync').mockReturnValue(undefined);
+    const writeSpy = vi.spyOn(fs, 'writeFileSync').mockReturnValue(undefined);
+
+    // Test tavily
+    await handleConfigCommand(['set', 'tavily', 'tvly-key-1234567890'], mockState);
+    expect(writeSpy).toHaveBeenLastCalledWith(envLocalPath, 'TAVILY_API_KEY=tvly-key-1234567890\n');
+
+    // Test context7
+    await handleConfigCommand(['set', 'context7', 'c7-key-1234567890'], mockState);
+    expect(writeSpy).toHaveBeenLastCalledWith(envLocalPath, 'CONTEXT7_API_KEY=c7-key-1234567890\n');
+
+    // Test braintrust
+    await handleConfigCommand(['set', 'braintrust', 'bt-key-1234567890'], mockState);
+    expect(writeSpy).toHaveBeenLastCalledWith(envLocalPath, 'BRAINTRUST_API_KEY=bt-key-1234567890\n');
+  });
+});

package/src/commands/config.ts

@@ -10,6 +10,7 @@ import { logger } from '../utils/logger.js';
 import { simpson } from '../utils/colors.js';
 import type { SessionState } from '../repl/session-state.js';
 import { getAvailableProvider, AVAILABLE_MODELS } from '../ai/providers.js';
+import { writeKeysToEnvFile } from '../utils/env.js';
 
 /**
  * Supported services for API key configuration
@@ -40,27 +41,17 @@ function isServiceConfigured(service: ConfigurableService): boolean {
 }
 
 /**
- * Save an API key to .env.local file
+ * Save an API key to .ralph/.env.local file
  */
 function saveKeyToEnvLocal(projectRoot: string, envVar: string, value: string): void {
-  const envLocalPath = path.join(projectRoot, '.env.local');
-  let envContent = '';
-
-  // Read existing content if file exists
-  if (fs.existsSync(envLocalPath)) {
-    envContent = fs.readFileSync(envLocalPath, 'utf-8');
-  }
-
-  const keyRegex = new RegExp(`^${envVar}=.*$`, 'm');
-  if (keyRegex.test(envContent)) {
-    // Replace existing key
-    envContent = envContent.replace(keyRegex, `${envVar}=${value}`);
-  } else {
-    // Append new key
-    envContent = envContent.trimEnd() + (envContent ? '\n' : '') + `${envVar}=${value}\n`;
+  // Check that .ralph/ exists (project is initialized)
+  const ralphDir = path.join(projectRoot, '.ralph');
+  if (!fs.existsSync(ralphDir) || !fs.statSync(ralphDir).isDirectory()) {
+    throw new Error('This project is not initialized. Run \'ralph init\' to set up .ralph/ before using \'ralph config set\'.');
   }
 
-  fs.writeFileSync(envLocalPath, envContent);
+  const envLocalPath = path.join(ralphDir, '.env.local');
+  writeKeysToEnvFile(envLocalPath, { [envVar]: value });
 }
 
 /**
@@ -160,7 +151,7 @@ export async function handleConfigCommand(
     // Also set in current process environment
     process.env[envVar] = apiKey;
 
-    logger.success(`${envVar} saved to .env.local`);
+    logger.success(`${envVar} saved to .ralph/.env.local`);
     console.log(pc.dim('Restart Wiggum to apply changes to tool availability.'));
     console.log('');
   } catch (error) {

package/src/context/convert.test.ts

@@ -0,0 +1,129 @@
+// src/context/convert.test.ts
+import { describe, it, expect } from 'vitest';
+import {
+  toPersistedScanResult,
+  toPersistedAIAnalysis,
+  toScanResultFromPersisted,
+} from './convert.js';
+import type { ScanResult } from '../scanner/types.js';
+import type { AIAnalysisResult } from '../ai/enhancer.js';
+
+describe('context/convert', () => {
+  describe('toPersistedScanResult', () => {
+    it('maps DetectedStack fields to flat persisted format', () => {
+      const scanResult: ScanResult = {
+        projectRoot: '/tmp/test',
+        scanTime: 100,
+        stack: {
+          framework: { name: 'Next.js', version: '14.0.0', variant: 'app-router', confidence: 95, evidence: [] },
+          packageManager: { name: 'pnpm', confidence: 90, evidence: [] },
+          testing: {
+            unit: { name: 'Vitest', confidence: 85, evidence: [] },
+            e2e: { name: 'Playwright', confidence: 80, evidence: [] },
+          },
+          styling: { name: 'Tailwind CSS', confidence: 90, evidence: [] },
+          database: { name: 'Supabase', confidence: 75, evidence: [] },
+          orm: { name: 'Prisma', confidence: 70, evidence: [] },
+          auth: { name: 'NextAuth', confidence: 65, evidence: [] },
+        },
+      };
+
+      const result = toPersistedScanResult(scanResult);
+
+      expect(result.framework).toBe('Next.js');
+      expect(result.frameworkVersion).toBe('14.0.0');
+      expect(result.frameworkVariant).toBe('app-router');
+      expect(result.packageManager).toBe('pnpm');
+      expect(result.testing?.unit).toBe('Vitest');
+      expect(result.testing?.e2e).toBe('Playwright');
+      expect(result.styling).toBe('Tailwind CSS');
+      expect(result.database).toBe('Supabase');
+      expect(result.orm).toBe('Prisma');
+      expect(result.auth).toBe('NextAuth');
+    });
+
+    it('handles missing optional fields gracefully', () => {
+      const scanResult: ScanResult = {
+        projectRoot: '/tmp/test',
+        scanTime: 50,
+        stack: {},
+      };
+
+      const result = toPersistedScanResult(scanResult);
+
+      expect(result.framework).toBeUndefined();
+      expect(result.packageManager).toBeUndefined();
+      expect(result.testing?.unit).toBeNull();
+      expect(result.testing?.e2e).toBeNull();
+    });
+  });
+
+  describe('toPersistedAIAnalysis', () => {
+    it('maps AIAnalysisResult to persisted format', () => {
+      const analysis: AIAnalysisResult = {
+        projectContext: {
+          entryPoints: ['src/index.ts'],
+          keyDirectories: { 'src/api': 'API routes' },
+          namingConventions: 'camelCase',
+        },
+        commands: { test: 'npm test', build: 'npm run build' },
+        implementationGuidelines: ['Use TypeScript strict mode'],
+        technologyPractices: {
+          projectType: 'Web App',
+          practices: ['SSR first'],
+          antiPatterns: ['No inline styles'],
+        },
+      };
+
+      const result = toPersistedAIAnalysis(analysis);
+
+      expect(result.projectContext?.entryPoints).toEqual(['src/index.ts']);
+      expect(result.projectContext?.keyDirectories).toEqual({ 'src/api': 'API routes' });
+      expect(result.commands?.test).toBe('npm test');
+      expect(result.implementationGuidelines).toEqual(['Use TypeScript strict mode']);
+      expect(result.technologyPractices?.projectType).toBe('Web App');
+    });
+
+    it('returns empty object for undefined analysis', () => {
+      const result = toPersistedAIAnalysis(undefined);
+      expect(result).toEqual({});
+    });
+  });
+
+  describe('toScanResultFromPersisted', () => {
+    it('rehydrates minimal ScanResult for codebase summary', () => {
+      const persisted = {
+        framework: 'Next.js',
+        frameworkVersion: '14.0.0',
+        frameworkVariant: 'app-router',
+        packageManager: 'pnpm',
+        testing: { unit: 'Vitest', e2e: 'Playwright' },
+        styling: 'Tailwind CSS',
+        database: 'Supabase',
+        orm: 'Prisma',
+        auth: 'NextAuth',
+      };
+
+      const scan = toScanResultFromPersisted(persisted, '/tmp/project');
+
+      expect(scan.projectRoot).toBe('/tmp/project');
+      expect(scan.stack.framework?.name).toBe('Next.js');
+      expect(scan.stack.framework?.version).toBe('14.0.0');
+      expect(scan.stack.framework?.variant).toBe('app-router');
+      expect(scan.stack.packageManager?.name).toBe('pnpm');
+      expect(scan.stack.testing?.unit?.name).toBe('Vitest');
+      expect(scan.stack.testing?.e2e?.name).toBe('Playwright');
+      expect(scan.stack.styling?.name).toBe('Tailwind CSS');
+      expect(scan.stack.database?.name).toBe('Supabase');
+      expect(scan.stack.orm?.name).toBe('Prisma');
+      expect(scan.stack.auth?.name).toBe('NextAuth');
+    });
+
+    it('handles empty persisted fields without crashing', () => {
+      const scan = toScanResultFromPersisted({}, '/tmp/project');
+      expect(scan.projectRoot).toBe('/tmp/project');
+      expect(scan.stack.framework).toBeUndefined();
+      expect(scan.stack.testing).toBeUndefined();
+    });
+  });
+});