@codeyam/codeyam-cli 0.1.0-bleeding-edge.8afd3ee

package/analyzer-template/playwright/taskComplete.ts

@@ -0,0 +1,12 @@
+export default async function taskComplete(
+  serverUrl: string,
+  scenarioId?: string,
+) {
+  try {
+    const url = scenarioId
+      ? `${serverUrl}/static/codeyam-task-complete?scenarioId=${encodeURIComponent(scenarioId)}`
+      : `${serverUrl}/static/codeyam-task-complete`;
+    await fetch(url);
+  } catch (e) {}
+  return new Promise((resolve) => setTimeout(resolve, 1000));
+}

package/analyzer-template/playwright/updateBackgroundJob.ts

@@ -0,0 +1,43 @@
+import { updateBackgroundJobProgress } from '~codeyam/supabase';
+import { BackgroundJob } from '~codeyam/types';
+
+export default async function updateBackgroundJob(
+  job: BackgroundJob,
+  screenshotsErrors: string[],
+  interactivesErrors: string[],
+) {
+  if (!job) return;
+
+  await updateBackgroundJobProgress(
+    job,
+    {
+      initiated: job.progress.initiated,
+      steps: [
+        {
+          name: 'generate-screenshots',
+          initiated:
+            job.progress.steps.find((s) => s.name === 'generate-screenshots')
+              ?.initiated ?? new Date().toISOString(),
+          error:
+            screenshotsErrors?.length > 0
+              ? screenshotsErrors.join('\n')
+              : undefined,
+          completed: new Date().toISOString(),
+        },
+        {
+          name: 'generate-interactives',
+          initiated:
+            job.progress.steps.find((s) => s.name === 'generate-interactives')
+              ?.initiated ?? new Date().toISOString(),
+          error:
+            interactivesErrors?.length > 0
+              ? interactivesErrors.join('\n')
+              : undefined,
+          completed: new Date().toISOString(),
+        },
+      ],
+      completed: new Date().toISOString(),
+    },
+    true,
+  );
+}

package/analyzer-template/playwright/uploadAssets.ts

