@codeyam/codeyam-cli 0.1.0-staging.e38f7bd → 0.1.0-staging.fef152f

package/analyzer-template/project/runAnalysis.ts

@@ -215,6 +215,11 @@ export default async function runAnalysis({
       entityShas,
       branchName: branch?.name,
     });
+
+    // Propagate the fallback branch to branchCommit so downstream code can use it
+    if (branchCommit && branch) {
+      branchCommit.branch = branch;
+    }
   }
 
   // After this block, 'commit' is the union of a regular or baseline commit
@@ -308,6 +313,10 @@ export default async function runAnalysis({
   // Route to appropriate analyzer
   try {
     if (runReadyToBeCapturedPath) {
+      // Signal that analysis can produce captures immediately since analyses are already ready.
+      // This is needed for recapture to work - orchestration waits for the 'analysisProducing' event.
+      controller?.setAnalysisProducingPhase();
+
       return await analyzeReadyToBeCaptured({
         project,
         projectAnalyzer,
@@ -330,6 +339,7 @@ export default async function runAnalysis({
         desiredAnalyses,
         force,
         fileStore,
+        onAnalysisProducing: () => controller?.setAnalysisProducingPhase(),
       });
     }
 
@@ -350,6 +360,7 @@ export default async function runAnalysis({
       backgroundJob,
       desiredAnalyses,
       fileStore,
+      onAnalysisProducing: () => controller?.setAnalysisProducingPhase(),
     });
   } catch (e) {
     awsLog('CodeYam Error: Analysis failed', {

package/analyzer-template/project/runMultiScenarioServer.ts

@@ -302,14 +302,14 @@ export async function runMultiScenarioServer({
             message: message.slice(0, 1000),
           });
 
-          // Save error to database
-          await recordErrorMessageForScenario(analysis, currentScenario, {
-            message: messageToSave,
-          } as Error);
-
-          // Only signal scenario failed for RELEVANT crash errors
-          // Non-crash errors (like SSR warnings) should be recorded but not stop capture
+          // Only save error and signal scenario failed for RELEVANT crash errors
+          // Non-crash errors (like SSR warnings) should be logged but not stop capture
+          // or mark the scenario as finished (which would prevent screenshot capture)
           if (relevantError) {
+            // Save crash error to database (sets finishedAt on scenario)
+            await recordErrorMessageForScenario(analysis, currentScenario, {
+              message: messageToSave,
+            } as Error);
             awsLog(
               'CodeYam SERVER DEBUG: Calling handleServerError for crash error',
               {
@@ -320,8 +320,9 @@ export async function runMultiScenarioServer({
             );
             iterator.handleServerError(currentScenario.name);
           } else {
+            // Non-crash errors are logged but don't affect scenario status
             awsLog(
-              'CodeYam SERVER DEBUG: Non-crash error recorded, NOT stopping scenario',
+              'CodeYam SERVER DEBUG: Non-crash error logged, NOT stopping scenario',
               {
                 analysisId: analysis.id,
                 scenarioName: currentScenario.name,
@@ -501,13 +502,13 @@ export async function runMultiScenarioServer({
 
       if (!iterator.hasScenarioFailed(scenario.name)) {
         completedScenarios.push(scenario.name);
-        awsLog('CodeYam SERVER DEBUG: Scenario marked as completed', {
+        awsLog('CodeYam: Scenario marked as completed', {
           analysisId: analysis.id,
           scenarioName: scenario.name,
           scenarioId: scenario.id,
         });
       } else {
-        awsLog('CodeYam SERVER DEBUG: Scenario marked as FAILED', {
+        awsLog('CodeYam: Scenario marked as FAILED', {
           analysisId: analysis.id,
           scenarioName: scenario.name,
           scenarioId: scenario.id,

package/analyzer-template/project/serverOnlyModules.ts

@@ -0,0 +1,413 @@
+import ts from 'typescript';
+
+/**
+ * Configuration for modules that require client-side mocking.
+ *
+ * These are Node.js built-ins, server-only npm packages, or framework-specific
+ * server APIs that cannot run in the browser and need mock implementations.
+ */
+
+export interface ServerOnlyModuleMock {
+  /** The module specifier pattern (exact match or regex) */
+  module: string | RegExp;
+  /** Description of why this module needs mocking */
+  reason: string;
+  /** Category for grouping */
+  category: 'node-builtin' | 'npm-package' | 'framework';
+  /**
+   * Mock code generator function.
+   * @param importNames - The names being imported (for named imports)
+   * @param defaultImportName - The name used for default import (if any)
+   * @returns The mock code to replace the import with
+   */
+  getMockCode: (importNames: string[], defaultImportName?: string) => string;
+}
+
+/**
+ * Known server-only modules that need client-side mocking.
+ * This list can be extended by users via project configuration.
+ */
+export const SERVER_ONLY_MODULES: ServerOnlyModuleMock[] = [
+  // Node.js built-ins
+  {
+    module: 'node:crypto',
+    reason: 'Node.js crypto module is not available in browser',
+    category: 'node-builtin',
+    getMockCode: (importNames, defaultImportName) => {
+      if (defaultImportName) {
+        return `// Mock for node:crypto (Node.js built-in, not available in browser)
+const ${defaultImportName} = {
+  createHash: (algorithm: string) => ({
+    update: (data: string) => ({
+      digest: (encoding: string) => 'mock-hash-' + data.substring(0, 8),
+    }),
+  }),
+  randomBytes: (size: number) => new Uint8Array(size),
+  randomUUID: () => 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+    const r = Math.random() * 16 | 0;
+    return (c === 'x' ? r : (r & 0x3 | 0x8)).toString(16);
+  }),
+};
+`;
+      }
+      // Named imports
+      let code =
+        '// Mock for node:crypto (Node.js built-in, not available in browser)\n';
+      for (const name of importNames) {
+        const [originalName, aliasName] = name
+          .split(/\s+as\s+/)
+          .map((s) => s.trim());
+        const finalName = aliasName || originalName;
+        if (originalName === 'createHash') {
+          code += `const ${finalName} = (algorithm: string) => ({
+  update: (data: string) => ({
+    digest: (encoding: string) => 'mock-hash-' + data.substring(0, 8),
+  }),
+});
+`;
+        } else if (originalName === 'randomBytes') {
+          code += `const ${finalName} = (size: number) => new Uint8Array(size);
+`;
+        } else if (originalName === 'randomUUID') {
+          code += `const ${finalName} = () => 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+  const r = Math.random() * 16 | 0;
+  return (c === 'x' ? r : (r & 0x3 | 0x8)).toString(16);
+});
+`;
+        } else {
+          code += `const ${finalName} = () => { throw new Error('${originalName} is not available in browser'); };
+`;
+        }
+      }
+      return code;
+    },
+  },
+
+  // npm packages that require Node.js
+  {
+    module: 'https-proxy-agent',
+    reason: 'Requires Node.js net/tls modules',
+    category: 'npm-package',
+    getMockCode: (importNames) => {
+      return `// Mock for https-proxy-agent (requires Node.js net/tls modules)
+class HttpsProxyAgent {
+  constructor() {}
+}
+`;
+    },
+  },
+  {
+    module: 'node-fetch',
+    reason: 'Requires Node.js http/https modules',
+    category: 'npm-package',
+    getMockCode: (importNames, defaultImportName) => {
+      if (defaultImportName) {
+        return `// Mock for node-fetch (requires Node.js http/https modules)
+const ${defaultImportName} = async (url: string, options?: any) => ({
+  ok: true,
+  status: 200,
+  json: async () => ({}),
+  text: async () => '',
+  headers: new Headers(),
+});
+`;
+      }
+      // Named imports - browser has native Response, Headers, etc.
+      return '// node-fetch named imports removed - using browser natives\n';
+    },
+  },
+
+  // Framework-specific server APIs
+  {
+    module: 'next/headers',
+    reason: 'Next.js server-only API for reading request headers',
+    category: 'framework',
+    getMockCode: () => {
+      return `// Mock for next/headers (server-only in Next.js)
+const headers = async () => ({
+  get: (name: string) => null,
+  has: (name: string) => false,
+  entries: () => [][Symbol.iterator](),
+  keys: () => [][Symbol.iterator](),
+  values: () => [][Symbol.iterator](),
+  forEach: () => {},
+});
+const cookies = async () => ({
+  get: (name: string) => undefined,
+  getAll: () => [],
+  has: (name: string) => false,
+  set: () => {},
+  delete: () => {},
+});
+`;
+    },
+  },
+];
+
+/**
+ * Find a server-only module configuration by module specifier.
+ */
+export function findServerOnlyModule(
+  moduleSpecifier: string,
+): ServerOnlyModuleMock | undefined {
+  return SERVER_ONLY_MODULES.find((config) => {
+    if (typeof config.module === 'string') {
+      return config.module === moduleSpecifier;
+    }
+    return config.module.test(moduleSpecifier);
+  });
+}
+
+/**
+ * Check if a module specifier matches any known server-only module.
+ */
+export function isServerOnlyModule(moduleSpecifier: string): boolean {
+  return findServerOnlyModule(moduleSpecifier) !== undefined;
+}
+
+/**
+ * Parse an import statement to extract module specifier and import names.
+ */
+export function parseImportStatement(importStatement: string): {
+  moduleSpecifier: string;
+  importNames: string[];
+  defaultImportName?: string;
+} | null {
+  // Match: import { a, b } from "module"
+  const namedMatch = importStatement.match(
+    /import\s+\{([^}]+)\}\s+from\s+["']([^"']+)["']/,
+  );
+  if (namedMatch) {
+    const names = namedMatch[1]
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean);
+    return {
+      moduleSpecifier: namedMatch[2],
+      importNames: names,
+    };
+  }
+
+  // Match: import foo from "module" or import * as foo from "module"
+  const defaultMatch = importStatement.match(
+    /import\s+(?:\*\s+as\s+)?(\w+)\s+from\s+["']([^"']+)["']/,
+  );
+  if (defaultMatch) {
+    return {
+      moduleSpecifier: defaultMatch[2],
+      importNames: [],
+      defaultImportName: defaultMatch[1],
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Apply server-only module mocks to file content.
+ * Replaces imports from known server-only modules with mock implementations.
+ */
+export function applyServerOnlyMocks(fileContent: string): string {
+  // Always use AST parsing - regex with nested quantifiers can cause catastrophic
+  // backtracking that hangs on a single .exec() call (before iteration limits kick in)
+  return applyServerOnlyMocksAst(fileContent);
+}
+
+/**
+ * Check if a file exports an "env" variable that's derived from a node module import.
+ * This is a generic pattern for env configuration packages (like @t3-oss/env-*, envalid, etc.)
+ * that create server-only environment objects.
+ *
+ * Pattern detected:
+ *   import { someFunc } from "some-package";
+ *   export const env = someFunc({...});
+ *
+ * Returns the name of the imported function if detected, null otherwise.
+ */
+function detectEnvStoreFromNodeModule(sourceFile: ts.SourceFile): {
+  importedFunctionName: string;
+  modulePath: string;
+} | null {
+  // First, collect all imported function names from node modules
+  const nodeModuleImports = new Map<string, string>(); // functionName -> modulePath
+
+  for (const statement of sourceFile.statements) {
+    if (!ts.isImportDeclaration(statement)) continue;
+
+    const moduleSpecifier = statement.moduleSpecifier;
+    if (!ts.isStringLiteral(moduleSpecifier)) continue;
+
+    const modulePath = moduleSpecifier.text;
+    // Skip relative imports - only look at node modules
+    if (modulePath.startsWith('.') || modulePath.startsWith('/')) continue;
+
+    if (
+      statement.importClause?.namedBindings &&
+      ts.isNamedImports(statement.importClause.namedBindings)
+    ) {
+      for (const element of statement.importClause.namedBindings.elements) {
+        nodeModuleImports.set(element.name.text, modulePath);
+      }
+    }
+    if (statement.importClause?.name) {
+      nodeModuleImports.set(statement.importClause.name.text, modulePath);
+    }
+  }
+
+  // Now look for: export const env = importedFunc(...)
+  for (const statement of sourceFile.statements) {
+    if (!ts.isVariableStatement(statement)) continue;
+
+    // Check if it's exported
+    const isExported = statement.modifiers?.some(
+      (m) => m.kind === ts.SyntaxKind.ExportKeyword,
+    );
+    if (!isExported) continue;
+
+    for (const decl of statement.declarationList.declarations) {
+      // Check if variable is named "env"
+      if (!ts.isIdentifier(decl.name) || decl.name.text !== 'env') continue;
+
+      // Check if initializer is a call expression
+      if (!decl.initializer || !ts.isCallExpression(decl.initializer)) continue;
+
+      // Get the function being called
+      const callExpr = decl.initializer.expression;
+      let funcName: string | null = null;
+
+      if (ts.isIdentifier(callExpr)) {
+        funcName = callExpr.text;
+      } else if (
+        ts.isPropertyAccessExpression(callExpr) &&
+        ts.isIdentifier(callExpr.name)
+      ) {
+        funcName = callExpr.name.text;
+      }
+
+      if (funcName && nodeModuleImports.has(funcName)) {
+        return {
+          importedFunctionName: funcName,
+          modulePath: nodeModuleImports.get(funcName)!,
+        };
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Generate mock code for env store patterns.
+ * Replaces the imported function with one that returns a proxy.
+ */
+function generateEnvStoreMock(functionName: string): string {
+  return `// Mock for env store function (server-only env vars)
+const ${functionName} = (config: any) => {
+  // Return a proxy that returns undefined for any property access
+  // This allows the code to run on the client without throwing
+  return new Proxy({} as any, {
+    get: (target, prop) => {
+      if (prop === 'then' || prop === Symbol.toStringTag) return undefined;
+      return undefined;
+    },
+  });
+};
+`;
+}
+
+/**
+ * AST-based implementation of applyServerOnlyMocks for large files.
+ * Uses TypeScript parser instead of regex to avoid catastrophic backtracking.
+ */
+function applyServerOnlyMocksAst(fileContent: string): string {
+  try {
+    const sourceFile = ts.createSourceFile(
+      'temp.ts',
+      fileContent,
+      ts.ScriptTarget.Latest,
+      true,
+    );
+
+    const replacements: { start: number; end: number; replacement: string }[] =
+      [];
+
+    // Check if this file exports an "env" variable from a node module function call
+    // This is a generic pattern for env configuration packages
+    const envStoreInfo = detectEnvStoreFromNodeModule(sourceFile);
+
+    for (const statement of sourceFile.statements) {
+      if (!ts.isImportDeclaration(statement)) continue;
+
+      const moduleSpecifier = statement.moduleSpecifier;
+      if (!ts.isStringLiteral(moduleSpecifier)) continue;
+
+      const modulePath = moduleSpecifier.text;
+
+      // Extract import names
+      const importNames: string[] = [];
+      let defaultImportName: string | undefined;
+
+      if (statement.importClause) {
+        // Default import
+        if (statement.importClause.name) {
+          defaultImportName = statement.importClause.name.text;
+        }
+
+        // Named imports
+        if (statement.importClause.namedBindings) {
+          if (ts.isNamedImports(statement.importClause.namedBindings)) {
+            for (const element of statement.importClause.namedBindings
+              .elements) {
+              importNames.push(element.name.text);
+            }
+          } else if (
+            ts.isNamespaceImport(statement.importClause.namedBindings)
+          ) {
+            // Namespace import like: import * as foo from 'module'
+            importNames.push(statement.importClause.namedBindings.name.text);
+          }
+        }
+      }
+
+      // Check if this import provides the function used to create the env store
+      if (
+        envStoreInfo &&
+        modulePath === envStoreInfo.modulePath &&
+        importNames.includes(envStoreInfo.importedFunctionName)
+      ) {
+        const mockCode = generateEnvStoreMock(
+          envStoreInfo.importedFunctionName,
+        );
+        replacements.push({
+          start: statement.getStart(sourceFile),
+          end: statement.getEnd(),
+          replacement: mockCode,
+        });
+        continue;
+      }
+
+      // Check for known server-only modules (from explicit list)
+      const config = findServerOnlyModule(modulePath);
+      if (!config) continue;
+
+      const mockCode = config.getMockCode(importNames, defaultImportName);
+      replacements.push({
+        start: statement.getStart(sourceFile),
+        end: statement.getEnd(),
+        replacement: mockCode,
+      });
+    }
+
+    // Apply replacements in reverse order to preserve positions
+    let result = fileContent;
+    replacements.sort((a, b) => b.start - a.start);
+    for (const { start, end, replacement } of replacements) {
+      result = result.slice(0, start) + replacement + result.slice(end);
+    }
+
+    return result;
+  } catch (error) {
+    console.warn('[applyServerOnlyMocksAst] Failed to parse file:', error);
+    return fileContent; // Return original content on error
+  }
+}

package/analyzer-template/project/start.ts

@@ -1,4 +1,5 @@
 import 'dotenv/config';
+import { once } from 'events';
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
 import {
@@ -16,14 +17,15 @@ import { startScenarioCapture } from './startScenarioCapture';
 import { createController } from './controller/startController';
 import { awsLog, awsLogDebugLevel } from '~codeyam/utils';
 import * as v8 from 'v8';
-import { initializeAIServiceMode } from '~codeyam/ai';
+import * as os from 'os';
+import { initializeAIServiceMode, destroyWorkerPool } from '~codeyam/ai';
 import runAnalysis, { EnvConfig, SharedContext } from './runAnalysis';
 import {
   loadOrCreateCommit,
   syncHeadBranches,
   syncPrimaryBranch,
 } from '~codeyam/github';
-import { installSignalHandlers } from '../process';
+import { installSignalHandlers } from '~codeyam/process';
 
 // Set process title for Activity Monitor visibility
 if (process.env.CODEYAM_PROCESS_NAME) {
@@ -118,28 +120,31 @@ async function main({
     // and attempted to access project/commit/branch data before it was loaded.
     const sharedContext = await loadSharedContext(envConfig);
 
-    // Heap monitoring: pulse every 1s, log every 30s when normal, warn every 1s when high
+    // Memory monitoring: tracks both V8 heap and RSS (which includes worker threads)
+    const containerMemoryMB = process.env.ECS_CONTAINER_MEMORY_MB
+      ? parseInt(process.env.ECS_CONTAINER_MEMORY_MB, 10)
+      : Math.round(os.totalmem() / 1024 / 1024);
     let lastLogTime = 0;
     setInterval(() => {
       const mem = process.memoryUsage();
       const heap = v8.getHeapStatistics();
-      const usagePercent = (mem.heapUsed / heap.heap_size_limit) * 100;
+      const heapMB = Math.round(mem.heapUsed / 1024 / 1024);
+      const rssMB = Math.round(mem.rss / 1024 / 1024);
+      const heapLimitMB = Math.round(heap.heap_size_limit / 1024 / 1024);
+      const rssPercent = (rssMB / containerMemoryMB) * 100;
       const now = Date.now();
 
-      if (usagePercent >= 80) {
-        // High usage: warn every second
+      if (rssPercent >= 80) {
         console.warn(
-          `CodeYam Heap Warning: ${Math.round(mem.heapUsed / 1024 / 1024)}MB used / ${Math.round(heap.heap_size_limit / 1024 / 1024)}MB limit (${Math.round(usagePercent)}%) ⚠️ HIGH USAGE`,
+          `CodeYam Memory Warning: RSS ${rssMB}MB/${containerMemoryMB}MB (${Math.round(rssPercent)}%), heap ${heapMB}MB/${heapLimitMB}MB ⚠️ HIGH`,
         );
-      } else if (usagePercent >= 50 && now - lastLogTime >= 5000) {
-        // Elevated usage: log every 5 seconds
+      } else if (rssPercent >= 50 && now - lastLogTime >= 5000) {
         console.log(
-          `CodeYam Heap Notice: ${Math.round(mem.heapUsed / 1024 / 1024)}MB used / ${Math.round(heap.heap_size_limit / 1024 / 1024)}MB limit (${Math.round(usagePercent)}%) ⚠️ Elevated`,
+          `CodeYam Memory Notice: RSS ${rssMB}MB/${containerMemoryMB}MB (${Math.round(rssPercent)}%), heap ${heapMB}MB/${heapLimitMB}MB ⚠️ Elevated`,
         );
       } else if (now - lastLogTime >= 30000) {
-        // Normal usage: log every 30 seconds
         console.log(
-          `CodeYam Heap Stats: ${Math.round(mem.heapUsed / 1024 / 1024)}MB used / ${Math.round(heap.heap_size_limit / 1024 / 1024)}MB limit (${Math.round(usagePercent)}%) 📊 OK`,
+          `CodeYam Memory Stats: RSS ${rssMB}MB/${containerMemoryMB}MB (${Math.round(rssPercent)}%), heap ${heapMB}MB/${heapLimitMB}MB 📊 OK`,
         );
       }
 
@@ -186,6 +191,11 @@ async function main({
               analyzerPid: undefined,
               capturePid: process.pid,
             },
+            updateCallback(metadata) {
+              if (metadata.currentRun?.captureCompletedAt) {
+                metadata.currentRun.completedAt = new Date().toISOString();
+              }
+            },
           }).catch((error) => {
             awsLog(`Warning: Failed to update commit metadata: ${error}`);
           });
@@ -207,7 +217,20 @@ async function main({
         while (!controller?.hasCompletedRepoCheckout()) {
           await new Promise((resolve) => setTimeout(resolve, 1000));
         }
-        awsLog('CodeYam: Repo checkout complete, starting orchestration...');
+        awsLog('CodeYam: Repo checkout complete.');
+
+        // Wait for analysis to enter producing phase (after prepareDataStructures)
+        // This prevents the 20-minute orchestration timeout from triggering before
+        // any analyses become ready to capture
+        awsLog('CodeYam: Waiting for analysis to start producing...');
+        if (!controller.hasStartedProducing()) {
+          await once(controller, 'analysisProducing');
+        }
+        awsLog('CodeYam: Analysis producing, starting orchestration...');
+
+        // Worker pool is no longer needed after data structure prep phase.
+        // Freeing it reclaims ~2GB before capture workers ramp up.
+        await destroyWorkerPool();
 
         // Create task runner based on orchestration mode
         let taskRunner;
@@ -219,6 +242,17 @@ async function main({
             framework: framework,
             packageManager: packageManager,
           });
+
+          const captureCommit =
+            sharedContext.commit ?? sharedContext.branchCommit;
+          if (captureCommit) {
+            await updateCommitMetadata({
+              commitId: captureCommit.id,
+              runStatusUpdate: {
+                captureTaskArns: taskRunner.getTaskArns(),
+              },
+            });
+          }
         } else if (orchestrateCapture === 'local-sequential') {
           taskRunner = await SequentialCaptureTaskRunner.create(
             {
@@ -260,18 +294,27 @@ async function main({
             }
           },
           project: sharedContext.project,
-          // In local-sequential mode, don't filter by commit since each analysis run
-          // creates a new fake commit. We want to capture all ready analyses for the project.
+          // In local-sequential mode, don't filter by commit (full=true handles that).
+          // For AWS mode, filter by the specific commit being analyzed.
           commit:
             orchestrateCapture === 'local-sequential'
               ? null
               : (sharedContext.commit ?? sharedContext.branchCommit),
-          analysisIds: envConfig.analysisIds,
-          entityShas: envConfig.entityShas,
-          // In local-sequential mode, use full=true to query all ready analyses for the project
-          // since we don't have specific analysisIds/entityShas and commit is null.
+          // In local-sequential mode, don't filter by analysisIds/entityShas since
+          // analysis may create new entities with different SHAs than the input filters.
+          // We want to capture all ready analyses for the project.
+          analysisIds:
+            orchestrateCapture === 'local-sequential'
+              ? undefined
+              : envConfig.analysisIds,
+          entityShas:
+            orchestrateCapture === 'local-sequential'
+              ? undefined
+              : envConfig.entityShas,
           full: orchestrateCapture === 'local-sequential',
           taskRunner,
+          // Always track capture progress on the commit, even when not filtering by it.
+          metadataCommit: sharedContext.commit ?? sharedContext.branchCommit,
         });
         awsLog('CodeYam Capture: runCaptureOrchestration() completed');
       };
@@ -433,6 +476,16 @@ async function main({
         `CodeYam: Exiting start.js process with ${hadError ? 'ERROR' : 'SUCCESS'}`,
       );
       process.exit(hadError ? 1 : 0);
+    } else if (process.env.CAPTURE_ONLY === 'true') {
+      awsLog(
+        'CodeYam: CAPTURE_ONLY mode - keeping files and exiting cleanly',
+        `Preserved ${generatedFiles.length} files`,
+      );
+      // Don't cleanup files in capture-only mode to preserve manual edits
+      awsLog(
+        `CodeYam: Exiting start.js process with ${hadError ? 'ERROR' : 'SUCCESS'}`,
+      );
+      process.exit(hadError ? 1 : 0);
     } else {
       awsLog(`CodeYam: Removing ${generatedFiles.length} generated files...`);
       removeScenario(generatedFiles);