@codeyam/codeyam-cli 0.1.0-staging.1 → 0.1.0-staging.1669d45

package/analyzer-template/project/startScenarioCapture.ts

@@ -13,7 +13,7 @@ import {
 import removeScenario from './removeScenario';
 import { recordErrorMessageForScenario } from './utils/errorHandling';
 import { Controller } from './controller/startController';
-import { loadFile, updateFreshAnalysisStatus } from '~codeyam/supabase';
+import { loadFile, updateFreshAnalysisStatus } from '~codeyam/database';
 import {
   awsLog,
   awsLogDebugLevel,
@@ -24,6 +24,11 @@ import {
 } from '~codeyam/utils';
 import getAppPath from './getAppPath';
 import { restoreAllBackups, restoreFromBackup } from './backupFiles';
+import {
+  readTrackingFile,
+  writeTrackingFile,
+  clearTrackingFile,
+} from './trackGeneratedFiles';
 import captureLibraryFunctionDirect from './captureLibraryFunctionDirect';
 import {
   getFrameworkForComponent,
@@ -31,6 +36,7 @@ import {
 } from './utils/webappMapping';
 import mergeEnvVarsIntoStartCommand from './utils/mergeEnvVarsIntoStartCommand';
 import { LazyFileStore } from './LazyFileStore';
+import { DEFAULT_SCENARIO_NAME } from '../common/constants';
 
 export interface StartScenarioCaptureArgs {
   readyToBeCaptured: Analysis[];
@@ -79,6 +85,29 @@ export async function startScenarioCapture({
     restoreAllBackups(fullPath);
   }
 
+  // Clean up any leftover generated files from previous debug sessions
+  // Skip in CAPTURE_ONLY mode - we want to preserve the files that were edited
+  const previouslyTracked = readTrackingFile();
+  if (previouslyTracked && process.env.CAPTURE_ONLY !== 'true') {
+    awsLog('CodeYam: Cleaning up files from previous session', {
+      generatedCount: previouslyTracked.generatedFiles.length,
+      backupCount: previouslyTracked.backupFiles.length,
+      timestamp: previouslyTracked.timestamp,
+    });
+    removeScenario(previouslyTracked.generatedFiles);
+    for (const backupPath of previouslyTracked.backupFiles) {
+      restoreFromBackup(backupPath);
+    }
+    clearTrackingFile();
+  } else if (previouslyTracked && process.env.CAPTURE_ONLY === 'true') {
+    awsLog(
+      'CodeYam: CAPTURE_ONLY mode - preserving files from previous session',
+      {
+        generatedCount: previouslyTracked.generatedFiles.length,
+      },
+    );
+  }
+
   const sortedReadyToBeCaptured = readyToBeCaptured.sort((a, b) => {
     if (a.indirect !== b.indirect) {
       return a.indirect ? 1 : -1;
@@ -198,6 +227,11 @@ export async function startScenarioCapture({
     }
 
     const sortedScenarios = (analysis.scenarios ?? []).sort((a, b) => {
+      // Default Scenario always goes first
+      if (a.name === DEFAULT_SCENARIO_NAME) return -1;
+      if (b.name === DEFAULT_SCENARIO_NAME) return 1;
+
+      // Then prioritize new or revised scenarios
       const newOrRevisedA =
         !a.previousVersionId || a.metadata?.revisedFromPreviousVersion;
       const newOrRevisedB =
@@ -332,7 +366,12 @@ export async function startScenarioCapture({
     const mocksDir = `${appPath}/${CODEYAM_MOCKS_DIRNAME}/`;
 
     for (const scenario of sortedScenarios) {
-      if (scenarioIds && !scenarioIds.includes(scenario.id)) {
+      // Check both id and name since scenarioIds may contain either (recapture uses names)
+      if (
+        scenarioIds &&
+        !scenarioIds.includes(scenario.id) &&
+        !scenarioIds.includes(scenario.name)
+      ) {
         awsLog('CodeYam: Skipping scenario', {
           thisScenarioId: scenario.id,
           thisScenarioName: scenario.name,
@@ -359,6 +398,7 @@ export async function startScenarioCapture({
       if (
         !process.env['CODEYAM_LOCAL_PROJECT_PATH'] &&
         !scenarioIds?.includes(scenario.id) &&
+        !scenarioIds?.includes(scenario.name) &&
         !analysisIds?.includes(analysis.id) &&
         (scenarioStatus?.finishedAt ||
           scenarioStatus?.error ||
@@ -369,40 +409,50 @@ export async function startScenarioCapture({
 
       awsLogDebugLevel(1, `Preparing ${analysis.entityName}: ${scenario.name}`);
 
-      // Write scenario files upfront
-      const scenarioGeneratedFiles = await writeScenario({
-        analysis,
-        scenario,
-        context,
-        projectAnalyzer,
-        framework,
-        fileStore,
-      });
-
-      // For non-routes: write root.tsx now (all scenarios can share it)
-      // For routes: defer writeSimpleRoot to per-scenario execution (each needs different mocks)
-      // EXCEPTION: In PREP_ONLY mode (debug), routes also need root.tsx written here since we exit early
-      if (!isRoute || process.env.PREP_ONLY === 'true') {
-        const simpleRootResult = await writeSimpleRoot(
-          project,
-          framework,
+      // In CAPTURE_ONLY mode, skip file generation and use existing files
+      // This preserves manual fixes made during debugging
+      let scenarioGeneratedFiles: string[] = [];
+      if (process.env.CAPTURE_ONLY !== 'true') {
+        // Write scenario files upfront
+        scenarioGeneratedFiles = await writeScenario({
+          analysis,
           scenario,
-          analysis.filePath,
-          {
-            file: analysis.file,
-            entity: analysis.entity,
-            routeAnalysis: analysis,
-            mocksDir,
-            scenarioComponentPaths: scenarioGeneratedFiles,
-          },
-        );
-        if (simpleRootResult.filePath) {
-          if (simpleRootResult.backupPath) {
-            backupFiles.push(simpleRootResult.backupPath);
-          } else {
-            scenarioGeneratedFiles.push(simpleRootResult.filePath);
+          context,
+          projectAnalyzer,
+          framework,
+          fileStore,
+        });
+
+        // For non-routes: write root.tsx now (all scenarios can share it)
+        // For routes: defer writeSimpleRoot to per-scenario execution (each needs different mocks)
+        // EXCEPTION: In PREP_ONLY mode (debug), routes also need root.tsx written here since we exit early
+        if (!isRoute || process.env.PREP_ONLY === 'true') {
+          const simpleRootResult = await writeSimpleRoot(
+            project,
+            framework,
+            scenario,
+            analysis.filePath,
+            {
+              file: analysis.file,
+              entity: analysis.entity,
+              routeAnalysis: analysis,
+              mocksDir,
+              scenarioComponentPaths: scenarioGeneratedFiles,
+            },
+          );
+          if (simpleRootResult.filePath) {
+            if (simpleRootResult.backupPath) {
+              backupFiles.push(simpleRootResult.backupPath);
+            } else {
+              scenarioGeneratedFiles.push(simpleRootResult.filePath);
+            }
           }
         }
+      } else {
+        awsLogDebugLevel(
+          1,
+          `CAPTURE_ONLY mode: skipping file generation for ${scenario.name}`,
+        );
       }
 
       // Mark scenario as initializing
@@ -446,6 +496,9 @@ export async function startScenarioCapture({
         controller?.port,
       );
       allGeneratedFiles.push(codeyamPagePath);
+
+      // Persist file tracking for crash/debug recovery
+      writeTrackingFile(allGeneratedFiles, backupFiles);
     }
 
     // Skip if no scenarios to capture
@@ -565,6 +618,7 @@ export async function startScenarioCapture({
         for (const backupPath of backupsToRestore) {
           restoreFromBackup(backupPath);
         }
+        clearTrackingFile();
       }
     };
 
@@ -654,14 +708,22 @@ export async function startScenarioCapture({
         allGeneratedFiles,
       );
 
-      // Clean up all generated files
-      console.log(
-        'CodeYam: Removing all scenario files for analysis',
-        analysis.id,
-        analysis.entityName,
-      );
-      cleanupFiles(allGeneratedFiles, backupFiles);
-      backupFiles = [];
+      // Clean up all generated files (skip in CAPTURE_ONLY mode to preserve edits)
+      if (process.env.CAPTURE_ONLY !== 'true') {
+        console.log(
+          'CodeYam: Removing all scenario files for analysis',
+          analysis.id,
+          analysis.entityName,
+        );
+        cleanupFiles(allGeneratedFiles, backupFiles);
+        backupFiles = [];
+      } else {
+        console.log(
+          'CodeYam: CAPTURE_ONLY mode - preserving scenario files for analysis',
+          analysis.id,
+          analysis.entityName,
+        );
+      }
 
       forceStop = result.forceStop;
     }

package/analyzer-template/project/startServer.ts

@@ -1,25 +1,32 @@
 import getPort from 'get-port';
 import execAsync from '../common/execAsync';
-import { ProjectFramework, ServerCommand } from '~codeyam/types';
+import { ServerCommand } from '~codeyam/types';
 import { Socket } from 'net';
 import { awsLogDebugLevel } from '~codeyam/utils';
 
 export interface StartServerArgs {
-  startCommand?: ServerCommand;
-  packageManager: string;
-  exitAfterSuccessfulAppStart?: boolean;
+  startCommand: ServerCommand;
   onStart: (port: number) => Promise<void>;
   onError: (data: string) => Promise<void>;
-  framework: ProjectFramework;
   projectPort?: number;
 }
 
+/**
+ * Start the project's dev server.
+ *
+ * Requires a complete startCommand with $PORT placeholder in args.
+ * The startCommand should be fully specified in the project's webapp configuration,
+ * including any package manager invocation and framework-specific flags.
+ *
+ * Examples of valid startCommand configurations:
+ * - npm: { command: 'npm', args: ['run', 'dev', '--', '--port', '$PORT'] }
+ * - pnpm: { command: 'pnpm', args: ['dev', '--port', '$PORT'] }
+ * - monorepo: { command: 'sh', args: ['-c', 'cd subdir && pnpm dev --port $PORT'] }
+ */
 export async function startServer({
   startCommand,
-  packageManager,
   onStart,
   onError,
-  framework,
   projectPort,
 }: StartServerArgs) {
   const acceptableErrorsRegexes = [
@@ -27,7 +34,7 @@ export async function startServer({
     /favicon\.ico/,
     /DeprecationWarning/,
     /warn deprecated/,
-    /One of your dependencies, babel-preset-react-app, is importing the/, // This error is thrown in CRA and is not a problem. TODO: How to not throw for warnings
+    /One of your dependencies, babel-preset-react-app, is importing the/,
     /No route matches URL/,
     /Browserslist: caniuse-lite is outdated/,
     /npx update-browserslist-db@latest/,
@@ -37,8 +44,27 @@ export async function startServer({
   ];
 
   try {
-    // both 'undefined' and 0 triggers port auto-selection, which we do here as late as
-    // possible to mimimise the risk of race conditions & port conflicts downstream
+    // Validate startCommand
+    if (!startCommand?.command) {
+      throw new Error(
+        'startCommand.command is required. ' +
+          'Please configure a complete startCommand in the webapp configuration.',
+      );
+    }
+    if (!startCommand.args?.length) {
+      throw new Error(
+        'startCommand.args is required and must be non-empty. ' +
+          'Please configure startCommand.args with $PORT placeholder.',
+      );
+    }
+    if (!startCommand.args.some((arg) => arg.includes('$PORT'))) {
+      throw new Error(
+        'startCommand.args must include $PORT placeholder. ' +
+          'Example: ["run", "dev", "--", "--port", "$PORT"]',
+      );
+    }
+
+    // Port auto-selection (as late as possible to minimize race conditions)
     if (!projectPort) {
       projectPort = await getPort();
       console.log(`CodeYam: Auto-selected project port: ${projectPort}`);
@@ -68,7 +94,6 @@ export async function startServer({
 
         socket.connect(port, 'localhost');
 
-        // Don't leave socket hanging
         timer.current = setTimeout(() => {
           console.log(`CodeYam: checkPort: Timeout`);
           socket.destroy();
@@ -89,66 +114,22 @@ export async function startServer({
       }
     };
 
-    // figure out the right CLI invocation for starting the server
-    const command = startCommand?.command ?? packageManager;
-    let args = startCommand?.args;
-
-    if (args) {
-      // Custom startCommand provided - clone and process it
-      args = [...args];
-
-      // Replace any $PORT placeholders with the actual port
-      let hasPort = false;
-      for (let i = 0; i < args.length; i++) {
-        if (args[i].includes('$PORT')) {
-          args[i] = args[i].replace('$PORT', projectPort.toString());
-          hasPort = true;
-        } else if (args[i] === '--port' || args[i] === '-p') {
-          hasPort = true;
-        }
-      }
+    // Build command from startCommand (substituting $PORT)
+    const command = startCommand.command;
+    const args = startCommand.args.map((arg) =>
+      arg.replace(/\$PORT/g, projectPort.toString()),
+    );
 
-      // If no port argument exists, add it.
-      // Use -- separator for compatibility with Turbo-based projects.
-      if (!hasPort) {
-        if (framework === ProjectFramework.Remix) {
-          args.push('--', '--port', projectPort.toString(), '--strictPort');
-        } else {
-          args.push('--', '--port', projectPort.toString());
-        }
-      }
-    } else {
-      if (framework === ProjectFramework.CodeYam) {
-        args = ['start', projectPort.toString()];
-      } else {
-        // there's no guarantee that the logic below will work for all frameworks, and
-        // certainly no guarantee that it'll work on any one individual project... but
-        // it's a reasonable default, and we have `startCommand` for anything bespoke
-        //
-        // All package managers support -- to pass arguments to scripts.
-        // npm requires it, and Turbo-based projects (monorepos) also require it.
-        // Using -- universally is safe and ensures compatibility.
-        args = ['run', 'dev', '--', '--port', projectPort.toString()];
-        if (framework === ProjectFramework.Remix) {
-          args.push('--strictPort');
-        }
-      }
-    }
-    let env = startCommand?.env;
-    if (!env) {
-      env = {
-        LOCAL: 'local',
-        PORT: projectPort.toString(),
-      };
-      if (framework === ProjectFramework.CRA) {
-        env.BROWSER = 'none';
-      }
-    } else {
-      // Replace $PORT placeholders in env values
-      env = { ...env };
+    // Handle env: $PORT substitution
+    let env: Record<string, string> = {
+      LOCAL: 'local',
+      PORT: projectPort.toString(),
+    };
+    if (startCommand.env) {
+      env = { ...env, ...startCommand.env };
       for (const key of Object.keys(env)) {
         if (typeof env[key] === 'string' && env[key].includes('$PORT')) {
-          env[key] = env[key].replace('$PORT', projectPort.toString());
+          env[key] = env[key].replace(/\$PORT/g, projectPort.toString());
         }
       }
     }
@@ -166,7 +147,6 @@ export async function startServer({
         env,
         workingDir: '../project',
         acceptableErrorsRegexes,
-        // logErrors: false, // we do more selective logging ourselves
         onError,
         processName: 'local-project-server',
       }),
@@ -183,6 +163,6 @@ export async function startServer({
     console.log(
       `CodeYam Error: Error executing start script: ${error.message}`,
     );
-    throw error; // Rethrow the error to be caught in the main function
+    throw error;
   }
 }

package/analyzer-template/project/trackGeneratedFiles.ts

@@ -0,0 +1,41 @@
+import { existsSync, readFileSync, writeFileSync, unlinkSync } from 'fs';
+
+const TRACKING_FILE_PATH = '../project/.codeyam-generated-files.json';
+
+export interface TrackedFiles {
+  generatedFiles: string[];
+  backupFiles: string[];
+  timestamp: string;
+}
+
+export function getTrackingFilePath(): string {
+  return TRACKING_FILE_PATH;
+}
+
+export function writeTrackingFile(
+  generatedFiles: string[],
+  backupFiles: string[],
+): void {
+  const data: TrackedFiles = {
+    generatedFiles,
+    backupFiles,
+    timestamp: new Date().toISOString(),
+  };
+  writeFileSync(TRACKING_FILE_PATH, JSON.stringify(data, null, 2), 'utf8');
+}
+
+export function readTrackingFile(): TrackedFiles | null {
+  if (!existsSync(TRACKING_FILE_PATH)) return null;
+  try {
+    const content = readFileSync(TRACKING_FILE_PATH, 'utf8');
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+export function clearTrackingFile(): void {
+  if (existsSync(TRACKING_FILE_PATH)) {
+    unlinkSync(TRACKING_FILE_PATH);
+  }
+}

package/analyzer-template/project/updateCommitBackgroundJob.ts

@@ -1,4 +1,4 @@
-import { updateBackgroundJobProgress } from '~codeyam/supabase';
+import { updateBackgroundJobProgress } from '~codeyam/database';
 import { BackgroundJob } from '~codeyam/types';
 export default async function updateCommitBackgroundJob(
   backgroundJob: BackgroundJob,

package/analyzer-template/project/utils/errorHandling.ts

@@ -1,6 +1,6 @@
 import { Analysis, Scenario } from '~codeyam/types';
 import emailErrorReport from '../emailErrorReport';
-import { updateFreshAnalysisStatus } from '~codeyam/supabase';
+import { updateFreshAnalysisStatus } from '~codeyam/database';
 
 export async function recordErrorMessageForScenario(
   analysis: Analysis,