@@ -0,0 +1,118 @@
+import { PutObjectCommand, S3Client } from '@aws-sdk/client-s3';
+import * as fs from 'fs';
+import * as path from 'path';
+import { awsLog, rsyncCopy } from '~codeyam/utils/server';
+
+export async function uploadAssetDirectory(directory: string) {
+  if (process.env.CODEYAM_LOCAL_PROJECT_PATH) {
+    await uploadDirectoryToFS(directory);
+  } else if (process.env.S3_BUCKET_NAME) {
+    await uploadDirectoryToS3(directory);
+  } else {
+    console.warn(`CodeYam Warning: SKIPPING upload of directory ${directory}`);
+  }
+}
+
+export async function uploadAssetFile(filePath: string, key: string) {
+  if (process.env.CODEYAM_LOCAL_PROJECT_PATH) {
+    return uploadFileToFS(key, filePath);
+  } else if (process.env.S3_BUCKET_NAME) {
+    return uploadFileToS3(filePath, key);
+  }
+}
+
+async function uploadDirectoryToS3(directory: string) {
+  if (!fs.existsSync(directory)) return;
+
+  const files = fs.readdirSync(directory);
+  awsLog('Uploading directory: ', directory, files);
+  for (let i = 0; i < files?.length; i++) {
+    const filePath = path.join(directory, files[i]);
+    const fileStat = fs.statSync(filePath);
+
+    if (fileStat.isFile()) {
+      await uploadFileToS3(filePath, filePath.replace('./', ''));
+    } else if (fileStat.isDirectory()) {
+      await uploadDirectoryToS3(filePath);
+    }
+  }
+}
+
+async function uploadDirectoryToFS(directory: string) {
+  const targetPath = path.join(
+    process.env.CODEYAM_LOCAL_PROJECT_PATH,
+    '.codeyam',
+    'captures',
+    directory.replace('./', ''),
+  );
+  console.log(
+    `CodeYam: Uploading directory ${directory} to local path: ${targetPath}`,
+  );
+
+  await rsyncCopy({
+    sourcePath: directory,
+    destinationPath: targetPath,
+    keepExisting: true, // overlay files
+  });
+}
+
+async function uploadFileToS3(filePath: string, key: string) {
+  const ContentType = getContentTypeByFile(filePath);
+  const fileContent =
+    ContentType.indexOf('image') > -1
+      ? fs.readFileSync(filePath)
+      : fs.readFileSync(filePath, 'utf8');
+
+  console.log('Uploading file: ', key);
+
+  if (key.indexOf('.html')) {
+    key = key.replace('.html', '');
+  }
+
+  const uploadParams = {
+    Bucket: process.env.S3_BUCKET_NAME,
+    Key: key,
+    Body: fileContent,
+    ContentType,
+  };
+
+  const s3Client = new S3Client();
+  await s3Client.send(new PutObjectCommand(uploadParams));
+
+  return key;
+}
+
+function uploadFileToFS(key: string, filePath: string) {
+  const targetFilePath = path.join(
+    process.env.CODEYAM_LOCAL_PROJECT_PATH,
+    '.codeyam',
+    'captures',
+    key,
+  );
+
+  console.log(
+    `CodeYam: Uploading file ${filePath} to local path: ${targetFilePath}`,
+  );
+
+  // Ensure the target directory exists
+  const targetDir = path.dirname(targetFilePath);
+  fs.mkdirSync(targetDir, { recursive: true });
+
+  // Copy the file
+  fs.copyFileSync(filePath, targetFilePath);
+
+  return key;
+}
+
+function getContentTypeByFile(fileName: string) {
+  const fn = fileName.toLowerCase();
+
+  if (fn.endsWith('.html')) return 'text/html';
+  else if (fn.endsWith('.css')) return 'text/css';
+  else if (fn.endsWith('.json')) return 'application/json';
+  else if (fn.endsWith('.js')) return 'application/javascript';
+  else if (fn.endsWith('.png')) return 'image/png';
+  else if (fn.endsWith('.jpg')) return 'image/jpg';
+
+  return 'application/octet-stream';
+}

package/analyzer-template/playwright/waitForNoServer.ts

@@ -0,0 +1,16 @@
+/* eslint-disable */
+
+export default async function waitForNoServer(url: string) {
+  while (true) {
+    try {
+      const response = await fetch(url + '/static/codeyam-info');
+      console.log('Server response', url, response.status);
+    } catch (error) {
+      break;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 2000));
+  }
+
+  console.log('Server is no longer responding.');
+  return true;
+}

package/analyzer-template/playwright/waitForServer.ts

