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

package/analyzer-template/project/loadReadyToBeCaptured.ts

@@ -1,5 +1,9 @@
 import { AnalysisContext, discoverDirectDependencies } from '~codeyam/analyze';
-import { loadAnalysis, loadReadyToBeCapturedAnalyses } from '~codeyam/supabase';
+import {
+  loadAnalysis,
+  loadEntities,
+  loadReadyToBeCapturedAnalyses,
+} from '~codeyam/database';
 import { Analysis, Project } from '~codeyam/types';
 import { LazyFileStore } from './LazyFileStore';
 
@@ -11,6 +15,116 @@ interface LoadReadyToBeCapturedArgs {
   fileStore?: LazyFileStore;
 }
 
+/**
+ * Recursively gather all entities referenced in importedExports of entities already in context.
+ * This fills the gap where discoverDirectDependencies skips mocked/type/implicit imports,
+ * but writeScenarioComponents still needs those entities in the context.
+ */
+async function gatherAllReferencedEntities(
+  context: AnalysisContext,
+  project: Project,
+): Promise<void> {
+  const processedKeys = new Set<string>();
+  let iterationCount = 0;
+  const MAX_ITERATIONS = 20; // Safety limit to prevent infinite loops
+
+  const getAllEntities = () =>
+    Object.values(context.getMutableEntityMap()).flatMap(Object.values);
+
+  while (iterationCount < MAX_ITERATIONS) {
+    iterationCount++;
+
+    // Collect all (filePath, entityName) pairs from importedExports of entities in context
+    const missingEntities = new Map<
+      string,
+      { filePath: string; name: string }
+    >();
+
+    for (const entity of getAllEntities()) {
+      for (const ie of entity.metadata?.importedExports ?? []) {
+        const filePath = ie.resolvedFilePath ?? ie.filePath;
+        const entityName = ie.resolvedName ?? ie.name;
+        const key = `${filePath}:${entityName}`;
+
+        // Skip if already in context or already processed
+        if (context.getEntity(filePath, entityName) || processedKeys.has(key)) {
+          continue;
+        }
+
+        missingEntities.set(key, { filePath, name: entityName });
+      }
+    }
+
+    if (missingEntities.size === 0) {
+      break; // No more missing entities
+    }
+
+    console.log(
+      `CodeYam: Entity gathering iteration ${iterationCount}: Loading ${missingEntities.size} missing entities`,
+    );
+
+    // Mark all as processed before loading to prevent re-processing
+    for (const key of missingEntities.keys()) {
+      processedKeys.add(key);
+    }
+
+    // Group by file path for batch loading
+    const byFilePath = new Map<string, string[]>();
+    for (const { filePath, name } of missingEntities.values()) {
+      if (!byFilePath.has(filePath)) {
+        byFilePath.set(filePath, []);
+      }
+      byFilePath.get(filePath)!.push(name);
+    }
+
+    // Batch load entities by file path
+    const loadPromises = Array.from(byFilePath.entries()).map(
+      async ([filePath, names]) => {
+        const entities = await loadEntities({
+          projectId: project.id,
+          filePaths: [filePath],
+        });
+
+        if (!entities) return [];
+
+        // Filter to only the entities we need (loadEntities returns all for the file)
+        return entities.filter((e) => names.includes(e.name));
+      },
+    );
+
+    const results = await Promise.all(loadPromises);
+    const loadedEntities = results.flat();
+
+    // Add loaded entities to context
+    for (const entity of loadedEntities) {
+      context.addEntity(entity);
+
+      // Also register under 'default' alias if it's a default export
+      if (
+        entity.metadata &&
+        !entity.metadata.notExported &&
+        !entity.metadata.namedExport
+      ) {
+        context.addEntity(entity, 'default');
+      }
+    }
+
+    console.log(
+      `CodeYam: Loaded ${loadedEntities.length} entities in iteration ${iterationCount}`,
+    );
+  }
+
+  if (iterationCount >= MAX_ITERATIONS) {
+    console.log(
+      `CodeYam Warning: Entity gathering reached max iterations (${MAX_ITERATIONS}), some entities may be missing`,
+    );
+  }
+
+  console.log(
+    `CodeYam: Entity gathering complete after ${iterationCount} iteration(s), context has ${getAllEntities().length} entities`,
+  );
+}
+
 /**
  * Load the minimal set of analyses required to successfully run scenario capture.
  * This includes the root analyses (with scenarios) plus all recursive mock dependencies.
@@ -145,7 +259,7 @@ export default async function loadReadyToBeCaptured({
     `CodeYam: Loaded ${allRequiredAnalyses.size} total analyses for scenario capture`,
   );
 
-  // Populate the provided analysis context
+  // Populate the provided analysis context with analyses and their direct entities
   for (const analysis of allRequiredAnalyses.values()) {
     // Add the entity if it exists
     if (analysis.entity) {
@@ -156,6 +270,12 @@ export default async function loadReadyToBeCaptured({
     context.addAnalysis(analysis, analysis.filePath, analysis.entityName);
   }
 
+  // Recursively gather ALL entities referenced in importedExports.
+  // This is necessary because discoverDirectDependencies only finds entities that need
+  // ANALYSES loaded (skipping mocked imports, type imports, etc.), but writeScenarioComponents
+  // needs ALL entities in the context for import path rewriting and recursion.
+  await gatherAllReferencedEntities(context, project);
+
   // Extract the root analyses with scenarios from allRequiredAnalyses (they were reloaded with mocks)
   const finalReadyToBeCaptured = readyToBeCapturedAnalyses.map(
     (originalAnalysis) => {

package/analyzer-template/project/orchestrateCapture/KyselyAnalysisLoader.ts

@@ -1,5 +1,5 @@
 import type { Commit, Project } from '~codeyam/types';
-import { getDatabase } from '~codeyam/supabase';
+import { getDatabase } from '~codeyam/database';
 import { sql } from 'kysely';
 import type { AnalysisLoader, ReadyAnalysisData } from './taskRunner';
 
@@ -56,11 +56,7 @@ export default class KyselyAnalysisLoader implements AnalysisLoader {
 
         // Optional: branch commit SHA filter
         if (this.config.commit?.metadata?.baseline) {
-          query = query.where(
-            'branch_commit_sha',
-            '=',
-            this.config.commit.sha,
-          );
+          query = query.where('branch_commit_sha', '=', this.config.commit.sha);
         }
 
         // Optional: commit ID filter

package/analyzer-template/project/orchestrateCapture/SequentialCaptureTaskRunner.ts

@@ -37,7 +37,10 @@ import {
 export interface SequentialCaptureTaskRunnerContext {
   absoluteProjectRootPath: string;
   absoluteTempPath?: string;
-  startArgs: StartArgs;
+  startArgs: Omit<
+    StartArgs,
+    'absoluteProjectRootPath' | 'absoluteTempPath' | 'noServer' | 'fast'
+  >;
   /** Universal mocks to apply to the capturer's project directory */
   universalMocks?: UniversalMock[];
   /** Environment variables to pass to the spawned processes */
