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

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

@@ -1,2 +1,10 @@
-export default function safeFileName(name: string): string;
+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;
 //# sourceMappingURL=safeFileName.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"safeFileName.d.ts","sourceRoot":"","sources":["../../../../src/lib/safeFileName.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,OAAO,UAAU,YAAY,CAAC,IAAI,EAAE,MAAM,UAShD"}
+{"version":3,"file":"safeFileName.d.ts","sourceRoot":"","sources":["../../../../src/lib/safeFileName.ts"],"names":[],"mappings":"AAcA,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,CAAC,OAAO,UAAU,YAAY,CAClC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,mBAAwB,GAChC,MAAM,CA4BR"}

package/analyzer-template/packages/utils/dist/utils/src/lib/safeFileName.js

@@ -1,10 +1,36 @@
-export default function safeFileName(name) {
+/**
+ * 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) {
+    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 default function safeFileName(name, options = {}) {
+    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;
 }
 //# sourceMappingURL=safeFileName.js.map

package/analyzer-template/packages/utils/dist/utils/src/lib/safeFileName.js.map

@@ -1 +1 @@
-{"version":3,"file":"safeFileName.js","sourceRoot":"","sources":["../../../../src/lib/safeFileName.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,OAAO,UAAU,YAAY,CAAC,IAAY;IAC/C,yEAAyE;IACzE,2EAA2E;IAC3E,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAE9E,IAAI,CAAC,QAAQ;QAAE,OAAO,EAAE,CAAC;IAEzB,6EAA6E;IAC7E,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAChE,CAAC"}
+{"version":3,"file":"safeFileName.js","sourceRoot":"","sources":["../../../../src/lib/safeFileName.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,SAAS,UAAU,CAAC,GAAW;IAC7B,IAAI,IAAI,GAAG,IAAI,CAAC;IAChB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACpC,IAAI,GAAG,CAAC,IAAI,GAAG,EAAE,CAAC,GAAG,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IACzC,CAAC;IACD,6CAA6C;IAC7C,OAAO,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AACpD,CAAC;AAWD,MAAM,CAAC,OAAO,UAAU,YAAY,CAClC,IAAY,EACZ,UAA+B,EAAE;IAEjC,MAAM,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC;IAE9B,yEAAyE;IACzE,2EAA2E;IAC3E,IAAI,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAE5E,IAAI,CAAC,QAAQ;QAAE,OAAO,EAAE,CAAC;IAEzB,6EAA6E;IAC7E,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAElE,6EAA6E;IAC7E,IAAI,SAAS,IAAI,QAAQ,CAAC,MAAM,GAAG,SAAS,EAAE,CAAC;QAC7C,6DAA6D;QAC7D,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;QAE9B,sDAAsD;QACtD,MAAM,cAAc,GAAG,SAAS,GAAG,CAAC,CAAC;QACrC,MAAM,SAAS,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC;QAExD,mEAAmE;QACnE,MAAM,cAAc,GAAG,SAAS,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAEpD,QAAQ,GAAG,GAAG,cAAc,IAAI,IAAI,EAAE,CAAC;IACzC,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}

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

@@ -82,9 +82,21 @@ export async function applyUniversalMocks(
     modifiedFiles: [],
   };
 
+  // Deduplicate mocks by (filePath, entityName) before processing.
+  // This handles cases where the same mock might appear multiple times in the array.
+  const seenMocks = new Set<string>();
+  const deduplicatedMocks = mocks.filter((mock) => {
+    const key = `${mock.filePath}:${mock.entityName}`;
+    if (seenMocks.has(key)) {
+      return false;
+    }
+    seenMocks.add(key);
+    return true;
+  });
+
   // Group mocks by filePath to handle multiple entities in the same file
   const mocksByPath = new Map<string, UniversalMock[]>();
-  for (const mock of mocks) {
+  for (const mock of deduplicatedMocks) {
     if (!mock.content) {
       log(`Skipping mock for ${mock.filePath}:${mock.entityName} - no content`);
       continue;
@@ -303,7 +315,21 @@ async function applyNodeModuleMock(options: {
     if (mock.entityName === 'default') {
       mockParts.push(`export default ${mock.content}`);
     } else {
-      mockParts.push(`${mock.content}\n\nexport { ${mock.entityName} };`);
+      // Check if the content already exports the entity (e.g., "export const X" or "export function X")
+      // to avoid duplicate exports like "export const X... export { X };"
+      const alreadyExports =
+        mock.content?.includes(`export const ${mock.entityName}`) ||
+        mock.content?.includes(`export function ${mock.entityName}`) ||
+        mock.content?.includes(`export class ${mock.entityName}`) ||
+        mock.content?.includes(`export { ${mock.entityName}`);
+
+      if (alreadyExports) {
+        // Content already exports the entity - use as-is
+        mockParts.push(mock.content!);
+      } else {
+        // Content doesn't export - add export statement
+        mockParts.push(`${mock.content}\n\nexport { ${mock.entityName} };`);
+      }
     }
     result.applied++;
   }

package/analyzer-template/packages/utils/src/lib/fs/rsyncCopy.ts

@@ -1,4 +1,87 @@
-import { spawn } from 'child_process';
+import { execSync, spawn } from 'child_process';
+import { existsSync, readdirSync, rmSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Try to use APFS copy-on-write clones on macOS for near-instant directory copies.
+ * Falls back to rsync on non-macOS or if the clone fails.
+ *
+ * Returns true if the clone succeeded (caller can skip rsync).
+ */
+function tryApfsClone({
+  sourcePath,
+  destinationPath,
+  excludes,
+  silent,
+}: {
+  sourcePath: string;
+  destinationPath: string;
+  excludes: string[];
+  silent: boolean;
+}): boolean {
+  if (process.platform !== 'darwin') return false;
+
+  // APFS clone requires the destination to not exist.
+  // If it exists and is empty, remove it so we can clone into it.
+  if (existsSync(destinationPath)) {
+    try {
+      const contents = readdirSync(destinationPath);
+      if (contents.length > 0) {
+        // Destination is non-empty — can't use clone, fall back to rsync
+        return false;
+      }
+      rmSync(destinationPath, { recursive: true });
+    } catch {
+      return false;
+    }
+  }
+
+  try {
+    // cp -c -R: APFS copy-on-write clone (faster than rsync, avoids data copy)
+    execSync(`cp -c -R "${sourcePath}" "${destinationPath}"`, {
+      stdio: 'pipe',
+      timeout: 300_000, // 5 min safety timeout
+    });
+
+    // Remove excluded items from the clone
+    for (const exclude of excludes) {
+      if (exclude.includes('*')) {
+        // Glob pattern — use shell expansion
+        try {
+          execSync(`rm -rf "${join(destinationPath, exclude)}"`, {
+            stdio: 'pipe',
+            shell: '/bin/sh',
+          });
+        } catch {
+          // Glob matched nothing — fine
+        }
+      } else {
+        const excludePath = join(destinationPath, exclude);
+        if (existsSync(excludePath)) {
+          rmSync(excludePath, { recursive: true, force: true });
+        }
+      }
+    }
+
+    if (!silent) {
+      console.log(
+        `Directory cloned (APFS CoW) from ${sourcePath} to ${destinationPath}`,
+      );
+    }
+    return true;
+  } catch {
+    // Clone failed (cross-volume, non-APFS, etc.) — fall back to rsync
+    // Clean up any partial clone
+    if (existsSync(destinationPath)) {
+      try {
+        rmSync(destinationPath, { recursive: true });
+      } catch {
+        // Best effort cleanup
+      }
+    }
+    return false;
+  }
+}
 
 export default async function rsyncCopy({
   sourcePath,
@@ -15,13 +98,38 @@ export default async function rsyncCopy({
   silent?: boolean;
   extraArgs?: string[];
 }): Promise<void> {
+  const startTime = Date.now();
+
+  // On macOS, try APFS copy-on-write clone first (near-instant).
+  // Skip when extraArgs are provided since those are rsync-specific flags
+  // that the clone path can't honor.
+  if (!keepExisting && extraArgs.length === 0) {
+    const cloned = tryApfsClone({
+      sourcePath,
+      destinationPath,
+      excludes,
+      silent,
+    });
+    if (cloned) {
+      if (!silent) {
+        const duration = ((Date.now() - startTime) / 1000).toFixed(1);
+        console.log(
+          `Directory synced from ${sourcePath} to ${destinationPath} [Time: ${duration}s]`,
+        );
+      }
+      return;
+    }
+  }
+
+  // Fall back to rsync
   return new Promise((resolve, reject) => {
     const source = sourcePath.endsWith('/') ? sourcePath : `${sourcePath}/`;
     const dest = destinationPath.endsWith('/')
       ? destinationPath
       : `${destinationPath}/`;
 
-    const rsyncArgs = ['-a'];
+    // -a includes --specials which tries to copy sockets/FIFOs and can fail
+    const rsyncArgs = ['-a', '--no-specials'];
 
     if (!keepExisting) {
       rsyncArgs.push('--delete', '--force');
@@ -37,7 +145,6 @@ export default async function rsyncCopy({
 
     rsyncArgs.push(source, dest);
 
-    const startTime = Date.now();
     const rsyncProcess = spawn('rsync', rsyncArgs);
 
     rsyncProcess.on('exit', (code) => {
@@ -50,6 +157,17 @@ export default async function rsyncCopy({
         }
         resolve();
       } else {
+        console.error(
+          `CodeYam Error: rsync failed with code: ${code}`,
+          JSON.stringify(
+            {
+              rsyncArgs,
+            },
+            null,
+            2,
+          ),
+        );
+
         reject(new Error(`rsync failed with exit code ${code}`));
       }
     });

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;
@@ -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`,