@@ -0,0 +1,83 @@
+import { awsLog } from '~codeyam/utils';
+import getCodeYamInfo from './getCodeYamInfo';
+
+const INITIAL_RETRY_DELAY = 500; // 0.5 seconds
+const MAX_RETRY_DELAY = 5000; // 5 seconds max between retries
+const MAX_WAIT_TIME = 20 * 60 * 1000; // 20 minutes total wait time
+const JITTER_FACTOR = 0.2; // ±20% jitter
+
+function calculateDelayWithJitter(baseDelay: number): number {
+  const jitter = baseDelay * JITTER_FACTOR;
+  const minDelay = baseDelay - jitter;
+  const maxDelay = baseDelay + jitter;
+  return Math.floor(minDelay + Math.random() * (maxDelay - minDelay));
+}
+
+export interface WaitForServerResult {
+  shutdown: boolean;
+}
+
+export default async function waitForServer(
+  url: string,
+  shouldStop: () => boolean,
+): Promise<WaitForServerResult> {
+  let retryDelay = INITIAL_RETRY_DELAY;
+  const startTime = Date.now();
+  let consecutiveConnectionFailures = 0;
+  const MAX_CONNECTION_FAILURES_FOR_SHUTDOWN = 3;
+
+  while (!shouldStop()) {
+    // Check if we've exceeded maximum wait time
+    const elapsedTime = Date.now() - startTime;
+    if (elapsedTime > MAX_WAIT_TIME) {
+      awsLog(
+        `Server failed to respond after ${Math.round(MAX_WAIT_TIME / 1000)}s. Giving up.`,
+      );
+      throw new Error(
+        `Server at ${url} did not respond within ${Math.round(MAX_WAIT_TIME / 1000)} seconds`,
+      );
+    }
+
+    const currentDelay = calculateDelayWithJitter(retryDelay);
+
+    try {
+      const result = await getCodeYamInfo(url, { returnShutdown: true });
+
+      // Check if controller signaled completion
+      if (result.shutdown) {
+        awsLog('CodeYam: Controller signaled completion during waitForServer');
+        return { shutdown: true };
+      }
+
+      // Check if connection failed (server exited)
+      if (result.connectionFailed) {
+        consecutiveConnectionFailures++;
+        // If we've had many consecutive connection failures, the controller has likely exited
+        if (consecutiveConnectionFailures >= MAX_CONNECTION_FAILURES_FOR_SHUTDOWN) {
+          awsLog('CodeYam: Controller connection lost, treating as shutdown');
+          return { shutdown: true };
+        }
+      } else {
+        consecutiveConnectionFailures = 0;
+      }
+
+      if (result.info !== null && !shouldStop()) {
+        console.log('Server is up and running.');
+        return { shutdown: false };
+      }
+      // Null response means server not ready - continue waiting
+      awsLog(
+        `Capture server not ready yet. Next attempt in ${Math.round(currentDelay / 1000)} seconds`,
+      );
+    } catch (error) {
+      awsLog(
+        `Error retrieving ${url}: '${error.message}'. Next attempt in ${Math.round(currentDelay / 1000)} seconds`,
+      );
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, currentDelay));
+    retryDelay = Math.min(retryDelay * 2, MAX_RETRY_DELAY);
+  }
+
+  return { shutdown: false };
+}

package/analyzer-template/process/GlobalProcessManager.ts

@@ -0,0 +1,93 @@
+import { ProcessManager, ProcessType, ProcessState } from './ProcessManager';
+import type { ProcessInfo } from './ProcessManager';
+
+export { ProcessManager, ProcessType, ProcessState };
+export type { ProcessInfo };
+
+let globalInstance: ProcessManager | null = null;
+let signalHandlersInstalled = false;
+
+/**
+ * Get the global singleton ProcessManager instance
+ */
+export function getGlobalProcessManager(): ProcessManager {
+  if (!globalInstance) {
+    globalInstance = new ProcessManager();
+  }
+  return globalInstance;
+}
+
+/**
+ * Install signal handlers to cleanup processes on exit
+ * Can be called multiple times safely - will only install once
+ */
+export function installSignalHandlers(): void {
+  if (signalHandlersInstalled) {
+    return;
+  }
+
+  const manager = getGlobalProcessManager();
+
+  const cleanup = async (signal: string) => {
+    console.log(`\n${signal} received, cleaning up processes...`);
+
+    try {
+      await manager.shutdownAll({ escalationTimeoutMs: 2000 });
+      console.log('All processes cleaned up successfully');
+    } catch (error) {
+      console.error('Error during cleanup:', error);
+    }
+
+    // Exit with appropriate code
+    process.exit(signal === 'SIGTERM' ? 0 : 1);
+  };
+
+  // Handle termination signals
+  process.on('SIGINT', () => void cleanup('SIGINT'));
+  process.on('SIGTERM', () => void cleanup('SIGTERM'));
+
+  // Handle uncaught exceptions
+  process.on('uncaughtException', (error) => {
+    console.error('Uncaught exception:', error);
+    void manager
+      .shutdownAll({ escalationTimeoutMs: 1000 })
+      .catch((cleanupError) =>
+        console.error('Error during emergency cleanup:', cleanupError),
+      )
+      .finally(() => process.exit(1));
+  });
+
+  // Handle unhandled promise rejections
+  process.on('unhandledRejection', (reason, promise) => {
+    console.error('Unhandled rejection at:', promise, 'reason:', reason);
+    void manager
+      .shutdownAll({ escalationTimeoutMs: 1000 })
+      .catch((cleanupError) =>
+        console.error('Error during emergency cleanup:', cleanupError),
+      )
+      .finally(() => process.exit(1));
+  });
+
+  // Handle normal exit
+  process.on('beforeExit', () => {
+    // Only cleanup if there are running processes
+    const runningProcesses = manager.listByState(ProcessState.Running);
+    if (runningProcesses.length > 0) {
+      console.log('Process exiting, cleaning up running processes...');
+      void manager.shutdownAll({ escalationTimeoutMs: 2000 });
+    }
+  });
+
+  signalHandlersInstalled = true;
+}
+
+/**
+ * Reset the global instance (primarily for testing)
+ */
+export function resetGlobalProcessManager(): void {
+  if (globalInstance) {
+    // Don't await, just fire and forget
+    globalInstance.shutdownAll().catch(console.error);
+    globalInstance = null;
+  }
+}

