@codeyam/codeyam-cli 0.1.0-staging.15d0f46 → 0.1.0-staging.1a2737b

package/analyzer-template/playwright/capture.ts

@@ -161,10 +161,10 @@ export default async function capture({
   awsLogDebugLevel(1, 'Capture process initialized, waiting for controller...');
 
   // Resolve controller URL once before starting capture loop
-  // Read controller port from log file (for local dev) or use PROJECT_URL env var (for Docker)
+  // Priority: PROJECT_URL env var > log file (local dev) > default (Docker)
   let controllerUrl = process.env.PROJECT_URL;
 
-  if (!controllerUrl) {
+  if (!controllerUrl && process.env.CODEYAM_LOCAL_PROJECT_PATH) {
     // Local dev mode - poll log file until controller port is found
     awsLog('CodeYam: Waiting for controller port in log file...');
     let controllerPort: number | null = null;
@@ -182,10 +182,19 @@ export default async function capture({
       awsLog('CodeYam: Shutdown during controller port wait');
       return;
     }
+  } else if (!controllerUrl) {
+    // Docker mode - use fixed port 3000
+    controllerUrl = 'http://localhost:3000';
+    awsLog(`Using default controller URL: ${controllerUrl}`);
   }
 
   awsLogDebugLevel(1, 'Controller found, waiting for analysis...');
 
+  // Determine if we're in local CLI mode vs cloud mode
+  // In local mode, connection failures indicate server crash (should exit quickly)
+  // In cloud mode, connection failures are normal between work items (wait patiently)
+  const isLocalMode = !!process.env.CODEYAM_LOCAL_PROJECT_PATH;
+
   // Track if we've ever successfully captured an analysis
   // If connection fails after we've successfully worked, it means controller exited
   let hasEverCapturedAnalysis = false;
@@ -248,11 +257,11 @@ export default async function capture({
           analysisId: analysis.id,
           entityName: analysis.entityName,
         });
-        await updateFreshAnalysisStatus(
+        await updateFreshAnalysisStatusWithScenarios(
           analysis.id,
-          (freshStatus, inAnalysis) => {
+          (freshStatus, dbScenarios, inAnalysis) => {
             // Mark any incomplete scenarios as errored
-            for (const scenario of inAnalysis.scenarios || []) {
+            for (const scenario of dbScenarios) {
               const scenarioStatus = freshStatus.scenarios?.find(
                 (s) => s.name === scenario.name,
               );
@@ -272,17 +281,18 @@ export default async function capture({
             }
 
             // Mark the analysis as finished if all scenarios have been addressed
-            const allScenariosComplete = freshStatus.scenarios?.every(
-              (s) => s.finishedAt || s.error,
-            );
+            // Only set finishedAt - the loader will exclude based on scenario states
+            const allScenariosComplete =
+              freshStatus.scenarios?.length >= dbScenarios.length &&
+              freshStatus.scenarios?.every((s) => s.finishedAt || s.error);
             if (allScenariosComplete && !freshStatus.finishedAt) {
               freshStatus.finishedAt = new Date().toISOString();
-              freshStatus.readyToBeCaptured = false;
               awsLog('CodeYam: Marking analysis as complete on shutdown', {
                 analysisId: inAnalysis.id,
               });
             }
           },
+          'capture-shutdown',
         );
       }
 
@@ -334,7 +344,13 @@ export default async function capture({
 
   async function captureOneAnalysis() {
     // controllerUrl is already set in parent scope - just wait for server to be ready
-    const waitResult = await waitForServer(controllerUrl, () => isShuttingDown);
+    const waitResult = await waitForServer(
+      controllerUrl,
+      () => isShuttingDown,
+      {
+        isLocalMode,
+      },
+    );
 
     // Check if controller signaled completion during wait
     if (waitResult.shutdown) {
@@ -372,23 +388,27 @@ export default async function capture({
           break;
         }
 
-        // Check if connection failed (controller may have exited)
+        // Check if connection failed (controller may have exited or not started yet)
         if (result.connectionFailed) {
-          consecutiveConnectionFailures++;
-          awsLog(
-            `CodeYam: Connection failed (attempt ${consecutiveConnectionFailures}/${MAX_CONNECTION_FAILURES_FOR_SHUTDOWN}, hasEverCaptured=${hasEverCapturedAnalysis})`,
-          );
-          // If we've had many consecutive connection failures, the controller has likely exited
-          // This can happen even if hasEverCapturedAnalysis is false due to race conditions
-          // in how scenario completion is tracked
-          if (
-            consecutiveConnectionFailures >=
-            MAX_CONNECTION_FAILURES_FOR_SHUTDOWN
-          ) {
-            awsLog('CodeYam: Controller connection lost, treating as shutdown');
-            isShuttingDown = true;
-            break;
+          // Only treat connection failures as shutdown in local mode
+          // In cloud mode, connection failures are expected between work items
+          if (isLocalMode) {
+            consecutiveConnectionFailures++;
+            awsLog(
+              `CodeYam: Connection failed (attempt ${consecutiveConnectionFailures}/${MAX_CONNECTION_FAILURES_FOR_SHUTDOWN}, hasEverCaptured=${hasEverCapturedAnalysis})`,
+            );
+            if (
+              consecutiveConnectionFailures >=
+              MAX_CONNECTION_FAILURES_FOR_SHUTDOWN
+            ) {
+              awsLog(
+                'CodeYam: Controller connection lost, treating as shutdown',
+              );
+              isShuttingDown = true;
+              break;
+            }
           }
+          // In cloud mode, just continue waiting (don't count failures)
         } else {
           consecutiveConnectionFailures = 0;
         }
@@ -531,7 +551,7 @@ export default async function capture({
 
           await updateFreshAnalysisStatusWithScenarios(
             analysis.id,
-            (freshStatus, scenarios) => {
+            (freshStatus, dbScenarios) => {
               freshStatus.scenarios ||= [];
               const scenarioStatus = freshStatus.scenarios.find(
                 (s) => s.name === scenario.name,
@@ -550,6 +570,17 @@ export default async function capture({
                   error: fullErrorMessage,
                 });
               }
+
+              // Check if all scenarios are now complete (even if with errors)
+              // Only set finishedAt - the loader will exclude this analysis based on
+              // the scenario check (all have finishedAt || error), no need to also
+              // toggle readyToBeCaptured which has different semantics
+              if (
+                freshStatus.scenarios.length >= dbScenarios.length &&
+                freshStatus.scenarios.every((s) => s.finishedAt || s.error)
+              ) {
+                freshStatus.finishedAt = new Date().toISOString();
+              }
             },
             'capture-http-error',
           );

package/analyzer-template/playwright/captureStatic.ts

@@ -40,7 +40,7 @@ export default async function captureStatic({
       const now = new Date().toISOString();
       await updateCommitMetadata({
         commitId: analysis.commitId,
-        updateCallback: (metadata, commit) => {
+        updateCallback: (metadata) => {
           if (metadata.currentRun) {
             metadata.currentRun.firstCaptureAt ??= now;
             metadata.currentRun.lastCaptureAt = now;

package/analyzer-template/playwright/getCodeYamInfo.ts

@@ -1,5 +1,3 @@
-/* eslint-disable */
-
 import { ProjectFramework } from '~codeyam/types';
 
 export interface CodeYamInfo {
@@ -41,7 +39,9 @@ export default async function getCodeYamInfo(
 
       // if controller signals complete, tell capture to shut down
       if (phase === 'COMPLETE') {
-        console.log(`CodeYam DEBUG: getCodeYamInfo received COMPLETE phase, signaling shutdown`);
+        console.log(
+          `CodeYam DEBUG: getCodeYamInfo received COMPLETE phase, signaling shutdown`,
+        );
         if (options?.returnShutdown) {
           return { info: null, shutdown: true };
         }
@@ -57,7 +57,6 @@ export default async function getCodeYamInfo(
       }
 
       // all other cases mean 'keep waiting'
-      console.log(`CodeYam DEBUG: getCodeYamInfo phase=${phase}, info=${info ? 'present' : 'null'}, returning null`);
       if (options?.returnShutdown) {
         return { info: null, shutdown: false };
       }
@@ -74,7 +73,9 @@ export default async function getCodeYamInfo(
     const errorMessage = error.message || '';
     const causeMessage = error.cause?.message || '';
 
-    console.log(`CodeYam DEBUG: getCodeYamInfo caught error - code=${errorCode}, message=${errorMessage}, causeMessage=${causeMessage}`);
+    console.log(
+      `CodeYam DEBUG: getCodeYamInfo caught error - code=${errorCode}, message=${errorMessage}, causeMessage=${causeMessage}`,
+    );
 
     const isConnectionError =
       errorCode === 'ECONNREFUSED' ||
@@ -85,11 +86,15 @@ export default async function getCodeYamInfo(
       causeMessage.includes('ECONNREFUSED');
 
     if (!isConnectionError) {
-      console.log(`CodeYam DEBUG: getCodeYamInfo error is NOT a connection error, rethrowing`);
+      console.log(
+        `CodeYam DEBUG: getCodeYamInfo error is NOT a connection error, rethrowing`,
+      );
       throw error;
     }
     // let caller know the server just isn't up yet (or has shut down)
-    console.log(`CodeYam DEBUG: getCodeYamInfo connection error detected, returning connectionFailed=true`);
+    console.log(
+      `CodeYam DEBUG: getCodeYamInfo connection error detected, returning connectionFailed=true`,
+    );
     if (options?.returnShutdown) {
       return { info: null, shutdown: false, connectionFailed: true };
     }

package/analyzer-template/playwright/takeElementScreenshot.ts

@@ -36,28 +36,43 @@ async function safeAwaitWithReturn<T>(
   }
 }
 
-/** Wait until DOM mutations stop for `quietMs` (default 500 ms). */
-async function waitForDomIdle(page: Page, quietMs = 500) {
+/** Wait until DOM mutations stop for `quietMs` (default 500 ms), or until `maxWaitMs` elapsed. */
+async function waitForDomIdle(page: Page, quietMs = 500, maxWaitMs = 5000) {
   await page.evaluate(
-    ({ quietMs }) =>
+    ({ quietMs, maxWaitMs }) =>
       new Promise<void>((resolve) => {
         let timer: NodeJS.Timeout;
+        const startTime = Date.now();
+
+        const finish = () => {
+          clearTimeout(timer);
+          observer.disconnect();
+          resolve();
+        };
+
         const reset = () => {
           clearTimeout(timer);
-          timer = setTimeout(() => {
-            observer.disconnect();
-            resolve();
-          }, quietMs);
+          // Check if we've exceeded max wait time
+          if (Date.now() - startTime >= maxWaitMs) {
+            finish();
+            return;
+          }
+          timer = setTimeout(finish, quietMs);
         };
+
         const observer = new MutationObserver(reset);
         observer.observe(document, {
           childList: true,
           subtree: true,
           attributes: true,
         });
+
+        // Set up the max wait timeout as a fallback
+        setTimeout(finish, maxWaitMs);
+
         reset();
       }),
-    { quietMs },
+    { quietMs, maxWaitMs },
   );
 }
 
@@ -226,10 +241,10 @@ export default async function takeElementScreenshot({
       `[${screenshotId}] Step 1 complete: Page loaded (success=${gotoResult}), elapsed: ${Date.now() - startTime}ms`,
     );
     awsLog(
-      `[${screenshotId}] Step 2: Waiting for DOM idle (timeout=${domIdle}ms)...`,
+      `[${screenshotId}] Step 2: Waiting for DOM idle (quietMs=500, maxWait=${domIdle}ms)...`,
     );
     const domIdleResult = await safeAwait('dom-idle', () =>
-      waitForDomIdle(page, domIdle),
+      waitForDomIdle(page, 500, domIdle),
     );
     awsLog(
       `[${screenshotId}] Step 2 complete: DOM idle (success=${domIdleResult}), elapsed: ${Date.now() - startTime}ms`,
@@ -262,7 +277,7 @@ export default async function takeElementScreenshot({
         page.waitForLoadState('networkidle', { timeout: pageIdle }),
       );
       await safeAwait('post-script-dom-idle', () =>
-        waitForDomIdle(page, domIdle),
+        waitForDomIdle(page, 500, domIdle),
       );
       awsLog(
         `[${screenshotId}] Step 4 complete: Instructions executed, elapsed: ${Date.now() - startTime}ms`,

package/analyzer-template/playwright/waitForServer.ts

@@ -17,10 +17,18 @@ export interface WaitForServerResult {
   shutdown: boolean;
 }
 
+export interface WaitForServerOptions {
+  // In local CLI mode, treat connection failures as shutdown signal (server should be running)
+  // In cloud mode, connection failures are normal between work items
+  isLocalMode?: boolean;
+}
+
 export default async function waitForServer(
   url: string,
   shouldStop: () => boolean,
+  options?: WaitForServerOptions,
 ): Promise<WaitForServerResult> {
+  const isLocalMode = options?.isLocalMode ?? false;
   let retryDelay = INITIAL_RETRY_DELAY;
   const startTime = Date.now();
   let consecutiveConnectionFailures = 0;
@@ -49,14 +57,21 @@ export default async function waitForServer(
         return { shutdown: true };
       }
 
-      // Check if connection failed (server exited)
+      // Check if connection failed (server exited or not started yet)
       if (result.connectionFailed) {
-        consecutiveConnectionFailures++;
-        // If we've had many consecutive connection failures, the controller has likely exited
-        if (consecutiveConnectionFailures >= MAX_CONNECTION_FAILURES_FOR_SHUTDOWN) {
-          awsLog('CodeYam: Controller connection lost, treating as shutdown');
-          return { shutdown: true };
+        // Only treat connection failures as shutdown in local mode
+        // In cloud mode, connection failures are expected between work items
+        if (isLocalMode) {
+          consecutiveConnectionFailures++;
+          if (
+            consecutiveConnectionFailures >=
+            MAX_CONNECTION_FAILURES_FOR_SHUTDOWN
+          ) {
+            awsLog('CodeYam: Controller connection lost, treating as shutdown');
+            return { shutdown: true };
+          }
         }
+        // In cloud mode, just continue waiting (don't count failures)
       } else {
         consecutiveConnectionFailures = 0;
       }

package/analyzer-template/project/analyzeBaselineCommit.ts

@@ -21,6 +21,8 @@ export interface AnalyzeBaselineCommitArgs {
   desiredAnalyses?: Analysis[];
   force?: boolean;
   fileStore?: LazyFileStore;
+  /** Called after data structures are prepared, signaling orchestration can begin */
+  onAnalysisProducing?: () => void;
 }
 
 export interface AnalyzeBaselineCommitResult {
@@ -40,6 +42,7 @@ export default async function analyzeBaselineCommit({
   desiredAnalyses = [],
   force = false,
   fileStore,
+  onAnalysisProducing,
 }: AnalyzeBaselineCommitArgs): Promise<AnalyzeBaselineCommitResult> {
   awsLog('CodeYam: Analyze - branchCommit (baseline) path', {
     analysisIds,
@@ -64,6 +67,7 @@ export default async function analyzeBaselineCommit({
     context,
     steps,
     fileStore,
+    onAnalysisProducing,
   });
 
   let analysisBranches = Object.values(context.getAnalysisMap())
@@ -99,6 +103,11 @@ export default async function analyzeBaselineCommit({
       entitiesAnalyzedAt: now,
     },
     archiveCurrentRun: true,
+    updateCallback(metadata) {
+      if (metadata.currentRun?.captureCompletedAt) {
+        metadata.currentRun.completedAt = now;
+      }
+    },
   });
 
   awsLog(`CodeYam: Marking baseline completed for project ${project.slug}`);

package/analyzer-template/project/analyzeBranchCommit.ts

@@ -24,6 +24,8 @@ interface AnalyzeBranchCommitArgs {
   context: AnalysisContext;
   steps: string[];
   fileStore?: LazyFileStore;
+  /** Called after data structures are prepared, signaling orchestration can begin */
+  onAnalysisProducing?: () => void;
 }
 
 export default async function analyzeBranchCommit({
@@ -34,6 +36,7 @@ export default async function analyzeBranchCommit({
   context,
   steps,
   fileStore,
+  onAnalysisProducing,
 }: AnalyzeBranchCommitArgs) {
   console.log('CodeYam: Starting Branch Commit Analysis', branchCommit.sha, {
     analysisIds,
@@ -231,6 +234,7 @@ export default async function analyzeBranchCommit({
           steps,
           force: !!process.env.FORCE,
           forceAll: !!process.env.FORCE_ALL,
+          onAnalysisProducing,
         },
       });
     } catch (error) {

package/analyzer-template/project/analyzeFileEntities.ts

@@ -27,6 +27,8 @@ interface AnalyzeFileEntitiesArgs {
   steps: string[];
   context: AnalysisContext;
   fileStore?: LazyFileStore;
+  /** Called after data structures are prepared, signaling orchestration can begin */
+  onAnalysisProducing?: () => void;
 }
 
 export default async function analyzeFileEntities({
@@ -40,6 +42,7 @@ export default async function analyzeFileEntities({
   steps,
   context,
   fileStore,
+  onAnalysisProducing,
 }: AnalyzeFileEntitiesArgs) {
   // Enable baseline mode for E2E tests to skip expensive importedBy tracking
   // This eliminates thousands of DB operations that aren't needed for simulation/capture
@@ -263,6 +266,7 @@ export default async function analyzeFileEntities({
         fresh: !!process.env.FRESH,
         force: !!process.env.FORCE,
         forceAll: !!process.env.FORCE_ALL,
+        onAnalysisProducing,
       },
     });
   }

package/analyzer-template/project/analyzeRegularCommit.ts

@@ -36,6 +36,8 @@ export interface AnalyzeRegularCommitArgs {
   backgroundJob?: BackgroundJob;
   desiredAnalyses?: Analysis[];
   fileStore?: LazyFileStore;
+  /** Called after data structures are prepared, signaling orchestration can begin */
+  onAnalysisProducing?: () => void;
 }
 
 export interface AnalyzeRegularCommitResult {
@@ -97,6 +99,7 @@ export default async function analyzeRegularCommit({
   backgroundJob,
   desiredAnalyses = [],
   fileStore,
+  onAnalysisProducing,
 }: AnalyzeRegularCommitArgs): Promise<AnalyzeRegularCommitResult> {
   awsLog('CodeYam: Analyze - commit path');
 
@@ -174,6 +177,7 @@ export default async function analyzeRegularCommit({
     steps,
     context,
     fileStore,
+    onAnalysisProducing,
   });
   let entities = fileEntities;
 
@@ -249,6 +253,11 @@ export default async function analyzeRegularCommit({
       // In local mode (CLI), let job.js handle archiving after BOTH analysis AND capture complete
       // In cloud mode (Docker), archive immediately after analysis completes
       archiveCurrentRun: !isLocalMode,
+      updateCallback(metadata) {
+        if (metadata.currentRun?.captureCompletedAt) {
+          metadata.currentRun.completedAt = now;
+        }
+      },
     });
   }
 

package/analyzer-template/project/captureLibraryFunctionDirect.ts

@@ -81,33 +81,36 @@ export default async function captureLibraryFunctionDirect(
       },
     );
 
-    // Mark scenario as complete
-    await updateFreshAnalysisStatus(analysis.id, (freshStatus, inAnalysis) => {
-      freshStatus.scenarios ||= [];
-      const scenarioStatus = freshStatus.scenarios.find(
-        (s) => s.name === scenario.name,
-      );
-      if (scenarioStatus) {
-        scenarioStatus.finishedAt = new Date().toISOString();
-      } else {
-        freshStatus.scenarios.push({
-          name: scenario.name,
-          startedAt: new Date().toISOString(),
-          finishedAt: new Date().toISOString(),
-        });
-      }
+    // Mark scenario as complete (use WithScenarios variant to get actual scenario count)
+    await updateFreshAnalysisStatusWithScenarios(
+      analysis.id,
+      (freshStatus, dbScenarios, _inAnalysis) => {
+        freshStatus.scenarios ||= [];
+        const scenarioStatus = freshStatus.scenarios.find(
+          (s) => s.name === scenario.name,
+        );
+        if (scenarioStatus) {
+          scenarioStatus.finishedAt = new Date().toISOString();
+        } else {
+          freshStatus.scenarios.push({
+            name: scenario.name,
+            startedAt: new Date().toISOString(),
+            finishedAt: new Date().toISOString(),
+          });
+        }
 
-      // Check if all scenarios are done
-      const allScenariosAvailable =
-        freshStatus.scenarios.length >= inAnalysis.scenarios?.length;
-      if (
-        allScenariosAvailable &&
-        freshStatus.scenarios.every((s) => !!s.finishedAt)
-      ) {
-        freshStatus.finishedAt = new Date().toISOString();
-        freshStatus.readyToBeCaptured = false;
-      }
-    });
+        // Check if all scenarios are done
+        const allScenariosAvailable =
+          freshStatus.scenarios.length >= dbScenarios.length;
+        if (
+          allScenariosAvailable &&
+          freshStatus.scenarios.every((s) => !!s.finishedAt)
+        ) {
+          freshStatus.finishedAt = new Date().toISOString();
+          freshStatus.readyToBeCaptured = false;
+        }
+      },
+    );
 
     awsLog('CodeYam: Direct library function capture complete', {
       analysisId: analysis.id,