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

package/background/src/lib/virtualized/project/startServer.js

@@ -1,15 +1,26 @@
 import getPort from 'get-port';
 import execAsync from "../common/execAsync.js";
-import { ProjectFramework } from "../../../../../packages/types/index.js";
 import { Socket } from 'net';
 import { awsLogDebugLevel } from "../../../../../packages/utils/index.js";
-export async function startServer({ startCommand, packageManager, onStart, onError, framework, projectPort, }) {
+/**
+ * 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, onStart, onError, projectPort, }) {
     const acceptableErrorsRegexes = [
         /robots\.txt/,
         /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/,
@@ -18,8 +29,20 @@ export async function startServer({ startCommand, packageManager, onStart, onErr
         /Your project has\s+`([^`]+)`\s+installed as a dependency,\s+please use the built-in/,
     ];
     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}`);
@@ -45,7 +68,6 @@ export async function startServer({ startCommand, packageManager, onStart, onErr
                     resolve(true);
                 });
                 socket.connect(port, 'localhost');
-                // Don't leave socket hanging
                 timer.current = setTimeout(() => {
                     console.log(`CodeYam: checkPort: Timeout`);
                     socket.destroy();
@@ -64,68 +86,19 @@ export async function startServer({ startCommand, packageManager, onStart, onErr
                 await new Promise((resolve) => setTimeout(resolve, 1000));
             }
         };
-        // 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;
-                }
-            }
-            // 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 };
+        // Build command from startCommand (substituting $PORT)
+        const command = startCommand.command;
+        const args = startCommand.args.map((arg) => arg.replace(/\$PORT/g, projectPort.toString()));
+        // Handle env: $PORT substitution
+        let env = {
+            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());
                 }
             }
         }
@@ -138,7 +111,6 @@ export async function startServer({ startCommand, packageManager, onStart, onErr
                 env,
                 workingDir: '../project',
                 acceptableErrorsRegexes,
-                // logErrors: false, // we do more selective logging ourselves
                 onError,
                 processName: 'local-project-server',
             }),
@@ -150,7 +122,7 @@ export async function startServer({ startCommand, packageManager, onStart, onErr
     }
     catch (error) {
         console.log(`CodeYam Error: Error executing start script: ${error.message}`);
-        throw error; // Rethrow the error to be caught in the main function
+        throw error;
     }
 }
 //# sourceMappingURL=startServer.js.map

package/background/src/lib/virtualized/project/startServer.js.map

@@ -1 +1 @@
-{"version":3,"file":"startServer.js","sourceRoot":"","sources":["../../../../../../../background/src/lib/virtualized/project/startServer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"startServer.js","sourceRoot":"","sources":["../../../../../../../background/src/lib/virtualized/project/startServer.ts"],"names":[],"mappings":"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"}

package/background/src/lib/virtualized/project/updateCommitBackgroundJob.js

@@ -1,4 +1,4 @@
-import { updateBackgroundJobProgress } from "../../../../../packages/supabase/index.js";
+import { updateBackgroundJobProgress } from "../../../../../packages/database/index.js";
 export default async function updateCommitBackgroundJob(backgroundJob, stepName) {
     backgroundJob = await updateBackgroundJobProgress(backgroundJob, {
         initiated: new Date().toISOString(),

package/background/src/lib/virtualized/project/utils/errorHandling.js

@@ -1,5 +1,5 @@
 import emailErrorReport from "../emailErrorReport.js";
-import { updateFreshAnalysisStatus } from "../../../../../../packages/supabase/index.js";
+import { updateFreshAnalysisStatus } from "../../../../../../packages/database/index.js";
 export async function recordErrorMessageForScenario(analysis, scenario, error, shouldEmailReport = true) {
     try {
         await updateFreshAnalysisStatus(analysis.id, (freshStatus, _inAnalysis) => {

package/background/src/lib/virtualized/project/writeMockDataTsx.js

@@ -80,16 +80,24 @@ const shouldBeMap = (mockKey, mergedDataStructure) => {
     return false;
 };
 /**
- * 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) => {
-    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;
 };
@@ -131,11 +139,43 @@ function extractAllKeys(obj) {
     }
     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) => {
+    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) => {
     const normalized = {};
@@ -148,17 +188,38 @@ const normalizeMockData = (mockData) => {
         }
         keyMapping.get(normKey).push(key);
     }
+    // Helper to check if a value is an empty object
+    const isEmptyObject = (value) => {
+        return (value !== null &&
+            typeof value === 'object' &&
+            !Array.isArray(value) &&
+            Object.keys(value).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 = {};
             for (const origKey of originalKeys) {
                 const value = mockData[origKey];
+                // Skip bare type markers when merging
+                if (isBareTypeMarker(value)) {
+                    continue;
+                }
                 if (value &&
                     typeof value === 'object' &&
                     !Array.isArray(value) &&
@@ -172,7 +233,13 @@ const normalizeMockData = (mockData) => {
                     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).length === 0)) {
+                normalized[normKey] = mergedValue;
+            }
         }
     }
     return normalized;
@@ -186,9 +253,13 @@ const jsonToCode = (json, level = 1, mergedDataStructure, currentKey) => {
         if (Array.isArray(json)) {
             const arrayStrings = [];
             for (const item of json) {
-                if (!item)
+                // Skip undefined but preserve null (important for ref props)
+                if (item === undefined)
                     continue;
-                if (typeof item === 'object') {
+                if (item === null) {
+                    arrayStrings.push('null');
+                }
+                else if (typeof item === 'object') {
                     arrayStrings.push(jsonToCode(item, level + 1, mergedDataStructure));
                 }
                 else {
@@ -203,9 +274,29 @@ const jsonToCode = (json, level = 1, mergedDataStructure, currentKey) => {
             // Track normalized function names to avoid duplicate keys in output
             // e.g., submit({ a }) and submit({ b }) should both become "submit" once
             const seenNormalizedFuncNames = new Set();
+            // 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();
             for (const key of Object.keys(jsonObj)) {
-                if (jsonObj[key] === undefined || jsonObj[key] === null)
+                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)
+                    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~~') {
                         return `<>${jsonObj[key].join('')}</>`;
@@ -310,6 +401,13 @@ const jsonToCode = (json, level = 1, mergedDataStructure, currentKey) => {
                         }
                     }
                     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)}`);
                     }
                 }
@@ -337,20 +435,54 @@ const jsonToCode = (json, level = 1, mergedDataStructure, currentKey) => {
                     // Only apply at deeper nesting levels (level > 2)
                     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;
-                        if (stringValue === 'promise') {
-                            outputValue = 'Promise.resolve()';
-                            console.log(`CodeYam: Nested func transform (string->Promise): "${key}" -> "${funcName}": 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}": () => ${promiseExpr}`);
                         }
                         else if (stringValue === 'function') {
                             outputValue = '() => {}';
@@ -368,10 +500,29 @@ const jsonToCode = (json, level = 1, mergedDataStructure, currentKey) => {
                         keyStrings.push(`${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)}`);
                 }
             }
@@ -502,13 +653,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 {
@@ -602,17 +784,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';
                     };
                 }