package/analyzer-template/process/INTEGRATION_COMPLETE.md

@@ -0,0 +1,333 @@
+# Process Management Integration - COMPLETE ✅
+
+## Summary
+
+We've successfully completed an **aggressive, test-driven integration** of the process management system into CodeYam's codebase!
+
+## What Was Integrated
+
+### 1. Signal Handlers Added to All CLI Entry Points ✅
+
+Added `installSignalHandlers()` to:
+
+- ✅ `background/src/runLocally.ts`
+- ✅ `background/src/orchestrate.ts`
+- ✅ `background/src/runOrchestrateCapture.ts`
+- ✅ `background/src/captureStatic.ts`
+- ✅ `background/src/worker.ts`
+
+**What this does**: All processes spawned by these CLIs will now be automatically cleaned up on:
+
+- Ctrl+C (SIGINT)
+- SIGTERM signals
+- Uncaught exceptions
+- Unhandled promise rejections
+- Normal exit
+
+### 2. Process Registration Added to execAsync Functions ✅
+
+Modified both execAsync implementations to automatically register all spawned processes:
+
+**`background/src/lib/virtualized/common/execAsync.ts`**:
+
+- Registers all spawned processes with the global ProcessManager
+- Stores metadata (command, args, workingDir, commitId)
+- Uses ProcessType.Other for generic processes
+
+**`background/src/lib/local/execAsync.ts`**:
+
+- Registers all spawned processes with the global ProcessManager
+- Stores metadata (command, args, workingDir)
+- Both `execAsync()` and `execAsyncWithProcess()` are now managed
+
+**What this does**: Every process spawned anywhere in the codebase is now:
+
+- Automatically tracked in the global registry
+- Queryable by name, type, state, or metadata
+- Automatically cleaned up on exit/error
+
+### 3. Comprehensive Integration Tests ✅
+
+Created `background/src/lib/process/__tests__/integration.test.ts` with 6 tests:
+
+- ✅ Automatically registers processes spawned by execAsync
+- ✅ Tracks multiple concurrent processes
+- ✅ Cleans up processes on shutdown
+- ✅ Simulates signal handling cleanup
+- ✅ Stores command metadata with processes
+- ✅ Tracks failed processes
+
+## Test Results
+
+```
+Test Suites: 4 passed, 4 total
+Tests:       63 passed, 63 total
+```
+
+**Breakdown**:
+
+- 32 tests: ProcessManager (core functionality)
+- 8 tests: GlobalProcessManager (singleton & signal handling)
+- 17 tests: managedExecAsync (managed spawn wrapper)
+- 6 tests: Integration (real execAsync usage)
+
+## Files Modified
+
+1. **CLI Entry Points** (5 files):
+   - `background/src/runLocally.ts`
+   - `background/src/orchestrate.ts`
+   - `background/src/runOrchestrateCapture.ts`
+   - `background/src/captureStatic.ts`
+   - `background/src/worker.ts`
+
+2. **Core Spawning Functions** (2 files):
+   - `background/src/lib/virtualized/common/execAsync.ts`
+   - `background/src/lib/local/execAsync.ts`
+
+3. **Tests** (1 new file):
+   - `background/src/lib/process/__tests__/integration.test.ts`
+
+## How It Works
+
+### Before (Old Behavior)
+
+```typescript
+// Start process
+const proc = spawn('node', ['server.js']);
+// ❌ No tracking
+// ❌ No automatic cleanup
+// ❌ Orphaned on Ctrl+C
+// ❌ Orphaned on error
+```
+
+### After (New Behavior)
+
+```typescript
+// Start process (nothing changed in calling code!)
+const exitCode = await execAsync({
+  command: 'node',
+  args: ['server.js'],
+  processName: 'my-server',
+});
+
+// ✅ Automatically registered
+// ✅ Tracked in global registry
+// ✅ Cleaned up on Ctrl+C
+// ✅ Cleaned up on error
+// ✅ Queryable: manager.findByName('my-server')
+```
+
+## Verification Steps
+
+### 1. Run existing tests
+
+```bash
+# All 63 process management tests should pass
+npx jest background/src/lib/process/__tests__/
+```
+
+### 2. Test Ctrl+C cleanup (manual)
+
+```bash
+# Start a long-running command
+pnpm runLocally:no-build some-project
+
+# Press Ctrl+C
+# Verify all processes are killed (should see cleanup messages)
+
+# Check for orphaned processes
+ps aux | grep CODEYAM
+# Should be empty!
+```
+
+### 3. Test error cleanup (manual)
+
+```bash
+# Run a command that will error
+pnpm runLocally:no-build nonexistent-project
+
+# Verify all processes are cleaned up
+ps aux | grep CODEYAM
+# Should be empty!
+```
+
+### 4. Query running processes (during execution)
+
+```typescript
+// Add this to any code during execution:
+import { getGlobalProcessManager } from './lib/process';
+
+const manager = getGlobalProcessManager();
+console.log('Active processes:', manager.listAll());
+console.log('Running count:', manager.listByState('running').length);
+```
+
+## What's Controlled Now
+
+The process management system now controls **ALL** processes spawned by:
+
+1. **runLocally.ts** → sharedRunLocally → createLocalAnalyzer → execAsync
+2. **orchestrate.ts** → execAsync (server & capture processes)
+3. **runOrchestrateCapture.ts** → orchestrateCapture → various spawns
+4. **captureStatic.ts** → capture → playwright processes
+5. **worker.ts** → worker tasks → various spawns
+
+Any process spawned through `execAsync` in either:
+
+- `background/src/lib/virtualized/common/execAsync.ts`
+- `background/src/lib/local/execAsync.ts`
+
+Is now **automatically managed**.
+
+## Benefits
+
+### 1. No More Orphaned Processes ✅
+
+- Ctrl+C properly cleans up all child processes
+- Errors clean up processes before exit
+- No lingering servers/analyzers/capture processes
+
+### 2. Better Debugging ✅
+
+- Query all running processes at any time
+- See metadata (command, args, working dir)
+- Track process lifecycle (running → completed/failed/killed)
+
+### 3. Reliability ✅
+
+- Signal escalation ensures stubborn processes die (SIGINT → SIGTERM → SIGKILL)
+- Recursive cleanup (kills child processes too)
+- Tested with 63 automated tests
+
+### 4. Observability ✅
+
+```typescript
+const manager = getGlobalProcessManager();
+
+// What's running?
+console.log(`${manager.listByState('running').length} processes running`);
+
+// Any failures?
+const failures = manager.listByState('failed');
+failures.forEach((p) => console.log(`Failed: ${p.name}, code: ${p.exitCode}`));
+
+// Specific process?
+const analyzer = manager.findByName('analyzer-project-abc')[0];
+console.log(`Analyzer uptime: ${Date.now() - analyzer.startedAt}ms`);
+```
+
+## What's NOT Changed
+
+The integration is **backward compatible** - no changes required to calling code:
+
+- ✅ All existing `execAsync` calls work exactly as before
+- ✅ Return values unchanged
+- ✅ Error handling unchanged
+- ✅ Process lifecycle unchanged
+- ✅ Just adds automatic tracking + cleanup
+
+## Known Limitations
+
+1. **Processes spawned directly via `spawn()`**: Not managed (must use execAsync)
+2. **Docker containers**: Not managed by this system (separate lifecycle)
+3. **Worker threads**: Registered but may need special handling
+4. **ECS tasks**: Managed by AWS, not this system
+
+## Next Steps (Optional)
+
+### Future Enhancements
+
+1. **Process Groups**: Organize related processes (e.g., "analysis-session-123")
+2. **Resource Monitoring**: Track CPU/memory usage per process
+3. **Persistent Registry**: SQLite database for cross-restart tracking
+4. **Web Dashboard**: Real-time view of all managed processes
+5. **Auto-restart**: Automatically restart failed critical processes
+
+### Specific Process Types
+
+Replace generic `ProcessType.Other` with specific types:
+
+```typescript
+// In orchestrate.ts
+manager.register({
+  process: serverProcess,
+  type: ProcessType.Server, // Instead of Other
+  name: `server-${projectSlug}`,
+});
+
+// In capture code
+manager.register({
+  process: captureProcess,
+  type: ProcessType.Capture, // Instead of Other
+  name: `capture-${projectSlug}`,
+});
+```
+
+### Parent-Child Relationships
+
+Track process hierarchies:
+
+```typescript
+const serverId = manager.register({
+  process: serverProcess,
+  type: ProcessType.Server,
+  name: 'main-server',
+});
+
+manager.register({
+  process: captureProcess,
+  type: ProcessType.Capture,
+  name: 'capture-worker',
+  parentId: serverId, // Link to parent
+});
+
+// Shutdown server + all children
+await manager.shutdown(serverId, { shutdownChildren: true });
+```
+
+## Troubleshooting
+
+### Problem: Processes still orphaned
+
+**Solution**: Verify `installSignalHandlers()` is called at the top of the CLI entry point
+
+### Problem: Can't find process in registry
+
+**Solution**: Ensure the process is spawned via `execAsync`, not direct `spawn()`
+
+### Problem: Tests failing with "path undefined"
+
+**Solution**: Provide `workingDir` parameter to `execAsync()`
+
+### Problem: Process not cleaning up
+
+**Solution**: Check process logs - might be ignoring signals. Use `manager.shutdown()` with escalation
+
+## Success Metrics
+
+✅ **63 automated tests passing**
+✅ **5 CLI entry points updated**
+✅ **2 core spawn functions wrapped**
+✅ **All processes tracked automatically**
+✅ **Zero code changes required in calling code**
+✅ **Backward compatible**
+✅ **Test-driven development**
+
+## Conclusion
+
+The CodeYam process management system is **fully integrated and operational**!
+
+Every process spawned by the CLI is now:
+
+- Automatically tracked
+- Queryable at runtime
+- Guaranteed to be cleaned up
+
+No more orphaned processes. No more manual cleanup. No more "kill -9" hunting.
+
+🎉 **Mission accomplished!**
+
+---
+
+For detailed API documentation, see [README.md](./README.md)
+For migration examples, see [INTEGRATION_EXAMPLE.md](./INTEGRATION_EXAMPLE.md)