@codeyam/codeyam-cli 0.1.0-staging.596f0eb → 0.1.0-staging.6e699e5

package/analyzer-template/packages/utils/src/lib/lightweightEntityExtractor.ts

@@ -265,6 +265,33 @@ export function findEntityInContent(
             }
           }
         }
+      } else if (
+        ts.isFunctionDeclaration(node) &&
+        !hasExportModifier(node) &&
+        node.name?.text === entityName
+      ) {
+        // Non-exported function declaration
+        result = {
+          code: node.getText(sourceFile),
+          start: node.getStart(sourceFile),
+          end: node.getEnd(),
+        };
+        return;
+      } else if (ts.isVariableStatement(node) && !hasExportModifier(node)) {
+        // Non-exported variable statement
+        for (const declaration of node.declarationList.declarations) {
+          if (
+            ts.isIdentifier(declaration.name) &&
+            declaration.name.text === entityName
+          ) {
+            result = {
+              code: node.getText(sourceFile),
+              start: node.getStart(sourceFile),
+              end: node.getEnd(),
+            };
+            return;
+          }
+        }
       }
 
       ts.forEachChild(node, visit);

package/analyzer-template/packages/utils/src/lib/safeFileName.ts

@@ -1,10 +1,55 @@
-export default function safeFileName(name: string) {
+/**
+ * Simple hash function for generating unique suffixes.
+ * Uses djb2 algorithm - fast and produces good distribution.
+ * Not cryptographically secure, but sufficient for filename uniqueness.
+ */
+function simpleHash(str: string): string {
+  let hash = 5381;
+  for (let i = 0; i < str.length; i++) {
+    hash = (hash * 33) ^ str.charCodeAt(i);
+  }
+  // Convert to unsigned 32-bit and then to hex
+  return (hash >>> 0).toString(16).padStart(8, '0');
+}
+
+export interface SafeFileNameOptions {
+  /**
+   * Maximum length of the resulting filename.
+   * If the name exceeds this length, it will be truncated and a hash suffix added.
+   * macOS has a 255 byte filename limit. Default is undefined (no limit).
+   */
+  maxLength?: number;
+}
+
+export default function safeFileName(
+  name: string,
+  options: SafeFileNameOptions = {},
+): string {
+  const { maxLength } = options;
+
   // Replace unsafe characters with underscores, preserving original casing
   // Then trim leading/trailing underscores to avoid malformed route segments
-  const safeSlug = name.replace(/[^a-zA-Z0-9_]+/g, '_').replace(/^_+|_+$/g, '');
+  let safeSlug = name.replace(/[^a-zA-Z0-9_]+/g, '_').replace(/^_+|_+$/g, '');
 
   if (!safeSlug) return '';
 
   // Ensure it starts with a capital letter (for consistency with Remix routes)
-  return safeSlug.slice(0, 1).toUpperCase() + safeSlug.slice(1);
+  safeSlug = safeSlug.slice(0, 1).toUpperCase() + safeSlug.slice(1);
+
+  // If maxLength is specified and the slug exceeds it, truncate and add a hash
+  if (maxLength && safeSlug.length > maxLength) {
+    // Create an 8-character hash of the full name for uniqueness
+    const hash = simpleHash(name);
+
+    // Reserve space for underscore + hash (9 chars total)
+    const truncateLength = maxLength - 9;
+    const truncated = safeSlug.substring(0, truncateLength);
+
+    // Remove trailing underscore if present (from mid-word truncation)
+    const cleanTruncated = truncated.replace(/_+$/, '');
+
+    safeSlug = `${cleanTruncated}_${hash}`;
+  }
+
+  return safeSlug;
 }

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;
@@ -334,7 +343,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 +387,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;
         }

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/takeScreenshot.ts

@@ -194,12 +194,6 @@ export default async function takeScreenshot({
         const freshScenario = freshScenarios.find(
           (s) => s.name === scenario.name,
         );
-        freshScenario.metadata.screenshotPaths ||= [];
-        if (
-          !freshScenario.metadata.screenshotPaths.includes(screenshotFileName)
-        ) {
-          freshScenario.metadata.screenshotPaths.unshift(screenshotFileName);
-        }
 
         const statusScenario = freshStatus.scenarios.find(
           (s) => s.name === scenario.name,
@@ -208,7 +202,15 @@ export default async function takeScreenshot({
           statusScenario.screenshotFinishedAt = new Date().toISOString();
         }
 
-        if (!screenshotTaken) {
+        // Only add to screenshotPaths if the screenshot was actually taken
+        if (screenshotTaken) {
+          freshScenario.metadata.screenshotPaths ||= [];
+          if (
+            !freshScenario.metadata.screenshotPaths.includes(screenshotFileName)
+          ) {
+            freshScenario.metadata.screenshotPaths.unshift(screenshotFileName);
+          }
+        } else {
           freshScenario.metadata.noScreenshotSaved = true;
           if (!statusScenario.error) {
             statusScenario.error = 'Screenshot not taken properly';

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())

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;