@codeyam/codeyam-cli 0.1.0-staging.da5baf5 → 0.1.0-staging.dd216e0

package/analyzer-template/project/startServer.ts

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

package/analyzer-template/project/updateCommitBackgroundJob.ts

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

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

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

package/analyzer-template/project/writeMockDataTsx.ts

@@ -101,16 +101,25 @@ const shouldBeMap = (mockKey: string, mergedDataStructure: any): boolean => {
 };
 
 /**
- * Normalize a function call key by stripping arguments and type parameters.
+ * Normalize a function call key by stripping arguments and type parameters,
+ * but preserving variable qualifiers (::variableName suffix).
  * e.g., "useLastLogLine(projectSlug, !!simulatingEntitySha)" -> "useLastLogLine()"
  * e.g., "useLoaderData<typeof loader>()" -> "useLoaderData()"
+ * e.g., "useFetcher()::entityDiffFetcher" -> "useFetcher()::entityDiffFetcher" (preserved)
+ * e.g., "useFetcher<T>()::entityDiffFetcher" -> "useFetcher()::entityDiffFetcher"
  */
 const normalizeKey = (key: string): string => {
-  if (key.endsWith(')') && key.includes('(')) {
+  // Check for variable qualifier (::variableName)
+  const qualifierMatch = key.match(/::[a-zA-Z_][a-zA-Z0-9_]*$/);
+  const qualifier = qualifierMatch ? qualifierMatch[0] : '';
+  const keyWithoutQualifier = qualifier ? key.slice(0, -qualifier.length) : key;
+
+  // Check if key ends with ) - indicating a function call (after removing qualifier)
+  if (keyWithoutQualifier.endsWith(')') && keyWithoutQualifier.includes('(')) {
     // Strip arguments: "foo(a, b)" -> "foo()"
-    const normalized = key.split('(')[0] + '()';
+    const normalized = keyWithoutQualifier.split('(')[0] + '()';
     // Strip type parameters: "foo<T>()" -> "foo()"
-    return cleanOutTypes(normalized);
+    return cleanOutTypes(normalized) + qualifier;
   }
   return key;
 };
@@ -162,11 +171,46 @@ function extractAllKeys(obj: JsonTypeDefinition | undefined): string[] {
   return keys;
 }
 
+/**
+ * Bare type markers that indicate a function was detected but has no actual return data.
+ * These should be filtered out of mock data output since they're just type hints.
+ */
+const BARE_TYPE_MARKERS = ['function', 'async-function'];
+
+/**
+ * Check if a value is a bare function type marker that should be filtered out.
+ * These markers indicate the LLM detected a function but couldn't generate meaningful mock data.
+ *
+ * Also catches TypeScript union types containing function, like:
+ * - "function | null"
+ * - "function | undefined"
+ * - "async-function | null"
+ */
+const isBareTypeMarker = (value: unknown): boolean => {
+  if (typeof value !== 'string') return false;
+
+  // Check for exact bare type markers
+  if (BARE_TYPE_MARKERS.includes(value)) return true;
+
+  // Check for TypeScript union types containing function type markers
+  // e.g., "function | null", "function | undefined", "async-function | null"
+  if (value.includes('|')) {
+    const parts = value.split('|').map((p) => p.trim());
+    // If any part is a bare type marker, treat the whole thing as a type marker
+    return parts.some((part) => BARE_TYPE_MARKERS.includes(part));
+  }
+
+  return false;
+};
+
 /**
  * Normalize mock data by merging entries that have the same normalized function name.
  * e.g., "useLastLogLine(projectSlug, !!simulatingEntitySha)" and
  *       "useLastLogLine(projectSlug, currentRunActive)" both become "useLastLogLine()"
  * Their values are deep-merged to ensure all attributes are accounted for.
+ *
+ * Also filters out bare function type markers like "validateInputs()": "function"
+ * which are just type hints without actual mock data.
  */
 const normalizeMockData = (
   mockData: Record<string, unknown>,
@@ -183,16 +227,40 @@ const normalizeMockData = (
     keyMapping.get(normKey)!.push(key);
   }
 
+  // Helper to check if a value is an empty object
+  const isEmptyObject = (value: unknown): boolean => {
+    return (
+      value !== null &&
+      typeof value === 'object' &&
+      !Array.isArray(value) &&
+      Object.keys(value as object).length === 0
+    );
+  };
+
   // Second pass: merge values for duplicate normalized keys
   for (const [normKey, originalKeys] of keyMapping) {
     if (originalKeys.length === 1) {
       // No duplicates, use the original key (may be normalized or not based on safeString)
-      normalized[normKey] = mockData[originalKeys[0]];
+      const value = mockData[originalKeys[0]];
+      // Skip bare type markers like "function" or "async-function"
+      if (isBareTypeMarker(value)) {
+        continue;
+      }
+      // Skip empty objects - these cause "Objects are not valid as a React child" errors
+      // when mock functions return them (e.g., CheckCircle2() from lucide-react)
+      if (isEmptyObject(value)) {
+        continue;
+      }
+      normalized[normKey] = value;
     } else {
       // Multiple keys normalize to the same value - merge them
       let mergedValue: unknown = {};
       for (const origKey of originalKeys) {
         const value = mockData[origKey];
+        // Skip bare type markers when merging
+        if (isBareTypeMarker(value)) {
+          continue;
+        }
         if (
           value &&
           typeof value === 'object' &&
@@ -210,7 +278,17 @@ const normalizeMockData = (
           mergedValue = value;
         }
       }
-      normalized[normKey] = mergedValue;
+      // Only add if we have actual data (not just filtered type markers)
+      if (
+        mergedValue !== undefined &&
+        !isBareTypeMarker(mergedValue) &&
+        !(
+          typeof mergedValue === 'object' &&
+          Object.keys(mergedValue as object).length === 0
+        )
+      ) {
+        normalized[normKey] = mergedValue;
+      }
     }
   }
 
@@ -232,8 +310,11 @@ const jsonToCode = (
     if (Array.isArray(json)) {
       const arrayStrings: string[] = [];
       for (const item of json) {
-        if (!item) continue;
-        if (typeof item === 'object') {
+        // Skip undefined but preserve null (important for ref props)
+        if (item === undefined) continue;
+        if (item === null) {
+          arrayStrings.push('null');
+        } else if (typeof item === 'object') {
           arrayStrings.push(jsonToCode(item, level + 1, mergedDataStructure));
         } else {
           arrayStrings.push(`"${safeString(item, level)}"`);
@@ -248,8 +329,30 @@ const jsonToCode = (
       // e.g., submit({ a }) and submit({ b }) should both become "submit" once
       const seenNormalizedFuncNames = new Set<string>();
 
+      // Pre-scan to identify plain keys that have function-call versions
+      // These plain keys should be skipped because the function-call version
+      // will be normalized to the same key name
+      // e.g., if both "push" and "push(`/path`)" exist, skip the plain "push"
+      const plainKeysWithFunctionCallVersions = new Set<string>();
+      for (const key of Object.keys(jsonObj)) {
+        if (key.includes('(') && key.endsWith(')')) {
+          const funcName = key.split('(')[0];
+          // Check if a plain key with this name exists
+          if (funcName in jsonObj && !funcName.includes('(')) {
+            plainKeysWithFunctionCallVersions.add(funcName);
+          }
+        }
+      }
+
       for (const key of Object.keys(jsonObj)) {
-        if (jsonObj[key] === undefined || jsonObj[key] === null) continue;
+        if (jsonObj[key] === undefined) continue;
+
+        // Preserve explicit null values - components check `value !== null`
+        // to distinguish "not loaded" (undefined) from "explicitly null"
+        if (jsonObj[key] === null) {
+          keyStrings.push(`${levelSpacing}"${safeString(key, level)}": null`);
+          continue;
+        }
 
         if (Array.isArray(jsonObj[key])) {
           if (key === '~~codeyam-jsx~~') {
@@ -389,6 +492,15 @@ const jsonToCode = (
               );
             }
           } else {
+            // Skip plain keys that have function-call versions (at deeper nesting levels)
+            // e.g., if both "t" and "t('common.close')" exist, skip the plain "t" object
+            // because the function-call version will be normalized to "t"
+            if (level > 2 && plainKeysWithFunctionCallVersions.has(key)) {
+              console.log(
+                `CodeYam: Skipping plain object key "${key}" (has function-call version that will be normalized)`,
+              );
+              continue;
+            }
             keyStrings.push(
               `${levelSpacing}"${safeString(key, level)}": ${jsonToCode(jsonObj[key], level + 1, mergedDataStructure)}`,
             );
@@ -418,24 +530,68 @@ const jsonToCode = (
           if (key.includes('(') && key.endsWith(')') && level > 2) {
             const funcName = key.split('(')[0];
 
+            // Extract the function arguments to check if they're string literals
+            const argsMatch = key.match(/\((.+)\)$/);
+            const args = argsMatch ? argsMatch[1].trim() : '';
+            // Check if the argument is a simple string literal like "common.close" or 'common.close'
+            // These are static lookup keys (e.g., translation functions) and should NOT be normalized
+            const isStringLiteralArg = /^["'][^"']*["']$/.test(args);
+
+            if (isStringLiteralArg) {
+              // DON'T normalize - preserve the full key for static lookups (e.g., translations)
+              // This allows constructMockCode to generate a dispatch function that looks up by key
+              keyStrings.push(
+                `${levelSpacing}"${safeString(key, level)}": "${safeString(stringValue, level)}"`,
+              );
+              console.log(
+                `CodeYam: Preserving string-literal function key for lookup: "${key}": "${stringValue}"`,
+              );
+              continue;
+            }
+
             // Skip if we've already added this normalized function name
             if (seenNormalizedFuncNames.has(funcName)) {
               continue;
             }
+
+            // Skip TypeScript union type markers like "function | null" - these are type hints
+            // that would produce invalid JavaScript if output as-is.
+            // Note: We only skip UNION types here (containing '|'), not bare 'function'
+            // because bare 'function' is transformed to () => {} below.
+            // Note: This must come BEFORE seenNormalizedFuncNames.add() so that
+            // if another key with the same funcName has actual data, it can be used.
+            if (stringValue.includes('|') && isBareTypeMarker(stringValue)) {
+              continue;
+            }
+
             seenNormalizedFuncNames.add(funcName);
 
             // Check if the string value looks like a function expression
+            // Be careful not to match descriptive strings like "function listening" -
+            // a valid function expression must have parentheses like function(), function name(), or function (
             const looksLikeFunction =
               stringValue.includes('=>') ||
-              stringValue.startsWith('function') ||
-              stringValue.startsWith('async');
+              /^function\s*[\w]*\s*\(/.test(stringValue) ||
+              /^async\s+function\s*[\w]*\s*\(/.test(stringValue) ||
+              /^async\s*\(/.test(stringValue);
+
+            // Check if the string value looks like a Promise expression
+            // e.g., "Promise.resolve()", "new Promise(...)", etc.
+            const looksLikePromise =
+              stringValue.startsWith('Promise.') ||
+              stringValue.startsWith('new Promise');
 
             // Handle special type indicators that need transformation
             let outputValue: string;
-            if (stringValue === 'promise') {
-              outputValue = 'Promise.resolve()';
+            if (stringValue === 'promise' || looksLikePromise) {
+              // The key is a function call (e.g., "revalidate()"), so output a function
+              // that returns a Promise, not the Promise itself
+              const promiseExpr = looksLikePromise
+                ? stringValue
+                : 'Promise.resolve()';
+              outputValue = `() => ${promiseExpr}`;
               console.log(
-                `CodeYam: Nested func transform (string->Promise): "${key}" -> "${funcName}": Promise.resolve()`,
+                `CodeYam: Nested func transform (string->Promise): "${key}" -> "${funcName}": () => ${promiseExpr}`,
               );
             } else if (stringValue === 'function') {
               outputValue = '() => {}';
@@ -459,11 +615,34 @@ const jsonToCode = (
               `${levelSpacing}"${safeString(funcName, level)}": ${outputValue}`,
             );
           } else {
+            // Skip plain keys that have function-call versions (at the same nesting level where
+            // function-call keys get normalized). The function-call version will be output instead.
+            // e.g., if both "push" and "push(`/path`)" exist, skip "push" - the other normalizes to "push"
+            if (level > 2 && plainKeysWithFunctionCallVersions.has(key)) {
+              console.log(
+                `CodeYam: Skipping plain key "${key}" (has function-call version that will be normalized)`,
+              );
+              continue;
+            }
+            // Skip bare type markers like "function", "function | null", etc.
+            // For plain keys (not function signatures), these are just type hints
+            // that would produce invalid JavaScript if output as-is.
+            if (isBareTypeMarker(stringValue)) {
+              continue;
+            }
             keyStrings.push(
               `${levelSpacing}"${safeString(key, level)}": "${safeString(stringValue, level)}"`,
             );
           }
         } else {
+          // Skip plain keys that have function-call versions (at the same nesting level where
+          // function-call keys get normalized)
+          if (level > 2 && plainKeysWithFunctionCallVersions.has(key)) {
+            console.log(
+              `CodeYam: Skipping plain key "${key}" (has function-call version that will be normalized)`,
+            );
+            continue;
+          }
           keyStrings.push(
             `${levelSpacing}"${safeString(key, level)}": ${safeString(String(jsonObj[key]), level)}`,
           );
@@ -638,13 +817,44 @@ function serialize(obj) {
         
         // Handle functions
         if (typeof value === 'function') {
-            const fnStr = value.toString();
+            let fnStr;
+            try {
+                fnStr = value.toString();
+            } catch (toStringErr) {
+                console.warn('CodeYam: Function.toString() threw error:', toStringErr, 'function name:', value.name);
+                return {
+                    __type: TYPE_MARKERS.FUNCTION,
+                    value: '() => {}',
+                    name: value.name || 'anonymous'
+                };
+            }
+
+            // Defensive check: ensure fnStr is actually a string
+            if (typeof fnStr !== 'string') {
+                console.warn('CodeYam: Function.toString() returned non-string:', typeof fnStr, fnStr, 'function name:', value.name);
+                return {
+                    __type: TYPE_MARKERS.FUNCTION,
+                    value: '() => {}',
+                    name: value.name || 'anonymous'
+                };
+            }
+
             // Check if it's an arrow function
             if (fnStr.includes('=>')) {
+                const arrowIndex = fnStr.indexOf('=>');
+                // Extra safety: verify indexOf returned a valid index
+                if (arrowIndex === -1) {
+                    console.warn('CodeYam: Arrow function detection inconsistency - includes found => but indexOf returned -1. fnStr:', fnStr);
+                    return {
+                        __type: TYPE_MARKERS.FUNCTION,
+                        value: fnStr,
+                        name: value.name
+                    };
+                }
                 return {
                     __type: TYPE_MARKERS.ARROW_FUNCTION,
-                    params: fnStr.substring(0, fnStr.indexOf('=>')).trim(),
-                    body: fnStr.substring(fnStr.indexOf('=>') + 2).trim()
+                    params: fnStr.substring(0, arrowIndex).trim(),
+                    body: fnStr.substring(arrowIndex + 2).trim()
                 };
             }
             return {
@@ -738,17 +948,23 @@ function deserialize(jsonString) {
                 
             case TYPE_MARKERS.FUNCTION:
                 try {
-                    // Handle named functions
+                    // Handle named functions - extract params and body properly
                     if (value.name && value.name !== 'anonymous') {
-                        const functionBody = value.value.slice(value.value.indexOf('{') + 1, value.value.lastIndexOf('}'));
-                        return new Function(\`return function \${value.name}\${functionBody}\`)();
+                        const parenStart = value.value.indexOf('(');
+                        const braceStart = value.value.indexOf('{');
+                        if (parenStart !== -1 && braceStart !== -1 && parenStart < braceStart) {
+                            // Extract params (between first ( and the { that starts the body)
+                            const params = value.value.slice(parenStart, braceStart).trim();
+                            const functionBody = value.value.slice(braceStart + 1, value.value.lastIndexOf('}'));
+                            return new Function(\`return function \${value.name}\${params}{\${functionBody}}\`)();
+                        }
                     }
-                    // Handle anonymous functions
+                    // Handle anonymous functions or fallback
                     return new Function(\`return \${value.value}\`)();
                 } catch (e) {
                     console.warn('Error deserializing function:', e);
-                    return function() { 
-                        return 'Error: Function could not be deserialized'; 
+                    return function() {
+                        return 'Error: Function could not be deserialized';
                     };
                 }
                 

package/analyzer-template/project/writeScenario.ts

@@ -1,6 +1,6 @@
 import { Analysis, ProjectFramework, Scenario } from '~codeyam/types';
 import { CODEYAM_MOCKS_DIRNAME, pushAnalysisError } from '~codeyam/utils';
-import { loadFile, upsertAnalysesWithScenarios } from '~codeyam/supabase';
+import { loadFile, upsertAnalysesWithScenarios } from '~codeyam/database';
 import writeScenarioFiles from './writeScenarioFiles';
 import { ImmutableAnalysisContext, ProjectAnalyzer } from '~codeyam/analyze';
 import getAppPath from './getAppPath';