@codeyam/codeyam-cli 0.1.0-staging.d0ad4ae → 0.1.0-staging.d57a578

package/analyzer-template/project/orchestrateCapture.ts

@@ -32,7 +32,10 @@ import type {
 } from './orchestrateCapture/taskRunner';
 import KyselyAnalysisLoader from './orchestrateCapture/KyselyAnalysisLoader';
 
-const MAX_BATCH_SIZE = 6;
+// Temporarily set to 1 (effectively disabling batching) to work around reliability
+// issues where multi-analysis batches cause cascading failures. Revisit once we
+// reassess the SQS protocol and worker error handling.
+const MAX_BATCH_SIZE = 1;
 const POLLING_INTERVAL = 30 * 1000; // 30 seconds
 const TASK_HEALTH_CHECK_INTERVAL = 60 * 1000; // 1 minute
 const ANALYSIS_TIMEOUT = 20 * 60 * 1000;
@@ -99,15 +102,20 @@ export default async function orchestrateCapture({
   const attemptCount = new Map<string, number>();
   const maxAttempts = 2;
 
+  // Track which analyses had a worker report success — only these can be "captured"
+  const confirmedSuccessAnalyses = new Set<string>();
+
   // Register batch completion callback with task runner
-  taskRunner.onBatchCompleted((analysisIds: string[]) => {
+  taskRunner.onBatchCompleted((analysisIds: string[], success: boolean) => {
     console.log(
-      `CodeYam Capture: Received batch completion for ${analysisIds.length} analyses: ${analysisIds.join(', ')}`,
+      `CodeYam Capture: Received batch completion (success=${success}) for ${analysisIds.length} analyses: ${analysisIds.join(', ')}`,
     );
-    // Remove from inFlight and increment attempt count for each analysis
     for (const analysisId of analysisIds) {
       inFlight.delete(analysisId);
       attemptCount.set(analysisId, (attemptCount.get(analysisId) || 0) + 1);
+      if (success) {
+        confirmedSuccessAnalyses.add(analysisId);
+      }
     }
   });
 
@@ -195,9 +203,13 @@ export default async function orchestrateCapture({
         knownAnalyses.add(id);
       }
 
-      // an analysis we've seen, but is no longer "ready to be captured", is captured!
+      // An analysis is "captured" only if:
+      // 1. A worker reported success for its batch (in confirmedSuccessAnalyses)
+      // 2. It no longer appears in the ready-to-be-captured list (DB confirms)
+      // This prevents transient empty DB results from inflating the captured count.
       const capturedAnalysisIds = Array.from(knownAnalyses).filter(
-        (id) => !allReadyAnalysisIds.includes(id),
+        (id) =>
+          confirmedSuccessAnalyses.has(id) && !allReadyAnalysisIds.includes(id),
       );
 
       // Remove captured analyses from inFlight tracking
@@ -355,6 +367,32 @@ export default async function orchestrateCapture({
         }
       }
 
+      // Early exit when all enqueued work is settled (captured or abandoned)
+      // This avoids waiting for the 20-minute ANALYSIS_TIMEOUT when capture is complete
+      // IMPORTANT: Only check this when isDraining (analysis phase complete) to avoid
+      // exiting while slow-running analyses are still in progress
+      if (
+        isDraining &&
+        !firstLoop &&
+        enqueuedAnalyses.size > 0 &&
+        inFlight.size === 0 &&
+        remaining.length === 0 &&
+        toRetry.length === 0
+      ) {
+        const allAnalysesSettled = Array.from(enqueuedAnalyses).every((id) => {
+          const captured = !allReadyAnalysisIds.includes(id);
+          const abandoned = (attemptCount.get(id) || 0) >= maxAttempts;
+          return captured || abandoned;
+        });
+
+        if (allAnalysesSettled) {
+          console.log(
+            'CodeYam Capture: All enqueued analyses settled (captured or abandoned), exiting early',
+          );
+          break;
+        }
+      }
+
       if (isDraining) {
         // Exit if analysis complete but no entities ready for capture
         // Only check this after at least one poll (not firstLoop) to ensure we've
@@ -371,7 +409,9 @@ export default async function orchestrateCapture({
           // check if all enqueued analyses have been either captured or abandoned
           const allAnalysesSettled = Array.from(enqueuedAnalyses).every(
             (id) => {
-              const captured = !allReadyAnalysisIds.includes(id);
+              const captured =
+                confirmedSuccessAnalyses.has(id) &&
+                !allReadyAnalysisIds.includes(id);
               const abandoned = (attemptCount.get(id) || 0) >= maxAttempts;
               return captured || abandoned;
             },
@@ -411,5 +451,33 @@ export default async function orchestrateCapture({
   } finally {
     // Always clean up task runner resources in finally block
     await taskRunner.cleanup();
+
+    const trackingCommit = metadataCommit ?? commit;
+    if (trackingCommit?.id) {
+      const captureCompletedAt = new Date().toISOString();
+
+      await updateCommitMetadata({
+        commitId: trackingCommit.id,
+        runStatusUpdate: {
+          captureCompletedAt,
+          capturePid: undefined,
+        },
+        // completedAt = max(analysisCompletedAt, captureCompletedAt)
+        // Normally capture finishes after analysis, but using max means illogical
+        // orderings leave a detectable signal (completedAt !== captureCompletedAt).
+        updateCallback(metadata) {
+          const run = metadata.currentRun!;
+          run.completedAt =
+            run.analysisCompletedAt &&
+            run.analysisCompletedAt > captureCompletedAt
+              ? run.analysisCompletedAt
+              : captureCompletedAt;
+        },
+      }).catch((error) => {
+        console.log(
+          `Warning: Failed to update capture completion metadata: ${error}`,
+        );
+      });
+    }
   }
 }

package/analyzer-template/project/reconcileMockDataKeys.ts

@@ -7,6 +7,9 @@
  *
  * Keys are now original call signatures (e.g., "useFetcher<User>()", "db.select(query)").
  *
+ * Also handles flat dotted keys (e.g., "trpc.fastener.getAttributeValues.useQuery(...)")
+ * by converting them to nested structure.
+ *
  * @param mockData The mock data object to reconcile
  * @param expectedKeys The expected keys from the structure
  */
@@ -23,7 +26,32 @@ export function reconcileMockDataKeys(
         ? reconcileMockDataKeys(value as Record<string, unknown>, expectedKeys)
         : value;
 
-    // Check if key matches an expected key exactly
+    // Check if this is a flat dotted key (method chain) that should be nested.
+    // e.g., "ZId.safeParse(params.surveyId)" → { ZId: { "safeParse(params.surveyId)": ... } }
+    // e.g., "trpc.fastener.getAttributeValues.useQuery({ ... })" → nested structure
+    // constructMockCode generates nested lookups like data["ZId"]["safeParse(...)"]
+    // for method chains, so the data must be nested to match.
+    const flatKeyParts = parseFlatDottedKey(key);
+    if (flatKeyParts && flatKeyParts.length > 1) {
+      // Nest when:
+      // 1. The full key matches an expected key exactly (e.g., "ZId.safeParse(params.surveyId)")
+      // 2. OR individual parts match expected keys (e.g., "trpc" is an expected key)
+      //    This handles LLM-generated flat keys that should be nested (Issue 8)
+      const shouldNest =
+        expectedKeys.includes(key) ||
+        flatKeyParts.some((part) => expectedKeys.includes(part));
+      if (shouldNest) {
+        deepMergeIntoResult(
+          result,
+          flatKeyParts,
+          reconciledValue,
+          expectedKeys,
+        );
+        continue;
+      }
+    }
+
+    // Check if key matches an expected key exactly (for non-dotted keys)
     if (expectedKeys.includes(key)) {
       result[key] = reconciledValue;
       continue;
@@ -42,6 +70,94 @@ export function reconcileMockDataKeys(
   return result;
 }
 
+/**
+ * Parse a flat dotted key into path segments.
+ * Handles keys like "trpc.fastener.getAttributeValues.useQuery({ ... })"
+ * where the last part might contain parentheses with function arguments.
+ *
+ * Returns null if the key doesn't look like a dotted path.
+ */
+function parseFlatDottedKey(key: string): string[] | null {
+  // Don't treat keys that start with a function call as dotted paths
+  // e.g., "useQuery({ id: 123 })" should not be parsed
+  if (key.match(/^[a-zA-Z_][a-zA-Z0-9_]*\s*\(/)) {
+    // Check if there's a dot BEFORE the first parenthesis
+    const parenIndex = key.indexOf('(');
+    const dotBeforeParen = key.slice(0, parenIndex).includes('.');
+    if (!dotBeforeParen) {
+      return null;
+    }
+  }
+
+  // Must contain a dot to be a dotted path
+  if (!key.includes('.')) {
+    return null;
+  }
+
+  const parts: string[] = [];
+  let current = '';
+  let depth = 0;
+
+  for (let i = 0; i < key.length; i++) {
+    const char = key[i];
+
+    if (char === '(' || char === '{' || char === '[') {
+      depth++;
+      current += char;
+    } else if (char === ')' || char === '}' || char === ']') {
+      depth--;
+      current += char;
+    } else if (char === '.' && depth === 0) {
+      if (current) {
+        parts.push(current);
+      }
+      current = '';
+    } else {
+      current += char;
+    }
+  }
+
+  if (current) {
+    parts.push(current);
+  }
+
+  // Need at least 2 parts for it to be a meaningful dotted path
+  return parts.length >= 2 ? parts : null;
+}
+
+/**
+ * Deep merge a value into the result object following the path segments.
+ * Reconciles the leaf key against expected keys.
+ */
+function deepMergeIntoResult(
+  result: Record<string, unknown>,
+  parts: string[],
+  value: unknown,
+  expectedKeys: string[],
+): void {
+  let current = result;
+
+  // Navigate/create path for all but the last part
+  for (let i = 0; i < parts.length - 1; i++) {
+    const part = parts[i];
+    if (!(part in current)) {
+      current[part] = {};
+    }
+    const next = current[part];
+    if (next && typeof next === 'object' && !Array.isArray(next)) {
+      current = next as Record<string, unknown>;
+    } else {
+      // Can't traverse further, structure mismatch
+      return;
+    }
+  }
+
+  // Handle the leaf key
+  const leafKey = parts[parts.length - 1];
+  const closestLeafKey = findClosestKey(leafKey, expectedKeys) || leafKey;
+  current[closestLeafKey] = value;
+}
+
 /**
  * Find the closest matching key from expectedKeys for a given key.
  *
@@ -51,10 +167,14 @@ export function reconcileMockDataKeys(
  * - Match based on the common prefix
  * - If key has no parentheses, try matching with "()" appended
  * - If key is "funcName()" (empty args), match expected key "funcName({...})" by function name
+ * - If key has object arguments (like useQuery({...})), match by function name
+ * - If key has single argument with literal value, match by function name
  *
  * e.g., "eq('user_id', 'user-12345')" matches "eq('user_id', user.id)"
  * e.g., "getAll" matches "getAll()"
  * e.g., "getSurveysAction()" matches "getSurveysAction({ environmentId, ... })"
+ * e.g., "useQuery({ id: 123 })" matches "useQuery({ id: Number(id) })"
+ * e.g., "useCustomSizes('example-slug')" matches "useCustomSizes(projectSlug)"
  */
 function findClosestKey(key: string, expectedKeys: string[]): string | null {
   const keyBase = extractKeyBase(key);
@@ -95,6 +215,105 @@ function findClosestKey(key: string, expectedKeys: string[]): string | null {
     }
   }
 
+  // If key has object literal arguments (like "useQuery({ id: 123, ... })"),
+  // try matching expected keys with the same function path AND first object property.
+  // This handles cases where LLM generates literal values but expected keys have variable references.
+  // e.g., "useQuery({ attributes: ['a', 'b'] })" matches "useQuery({ attributes: items || [] })"
+  // e.g., "trpc.users.getById.useQuery({ userId: 'user-123' })" matches "trpc.users.getById.useQuery({ userId })"
+  // Uses first property matching when multiple candidates exist for disambiguation.
+  const objectArgMatch = key.match(/^([a-zA-Z_][a-zA-Z0-9_.]*)\s*\(\s*\{/);
+  if (objectArgMatch) {
+    const funcPath = objectArgMatch[1]; // Can be "funcName" or "path.to.funcName"
+    // Extract the first property name from the object argument
+    const firstPropMatch = key.match(
+      /\(\s*\{\s*\n?\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*:/,
+    );
+    const firstProp = firstPropMatch ? firstPropMatch[1] : null;
+
+    // Collect all matching candidates
+    const candidates: string[] = [];
+    for (const expected of expectedKeys) {
+      // Match if expected key has the same function path and starts with object argument
+      const expectedObjArgMatch = expected.match(
+        new RegExp(`^${escapeRegExp(funcPath)}\\s*\\(\\s*\\{`),
+      );
+      if (expectedObjArgMatch) {
+        candidates.push(expected);
+      }
+    }
+
+    // If we have a first property, prefer matching by property name
+    if (firstProp && candidates.length > 1) {
+      // Look for a candidate with the same first property
+      const propRegex = new RegExp(
+        `\\(\\s*\\{[\\s\\n]*${escapeRegExp(firstProp)}\\s*:`,
+      );
+      const propMatch = candidates.find((c) => propRegex.test(c));
+      if (propMatch) {
+        return propMatch;
+      }
+    }
+
+    // Fall back to first candidate if no property match found
+    if (candidates.length > 0) {
+      return candidates[0];
+    }
+  }
+
+  // If key has a single argument (literal value OR variable reference),
+  // try matching expected keys with the same function name but different argument.
+  // This handles cases where:
+  // - LLM generates "useCustomSizes('example-slug')" but expected key is "useCustomSizes(projectSlug)"
+  // - LLM generates "useCustomSizes(someProjectSlug)" but expected key is "useCustomSizes(projectSlug)"
+  //
+  // The second case is important because when LLM generates multiple keys with different
+  // variable names (e.g., "useCustomSizes(someProjectSlug)" and "useCustomSizes(projectSlug)"),
+  // without reconciliation, normalizeMockData merges them into "useCustomSizes()" which
+  // doesn't match the expected key "useCustomSizes(projectSlug)", causing undefined data access.
+  const singleArgMatch = key.match(
+    /^([a-zA-Z_][a-zA-Z0-9_.]*)\s*\(([^,)]+)\)$/,
+  );
+  if (singleArgMatch) {
+    const funcPath = singleArgMatch[1];
+    const arg = singleArgMatch[2].trim();
+    // Apply this matching if the argument is a literal OR a simple variable reference
+    const isLiteralArg = /^['"`].*['"`]$/.test(arg) || /^\d+$/.test(arg);
+    const isVariableRef = /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(arg);
+    if (isLiteralArg || isVariableRef) {
+      for (const expected of expectedKeys) {
+        // Match if expected key has the same function path with a single argument
+        const expectedSingleArgMatch = expected.match(
+          new RegExp(`^${escapeRegExp(funcPath)}\\s*\\([^,)]+\\)$`),
+        );
+        if (expectedSingleArgMatch) {
+          return expected;
+        }
+      }
+    }
+  }
+
+  // If key has multiple arguments where one contains a literal value,
+  // try matching expected keys with the same function name and argument count.
+  // This handles cases like "getScenarioDisplayState(scenario, undefined, undefined, 'entitysha123', undefined)"
+  // matching "getScenarioDisplayState(scenario, undefined, undefined, entitySha, undefined)"
+  const multiArgWithLiteralMatch = key.match(
+    /^([a-zA-Z_][a-zA-Z0-9_.]*)\s*\((.+)\)$/,
+  );
+  if (multiArgWithLiteralMatch) {
+    const funcPath = multiArgWithLiteralMatch[1];
+    const argsStr = multiArgWithLiteralMatch[2];
+    // Check if any argument is a string literal
+    const hasLiteralArg = /'[^']*'|"[^"]*"/.test(argsStr);
+    if (hasLiteralArg) {
+      for (const expected of expectedKeys) {
+        // Match if expected key starts with the same function path
+        if (expected.startsWith(funcPath + '(')) {
+          return expected;
+        }
+      }
+    }
+  }
+
   return null;
 }
 

package/analyzer-template/project/runAnalysis.ts

@@ -313,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,
@@ -335,6 +339,7 @@ export default async function runAnalysis({
         desiredAnalyses,
         force,
         fileStore,
+        onAnalysisProducing: () => controller?.setAnalysisProducingPhase(),
       });
     }
 
@@ -355,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/start.ts

@@ -1,4 +1,5 @@
 import 'dotenv/config';
+import { once } from 'events';
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
 import {
@@ -16,7 +17,8 @@ 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,
@@ -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(
             {
@@ -279,6 +313,9 @@ async function main({
               : envConfig.entityShas,
           full: orchestrateCapture === 'local-sequential',
           taskRunner,
+          // Poll faster in local mode - no DB load concerns like in cloud
+          pollingInterval:
+            orchestrateCapture === 'local-sequential' ? 5 * 1000 : undefined,
           // Always track capture progress on the commit, even when not filtering by it.
           metadataCommit: sharedContext.commit ?? sharedContext.branchCommit,
         });

package/analyzer-template/project/startScenarioCapture.ts

@@ -6,6 +6,7 @@ import writeUniversalMocks from './writeUniversalMocks';
 import writeScenario from './writeScenario';
 import writeSimpleRoot from './writeSimpleRoot';
 import writeCodeYamPage from './writeCodeYamPage';
+import writeClientLogRoute from './writeClientLogRoute';
 import {
   runMultiScenarioServer,
   ScenarioToCapture,
@@ -497,6 +498,14 @@ export async function startScenarioCapture({
       );
       allGeneratedFiles.push(codeyamPagePath);
 
+      // Write client-log API route so client-side errors appear in the server log
+      const clientLogPath = await writeClientLogRoute(
+        project,
+        framework,
+        analysis.filePath,
+      );
+      if (clientLogPath) allGeneratedFiles.push(clientLogPath);
+
       // Persist file tracking for crash/debug recovery
       writeTrackingFile(allGeneratedFiles, backupFiles);
     }

package/analyzer-template/project/writeClientLogRoute.ts

@@ -0,0 +1,125 @@
+import { Project, ProjectFramework } from '~codeyam/types';
+import { findWebAppForFile, PROJECT_RELATIVE_PATH } from '~codeyam/utils';
+import writeFile from '../common/writeFile';
+import * as path from 'path';
+
+/**
+ * Writes a client-log API route to the project so that client-side errors
+ * (window.onerror, unhandledrejection, console.error) are reported back to
+ * the server log where they can be read from the terminal.
+ *
+ * The route receives JSON POST requests and console.log's them, which sends
+ * the output to the dev server's stdout (captured in the server log file).
+ */
+export default async function writeClientLogRoute(
+  project: Project,
+  framework: ProjectFramework,
+  analysisFilePath?: string,
+) {
+  const relativePath = PROJECT_RELATIVE_PATH;
+  const fullAppPath = getFullAppPath(project, analysisFilePath);
+
+  let routePath: string;
+  let content: string;
+
+  switch (framework) {
+    case ProjectFramework.Remix:
+    case ProjectFramework.CRA:
+    case ProjectFramework.CodeYam:
+      routePath = `${relativePath}/${fullAppPath}/routes/api.client-log.ts`;
+      content = getRemixRoute();
+      break;
+    case ProjectFramework.Next:
+      routePath = `${relativePath}/${fullAppPath}/api/client-log/route.ts`;
+      content = getNextAppRoute();
+      break;
+    case ProjectFramework.NextPages:
+      routePath = `${relativePath}/pages/api/client-log.ts`;
+      content = getNextPagesRoute();
+      break;
+    default:
+      return;
+  }
+
+  await writeFile(routePath, content);
+  return routePath;
+}
+
+function getFullAppPath(project: Project, analysisFilePath?: string): string {
+  if (analysisFilePath) {
+    const webapp = findWebAppForFile(
+      analysisFilePath,
+      project.metadata?.webapps ?? [],
+    );
+    if (webapp) {
+      const webappPath = webapp.path === '.' ? '' : webapp.path;
+      const appDirectory = webapp.appDirectory ?? 'app';
+      return webappPath ? path.join(webappPath, appDirectory) : appDirectory;
+    }
+  }
+  const firstWebapp = project.metadata?.webapps?.[0];
+  if (firstWebapp) {
+    const webappPath = firstWebapp.path === '.' ? '' : firstWebapp.path;
+    const appDirectory = firstWebapp.appDirectory ?? 'app';
+    return webappPath ? path.join(webappPath, appDirectory) : appDirectory;
+  }
+  return 'app';
+}
+
+function formatLogEntry(): string {
+  return `
+function formatEntry(body) {
+  const ts = new Date().toLocaleString();
+  const scenario = body.scenario ? ' [' + body.scenario + ']' : '';
+  const type = (body.type || 'error').toUpperCase();
+  const lines = ['[' + ts + '] [CLIENT ' + type + ']' + scenario + ' ' + (body.message || 'Unknown error')];
+  if (body.stack) lines.push(body.stack);
+  if (body.url) lines.push('  at ' + body.url);
+  return lines.join('\\n');
+}`;
+}
+
+function getRemixRoute(): string {
+  return `// Auto-generated by CodeYam — client error reporting endpoint
+${formatLogEntry()}
+
+export async function action({ request }) {
+  try {
+    const body = await request.json();
+    console.log(formatEntry(body));
+  } catch (e) {}
+  return new Response('ok', { status: 200 });
+}
+`;
+}
+
+function getNextAppRoute(): string {
+  return `// Auto-generated by CodeYam — client error reporting endpoint
+import { NextResponse } from 'next/server';
+${formatLogEntry()}
+
+export async function POST(request: Request) {
+  try {
+    const body = await request.json();
+    console.log(formatEntry(body));
+  } catch (e) {}
+  return NextResponse.json({ ok: true });
+}
+`;
+}
+
+function getNextPagesRoute(): string {
+  return `// Auto-generated by CodeYam — client error reporting endpoint
+import type { NextApiRequest, NextApiResponse } from 'next';
+${formatLogEntry()}
+
+export default async function handler(req: NextApiRequest, res: NextApiResponse) {
+  if (req.method !== 'POST') return res.status(405).end();
+  try {
+    const body = typeof req.body === 'string' ? JSON.parse(req.body) : req.body;
+    console.log(formatEntry(body));
+  } catch (e) {}
+  res.status(200).json({ ok: true });
+}
+`;
+}