@@ -72,8 +75,6 @@ export default class SequentialCaptureTaskRunner implements CaptureTaskRunner {
     config: TaskRunnerConfig,
     context: SequentialCaptureTaskRunnerContext,
   ): Promise<SequentialCaptureTaskRunner> {
-    console.log('CodeYam DEBUG: Creating SequentialCaptureTaskRunner...');
-
     // Validate that cwd and project path share parent directory
     // Use realpathSync to resolve symlinks (e.g., /tmp -> /private/tmp on macOS)
     const parentOfCodeyam = fs.realpathSync(path.dirname(process.cwd()));
@@ -96,9 +97,6 @@ export default class SequentialCaptureTaskRunner implements CaptureTaskRunner {
 
     // Create capturer base directory
     if (!fs.existsSync(capturerPath)) {
-      console.log(
-        `CodeYam DEBUG: Creating capturer directory at ${capturerPath}`,
-      );
       fs.mkdirSync(capturerPath, { recursive: true });
     }
 
@@ -111,22 +109,17 @@ export default class SequentialCaptureTaskRunner implements CaptureTaskRunner {
       excludes: ['codeyam/log.txt', 'capturer-*'],
       silent: false,
     });
-    console.log('CodeYam DEBUG: Directory copy completed');
 
     // Sanitize env files in capturer project (replaces real values with mock placeholders)
     const capturerProjectPath = path.join(capturerPath, 'project');
     console.log('CodeYam: Sanitizing env files in capturer project...');
-    console.log(`CodeYam DEBUG: capturerProjectPath = ${capturerProjectPath}`);
     const sanitizeResult = sanitizeEnvFiles({
       projectPath: capturerProjectPath,
       log: (msg) => console.log(`CodeYam Sanitize: ${msg}`),
     });
-    console.log(
-      `CodeYam DEBUG: Env files sanitized - created: ${sanitizeResult.createdFiles.length}, sanitized: ${sanitizeResult.sanitizedFiles.length}`,
-    );
     if (sanitizeResult.sanitizedFiles.length > 0) {
       console.log(
-        `CodeYam DEBUG: Sanitized files: ${sanitizeResult.sanitizedFiles.join(', ')}`,
+        `CodeYam: Env files sanitized: ${sanitizeResult.sanitizedFiles.join(', ')}`,
       );
     }
 
@@ -139,7 +132,6 @@ export default class SequentialCaptureTaskRunner implements CaptureTaskRunner {
         mocks: context.universalMocks,
         projectPath: capturerProjectPath,
       });
