@codeyam/codeyam-cli 0.1.0-staging.8aea589 → 0.1.0-staging.bbe4da9

package/analyzer-template/project/constructMockCode.ts

@@ -4,8 +4,9 @@ import {
   functionArguments,
   cleanOutBoundary,
   fillInDirectSchemaGapsAndUnknowns,
+  removeDuplicateFunctionCalls,
 } from '~codeyam/ai';
-import { DataStructure, DeepReadonly } from '~codeyam/types';
+import { DataStructure, DeepReadonly, EntityType } from '~codeyam/types';
 
 interface ReturnValuePart {
   name: string;
@@ -18,6 +19,7 @@ interface ReturnValuePart {
   nested?: ReturnValuePart[];
   isAsyncFunction?: boolean;
   isStructural?: boolean;
+  hasNoReturnData?: boolean; // true when function has only signature entries, no functionCallReturnValue
   // Maps literal argument values to their specific nested structures for conditional dispatch
   argVariants?: Map<string, ReturnValuePart[]>;
 }
@@ -162,6 +164,7 @@ function isValidKey(key: string) {
 export default function constructMockCode(
   mockName: string,
   dependencySchemas: DeepReadonly<DataStructure['dependencySchemas']>,
+  entityType?: EntityType,
 ) {
   const mockNameParts = splitOutsideParenthesesAndArrays(mockName);
 
@@ -193,9 +196,10 @@ export default function constructMockCode(
         relevantReturnValueSchema = fillInDirectSchemaGapsAndUnknowns({
           schema: dependencySchemas[filePath][entityName]?.returnValueSchema,
         });
-        // NOTE: Temporarily disabled clearAttributesFromMapping as it deletes
+        // NOTE: clearAttributesFromMapping is disabled because it deletes
         // method calls on arrays (like .eq() after functionCallReturnValue: 'array')
-        // clearAttributesFromMapping(relevantReturnValueSchema)
+        // However, we still need to remove duplicate function calls that create invalid syntax
+        removeDuplicateFunctionCalls(relevantReturnValueSchema);
         dataStructureValue = relevantReturnValueSchema?.[dataStructurePath];
         break;
       }
@@ -273,7 +277,15 @@ export default function constructMockCode(
       }
 
       const addReturnValueFunctionAccessor = (dataPath: string) => {
-        if (returnValue.returnsFunctionArgs) {
+        // Add function call accessor if:
+        // - There are actual arguments, OR
+        // - This is a callable (not a method that returns an array directly)
+        // For methods like getAll() that return arrays, the data is at ["getAll()"] not ["getAll()"]["()"]
+        if (
+          returnValue.returnsFunctionArgs &&
+          (returnValue.returnsFunctionArgs.length > 0 ||
+            !returnValue.returnsFunctionArray)
+        ) {
           if (returnValue.isArray) {
             dataPath = `${dataPath}${optionalAccess('[0]')}`;
           }
@@ -313,6 +325,7 @@ export default function constructMockCode(
         returnsFunctionArgs,
         returnsFunctionArray,
         isAsyncFunction,
+        hasNoReturnData,
       } = returnValue;
 
       const nestedContent: (string | undefined)[] = (nested ?? []).map(
@@ -325,9 +338,53 @@ export default function constructMockCode(
         },
       );
 
+      // Array prototype methods that should be ignored when building mocks
+      // (these work on any array - we don't need to mock them)
+      const ARRAY_PROTOTYPE_METHODS = new Set([
+        'at',
+        'concat',
+        'copyWithin',
+        'entries',
+        'every',
+        'fill',
+        'filter',
+        'find',
+        'findIndex',
+        'findLast',
+        'findLastIndex',
+        'flat',
+        'flatMap',
+        'forEach',
+        'includes',
+        'indexOf',
+        'join',
+        'keys',
+        'lastIndexOf',
+        'map',
+        'pop',
+        'push',
+        'reduce',
+        'reduceRight',
+        'reverse',
+        'shift',
+        'slice',
+        'some',
+        'sort',
+        'splice',
+        'toLocaleString',
+        'toReversed',
+        'toSorted',
+        'toSpliced',
+        'toString',
+        'unshift',
+        'values',
+        'with',
+        'length',
+      ]);
+
       const levelContentItems = [];
       // Add spread for data paths when:
-      // - Not a function returning an array
+      // - Not a function returning an array, OR function returns array with custom methods
       // - Has function args OR not an array
       // - Not structural, OR is a structural [0] element with nested content
       //   (array elements with nested functions need their other properties spread)
@@ -336,8 +393,20 @@ export default function constructMockCode(
         returnValue.name === '[0]' &&
         nested &&
         nested.length > 0;
+      // Check if function returns array but has custom methods (not just array prototype methods)
+      // Excludes array indices like [0], [1], [] which are not methods
+      const hasCustomMethodsOnArrayReturn =
+        returnsFunctionArray &&
+        nested &&
+        nested.length > 0 &&
+        nested.some((n) => {
+          // Skip array indices - they're not methods
+          if (n.name.match(/^\[\d*\]$/)) return false;
+          const methodName = n.name.replace(/[<(].*$/, '');
+          return !ARRAY_PROTOTYPE_METHODS.has(methodName);
+        });
       if (
-        !returnsFunctionArray &&
+        (!returnsFunctionArray || hasCustomMethodsOnArrayReturn) &&
         (returnsFunctionArgs || !isArray) &&
         (!returnValue.isStructural || isStructuralArrayElementWithNested)
       ) {
@@ -352,14 +421,35 @@ export default function constructMockCode(
           .join(', ');
         let funcContents = '';
         if (returnsFunctionArray) {
-          if (levelContents.length === 0) {
+          if (hasNoReturnData) {
+            // Function has no return data (only signatures) - return empty array
+            funcContents = 'return []';
+          } else if (levelContents.length === 0 && dataPaths.length === 1) {
+            // When returning an array with no nested content, return the data path directly
+            // (the data path points to the array in scenario data)
+            funcContents = `return ${dataPaths[0]}`;
+          } else if (levelContents.length === 0) {
             funcContents = 'return []';
           } else {
             funcContents = `return [\n${indent(levelContents)}\n]`;
           }
         } else {
+          // Check if function has no actual return data (only signatures)
+          const hasNestedItems = nested && nested.length > 0;
+          const hasActualNestedContent =
+            nestedContent.filter(Boolean).length > 0;
+
           if (levelContentItems.length === 1 && dataPaths.length === 1) {
-            funcContents = `return ${dataPaths[0]}`;
+            if (
+              hasNoReturnData ||
+              (hasNestedItems && !hasActualNestedContent)
+            ) {
+              // Function has no return data (only signatures) - return empty array
+              funcContents = 'return []';
+            } else {
+              // Has return data - return data path
+              funcContents = `return ${dataPaths[0]}`;
+            }
           } else {
             funcContents = `return {\n${indent(levelContents)}\n}`;
           }
@@ -372,6 +462,17 @@ export default function constructMockCode(
         }
       }
 
+      // Check if all nested items are array prototype methods
+      const hasOnlyArrayPrototypeMethods =
+        returnsFunctionArray &&
+        nested &&
+        nested.length > 0 &&
+        nested.every((n) => {
+          // Extract method name before type params and args (e.g., "reduce<...>(...)" -> "reduce")
+          const methodName = n.name.replace(/[<(].*$/, '');
+          return ARRAY_PROTOTYPE_METHODS.has(methodName);
+        });
+
       let returnValueContents = '';
       if (
         !returnsFunctionArgs &&
@@ -379,6 +480,16 @@ export default function constructMockCode(
         dataPaths.length === 1
       ) {
         returnValueContents = dataPaths[0];
+      } else if (
+        returnsFunctionArray &&
+        dataPaths.length === 1 &&
+        !root &&
+        (!nested || nested.length === 0 || hasOnlyArrayPrototypeMethods)
+      ) {
+        // Nested method returns an array - return the data path directly
+        // Only if nested content is empty or only contains array prototype methods
+        // (like .reduce() which work on any array - we don't need to mock them)
+        returnValueContents = dataPaths[0];
       } else {
         if (isArray) {
           // When GENERIC array (using []) has nested content (like functions that need wrapping),
@@ -687,6 +798,25 @@ export default function constructMockCode(
           if (returnValueSection.returnsFunctionArgs && value === 'array') {
             returnValueSection.returnsFunctionArray = true;
           }
+
+          // Check if this function call has actual return data in the schema
+          // If the path only has .signature entries (no .functionCallReturnValue), mark as no return data
+          // Use parts[i] (original part) instead of modified 'part' to include array indices like [1]
+          const functionCallPath = joinParenthesesAndArrays([
+            ...parts.slice(0, i),
+            parts[i], // Use original part which may include [1](args) together
+          ]);
+          // Check if there's a .functionCallReturnValue AFTER this function call path
+          const hasFunctionCallReturnValue = Object.keys(
+            relevantReturnValueSchema,
+          ).some((k) => {
+            if (!k.startsWith(functionCallPath)) return false;
+            const afterPath = k.slice(functionCallPath.length);
+            return afterPath.startsWith('.functionCallReturnValue');
+          });
+          if (!hasFunctionCallReturnValue) {
+            returnValueSection.hasNoReturnData = true;
+          }
         }
 
         if (nextIsDifferentiatedArray || hasNestedFunction) {
@@ -841,6 +971,26 @@ export default function constructMockCode(
       }
 
       if (!hasNestedFunction) {
+        // Before breaking, check if this function returns an array
+        // by looking for a functionCallReturnValue: 'array' entry in the schema
+        if (relevantPart && part.endsWith(')')) {
+          const functionReturnPath = joinParenthesesAndArrays([
+            ...parts.slice(0, i + 1),
+            RETURN_VALUE,
+          ]);
+          const returnType = relevantReturnValueSchema[functionReturnPath];
+          if (returnType === 'array') {
+            // Only set returnsFunctionArray if the array contains plain data,
+            // NOT if it contains functions (which need wrapping)
+            const arrayElementPath = `${functionReturnPath}[]`;
+            const arrayElementType =
+              relevantReturnValueSchema[arrayElementPath];
+            // If array element is a function, we need to wrap it - don't set returnsFunctionArray
+            if (arrayElementType !== 'function') {
+              relevantPart.returnsFunctionArray = true;
+            }
+          }
+        }
         break;
       }
 
@@ -884,7 +1034,47 @@ export default function constructMockCode(
 
     return `const ${mockNameParts[0]} = {\n${indent(returnParts.join(',\n'))}\n};`;
   } else if (isFunction) {
-    return `const ${mockName}ReturnValue = ${contents};\n\n${isRootAsyncFunction ? 'async ' : ''}function ${mockName}() {\n${indent(`return ${mockName}ReturnValue;`)}\n}`;
+    // For headers() and cookies() from next/headers, add common iterator methods
+    // These are needed when the mock is passed to functions that use .entries(), .keys(), etc.
+    // (e.g., Object.fromEntries(headers.entries()) in buildLegacyHeaders)
+    const needsIteratorMethods =
+      mockName === 'headers' || mockName === 'cookies';
+    let enhancedContents = contents;
+    if (needsIteratorMethods && contents.trim().startsWith('{')) {
+      // Add iterator methods that operate on the scenario data
+      const iteratorMethods = `,
+  entries: () => Object.entries(scenarios().data()?.["${mockName}()"] || {}),
+  keys: () => Object.keys(scenarios().data()?.["${mockName}()"] || {}),
+  values: () => Object.values(scenarios().data()?.["${mockName}()"] || {}),
+  forEach: (fn) => Object.entries(scenarios().data()?.["${mockName}()"] || {}).forEach(([k, v]) => fn(v, k)),
+  has: (key) => Object.prototype.hasOwnProperty.call(scenarios().data()?.["${mockName}()"] || {}, key)`;
+      // Insert before the closing brace (handle trailing whitespace)
+      enhancedContents = contents.replace(/\}\s*$/, iteratorMethods + '\n}');
+    }
+
+    // Classes need to be mocked as classes, not functions.
+    // They're used with `new ClassName(args)` which requires a proper constructor.
+    // A function mock like `function ClassName() { return value; }` doesn't work because
+    // `new ClassName("arg")` wouldn't create the expected instance.
+    // For Error subclasses (detected by name ending in "Error"), extend Error for proper error handling.
+    if (entityType === 'class') {
+      const isErrorSubclass = mockName.endsWith('Error');
+      const baseClass = isErrorSubclass ? 'Error' : 'Object';
+      const superCall = isErrorSubclass ? 'super(message);' : '';
+      const nameAssignment = isErrorSubclass
+        ? `this.name = '${mockName}';`
+        : '';
+
+      return `class ${mockName}${isErrorSubclass ? ' extends Error' : ''} {
+  constructor(message) {
+    ${superCall}
+    ${nameAssignment}
+    Object.assign(this, scenarios().data()?.["${mockName}()"] || {});
+  }
+}`;
+    }
+
+    return `const ${mockName}ReturnValue = ${enhancedContents};\n\n${isRootAsyncFunction ? 'async ' : ''}function ${mockName}() {\n${indent(`return ${mockName}ReturnValue;`)}\n}`;
   } else {
     return `const ${mockName} = ${contents}`;
   }

package/analyzer-template/project/reconcileMockDataKeys.ts

@@ -46,8 +46,10 @@ export function reconcileMockDataKeys(
  * - Extract function name and first argument(s)
  * - Ignore the last argument value (could be literal or variable)
  * - Match based on the common prefix
+ * - If key has no parentheses, try matching with "()" appended
  *
  * e.g., "eq('user_id', 'user-12345')" matches "eq('user_id', user.id)"
+ * e.g., "getAll" matches "getAll()"
  */
 function findClosestKey(key: string, expectedKeys: string[]): string | null {
   const keyBase = extractKeyBase(key);
@@ -60,6 +62,17 @@ function findClosestKey(key: string, expectedKeys: string[]): string | null {
     }
   }
 
+  // If no match found and key has no parentheses, try matching with "()" appended
+  // This handles the case where LLM generates "getAll" but expected key is "getAll()"
+  if (!key.includes('(')) {
+    const keyWithParens = key + '()';
+    for (const expected of expectedKeys) {
+      if (expected === keyWithParens) {
+        return expected;
+      }
+    }
+  }
+
   return null;
 }
 

package/analyzer-template/project/runMultiScenarioServer.ts

@@ -184,10 +184,6 @@ export async function runMultiScenarioServer({
     // Start the server (this runs in the background)
     const serverPromise = startServer({
       startCommand,
-      packageManager,
-      exitAfterSuccessfulAppStart,
-      framework,
-
       onStart: async (port: number) => {
         projectPort = port;
         serverStarted = true;

package/analyzer-template/project/runScenarioServer.ts

@@ -119,10 +119,6 @@ export async function runScenarioServer({
   try {
     const code = await startServer({
       startCommand,
-      packageManager,
-      exitAfterSuccessfulAppStart,
-      framework,
-
       onStart: async (port: number) => {
         if (taskCompletion) {
           console.log(

package/analyzer-template/project/start.ts

@@ -378,17 +378,7 @@ async function main({
       });
       updateBackgroundJobProgress(backgroundJob, {
         initiated: backgroundJob.progress.initiated,
-        steps: [
-          {
-            name: 'build-project',
-            initiated:
-              backgroundJob.progress.steps.find(
-                (s) => s.name === 'build-project',
-              )?.initiated ?? new Date().toISOString(),
-            error: error.message,
-            completed: new Date().toISOString(),
-          },
-        ],
+        steps: [],
         completed: new Date().toISOString(),
       }).catch(() => {});
     }

package/analyzer-template/project/startScenarioCapture.ts

@@ -24,6 +24,11 @@ import {
 } from '~codeyam/utils';
 import getAppPath from './getAppPath';
 import { restoreAllBackups, restoreFromBackup } from './backupFiles';
+import {
+  readTrackingFile,
+  writeTrackingFile,
+  clearTrackingFile,
+} from './trackGeneratedFiles';
 import captureLibraryFunctionDirect from './captureLibraryFunctionDirect';
 import {
   getFrameworkForComponent,
@@ -79,6 +84,21 @@ export async function startScenarioCapture({
     restoreAllBackups(fullPath);
   }
 
+  // Clean up any leftover generated files from previous debug sessions
+  const previouslyTracked = readTrackingFile();
+  if (previouslyTracked) {
+    awsLog('CodeYam: Cleaning up files from previous session', {
+      generatedCount: previouslyTracked.generatedFiles.length,
+      backupCount: previouslyTracked.backupFiles.length,
+      timestamp: previouslyTracked.timestamp,
+    });
+    removeScenario(previouslyTracked.generatedFiles);
+    for (const backupPath of previouslyTracked.backupFiles) {
+      restoreFromBackup(backupPath);
+    }
+    clearTrackingFile();
+  }
+
   const sortedReadyToBeCaptured = readyToBeCaptured.sort((a, b) => {
     if (a.indirect !== b.indirect) {
       return a.indirect ? 1 : -1;
@@ -446,6 +466,9 @@ export async function startScenarioCapture({
         controller?.port,
       );
       allGeneratedFiles.push(codeyamPagePath);
+
+      // Persist file tracking for crash/debug recovery
+      writeTrackingFile(allGeneratedFiles, backupFiles);
     }
 
     // Skip if no scenarios to capture
@@ -565,6 +588,7 @@ export async function startScenarioCapture({
         for (const backupPath of backupsToRestore) {
           restoreFromBackup(backupPath);
         }
+        clearTrackingFile();
       }
     };
 

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

@@ -0,0 +1,41 @@
+import { existsSync, readFileSync, writeFileSync, unlinkSync } from 'fs';
+
+const TRACKING_FILE_PATH = '../project/.codeyam-generated-files.json';
+
+export interface TrackedFiles {
+  generatedFiles: string[];
+  backupFiles: string[];
+  timestamp: string;
+}
+
+export function getTrackingFilePath(): string {
+  return TRACKING_FILE_PATH;
+}
+
+export function writeTrackingFile(
+  generatedFiles: string[],
+  backupFiles: string[],
+): void {
+  const data: TrackedFiles = {
+    generatedFiles,
+    backupFiles,
+    timestamp: new Date().toISOString(),
+  };
+  writeFileSync(TRACKING_FILE_PATH, JSON.stringify(data, null, 2), 'utf8');
+}
+
+export function readTrackingFile(): TrackedFiles | null {
+  if (!existsSync(TRACKING_FILE_PATH)) return null;
+  try {
+    const content = readFileSync(TRACKING_FILE_PATH, 'utf8');
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+export function clearTrackingFile(): void {
+  if (existsSync(TRACKING_FILE_PATH)) {
+    unlinkSync(TRACKING_FILE_PATH);
+  }
+}