-      console.log('CodeYam DEBUG: Universal mocks applied');
     }
 
     const runner = new SequentialCaptureTaskRunner(
@@ -150,12 +142,8 @@ export default class SequentialCaptureTaskRunner implements CaptureTaskRunner {
 
     // Start background processing loop
     // Each batch will spawn its own paired start+capture processes
-    console.log('CodeYam DEBUG: Starting processing loop...');
     runner.startProcessingLoop();
 
-    console.log(
-      'CodeYam DEBUG: SequentialCaptureTaskRunner created successfully',
-    );
     return runner;
   }
 
@@ -179,23 +167,18 @@ export default class SequentialCaptureTaskRunner implements CaptureTaskRunner {
   }
 
   private async runProcessingLoop(): Promise<void> {
-    console.log('CodeYam DEBUG: Processing loop started');
     while (!this.isCleanedUp) {
       if (this.queue.length === 0) {
         await new Promise((resolve) => setTimeout(resolve, 1000));
         continue;
       }
 
-      console.log(
-        `CodeYam DEBUG: Processing queue - ${this.queue.length} batches waiting`,
-      );
       this.isProcessing = true;
       const batch = this.queue.shift()!;
 
       try {
         await this.processBatch(batch);
 
-        console.log(`CodeYam DEBUG: Batch completed successfully`);
         // Notify callback of completion
         if (this.batchCompletedCallback) {
           this.batchCompletedCallback(batch);
@@ -210,7 +193,6 @@ export default class SequentialCaptureTaskRunner implements CaptureTaskRunner {
         this.isProcessing = false;
       }
     }
-    console.log('CodeYam DEBUG: Processing loop exited');
   }
 
   private async processBatch(analysisIds: string[]): Promise<void> {
@@ -330,9 +312,6 @@ export default class SequentialCaptureTaskRunner implements CaptureTaskRunner {
   }
 
   enqueueWork(analysisIds: string[]): Promise<void> {
-    console.log(
-      `CodeYam DEBUG: Enqueueing batch of ${analysisIds.length} analyses`,
-    );
     this.queue.push(analysisIds);
     return Promise.resolve();
   }

package/analyzer-template/project/orchestrateCapture/SupabaseAnalysisLoader.ts

@@ -1,5 +1,5 @@
 import type { Commit, Project } from '~codeyam/types';
-import { getSupabase } from '~codeyam/supabase';
+import { getSupabase } from '~codeyam/database';
 import type { AnalysisLoader, ReadyAnalysisData } from './taskRunner';
 
 interface SupabaseAnalysisLoaderConfig {
@@ -48,7 +48,7 @@ export default class SupabaseAnalysisLoader implements AnalysisLoader {
     let pageOffset = 0;
 
     while (true) {
-      const query = getSupabase()
+      const { data, error } = await getSupabase()
         .rpc('get_ready_to_be_captured_analyses', args)
         .select(
           'id, commit_id, branch_commit_sha, status->processingForCaptureAt',
@@ -56,7 +56,7 @@ export default class SupabaseAnalysisLoader implements AnalysisLoader {
         .range(pageOffset, pageOffset + pageSize - 1)
         .returns<ReadyAnalysisData[]>();
 
-      const { data, error } = await query;
+      const rows = data as ReadyAnalysisData[] | null;
 
       if (error) {
         console.error(
@@ -67,13 +67,13 @@ export default class SupabaseAnalysisLoader implements AnalysisLoader {
         return null;
       }
 
-      if (!data || data.length === 0) {
+      if (!rows || rows.length === 0) {
         break;
       }
 
-      allData.push(...data);
+      allData.push(...rows);
 
-      if (data.length < pageSize) {
+      if (rows.length < pageSize) {
         break;
       }
 

package/analyzer-template/project/orchestrateCapture.ts

@@ -23,7 +23,7 @@
  */
 
 import type { Commit, Project } from '~codeyam/types';
-import { updateCommitMetadata } from '~codeyam/supabase';
+import { updateCommitMetadata } from '~codeyam/database';
 
 import type {
   AnalysisLoader,

package/analyzer-template/project/prepareRepo.ts

@@ -39,7 +39,7 @@ export default async function prepareRepo(args: PrepareRepoArgs) {
       throw new Error(`Local project path does not exist: ${localProjectPath}`);
     }
 
-    awsLogDebugLevel(1, 'Rsyncing repo...');
+    awsLogDebugLevel(1, 'Syncing repo...');
 
     // Rsync project files respecting .gitignore to avoid copying secrets
     // (.env files, credentials, private keys, etc.) while preserving node_modules

package/analyzer-template/project/runAnalysis.ts

@@ -16,7 +16,7 @@ import {
   loadEntity,
   loadScenario,
   updateCommitMetadata,
-} from '~codeyam/supabase';
+} from '~codeyam/database';
 import analyzeReadyToBeCaptured from './analyzeReadyToBeCaptured';
 import analyzeBaselineCommit from './analyzeBaselineCommit';
 import analyzeRegularCommit from './analyzeRegularCommit';

package/analyzer-template/project/runMultiScenarioServer.ts

@@ -11,7 +11,7 @@ import { startServer } from './startServer';
 import { awsLog, safeFileName } from '~codeyam/utils';
 import { recordErrorMessageForScenario } from './utils/errorHandling';
 import { Controller, TaskCompleteType } from './controller/startController';
-import { updateFreshAnalysisStatus, loadAnalysis } from '~codeyam/supabase';
+import { updateFreshAnalysisStatus, loadAnalysis } from '~codeyam/database';
 import getScenarioUrl from './getScenarioUrl';
 import { chromium } from 'playwright';
 import { ScenarioIterator } from './ScenarioIterator';
@@ -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;
@@ -519,7 +515,7 @@ export async function runMultiScenarioServer({
       }
 
       // Advance iterator to next scenario
-      awsLog('CodeYam SERVER DEBUG: Advancing to next scenario', {
+      awsLog('CodeYam: Advancing to next scenario', {
         analysisId: analysis.id,
         currentScenarioName: scenario.name,
         nextScenarioIndex: i + 1,

package/analyzer-template/project/runScenarioServer.ts

@@ -11,7 +11,7 @@ import { startServer } from './startServer';
 import { awsLog, safeFileName } from '~codeyam/utils';
 import { recordErrorMessageForScenario } from './utils/errorHandling';
 import { Controller, TaskCompleteType } from './controller/startController';
-import { updateFreshAnalysisStatus, loadAnalysis } from '~codeyam/supabase';
+import { updateFreshAnalysisStatus, loadAnalysis } from '~codeyam/database';
 import getScenarioUrl from './getScenarioUrl';
 
 const closedScenarios: string[] = [];
@@ -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

@@ -5,7 +5,8 @@ import {
   loadBackgroundJob,
   loadProject,
   updateBackgroundJobProgress,
-} from '~codeyam/supabase';
+  updateCommitMetadata,
+} from '~codeyam/database';
 import { Commit, ProjectFramework, ServerCommand } from '~codeyam/types';
 import runCaptureOrchestration from './orchestrateCapture';
 import AwsCaptureTaskRunner from './orchestrateCapture/AwsCaptureTaskRunner';
@@ -172,6 +173,24 @@ async function main({
         awsLog(
           'CodeYam Capture: analysis completed, signaling orchestration to begin draining...',
         );
+
+        // Update commit metadata to mark analysis as complete
+        // This allows the UI to show the "Capturing..." state
+        // With orchestration, the same process handles both phases,
+        // so we clear analyzerPid and set capturePid for a clean state transition
+        if (sharedContext.commit?.sha) {
+          await updateCommitMetadata({
+            commitSha: sharedContext.commit.sha,
+            runStatusUpdate: {
+              analysisCompletedAt: new Date().toISOString(),
+              analyzerPid: undefined,
+              capturePid: process.pid,
+            },
+          }).catch((error) => {
+            awsLog(`Warning: Failed to update commit metadata: ${error}`);
+          });
+        }
+
         if (sendControlMessage) {
           sendControlMessage('drain');
         } else {
@@ -213,12 +232,8 @@ async function main({
               absoluteTempPath,
               startArgs: {
                 packageManager,
-                absoluteProjectRootPath,
-                absoluteTempPath,
                 framework,
-                noServer: false,
                 steps,
-                fast,
               },
               // Pass universal mocks so they're applied to the capturer's project directory
               universalMocks: sharedContext.project.metadata?.universalMocks,
@@ -253,6 +268,9 @@ async function main({
               : (sharedContext.commit ?? sharedContext.branchCommit),
           analysisIds: envConfig.analysisIds,
           entityShas: envConfig.entityShas,
+          // In local-sequential mode, use full=true to query all ready analyses for the project
+          // since we don't have specific analysisIds/entityShas and commit is null.
+          full: orchestrateCapture === 'local-sequential',
           taskRunner,
         });
         awsLog('CodeYam Capture: runCaptureOrchestration() completed');
@@ -378,17 +396,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

@@ -13,7 +13,7 @@ import {
 import removeScenario from './removeScenario';
 import { recordErrorMessageForScenario } from './utils/errorHandling';
 import { Controller } from './controller/startController';
-import { loadFile, updateFreshAnalysisStatus } from '~codeyam/supabase';
+import { loadFile, updateFreshAnalysisStatus } from '~codeyam/database';
 import {
   awsLog,
   awsLogDebugLevel,

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;
   }
 }