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

package/analyzer-template/process/INTEGRATION_EXAMPLE.md

@@ -1,525 +0,0 @@
-# Integration Example: Adding Process Management to CLI Entry Points
-
-This document shows concrete examples of integrating the process management system into existing CodeYam CLI entry points.
-
-## Step 1: Add Signal Handlers to CLI Entry Points
-
-### Example: runLocally.ts
-
-**Before:**
-
-```typescript
-import yargs from 'yargs';
-import { hideBin } from 'yargs/helpers';
-import sharedRunLocally, { RunLocallyArgs } from './sharedRunLocally';
-
-yargs(hideBin(process.argv))
-  .command('$0 <projectSlug>', 'Run the project locally', (yargs) => {
-    // ... configuration
-  })
-  .parse();
-```
-
-**After:**
-
-```typescript
-import yargs from 'yargs';
-import { hideBin } from 'yargs/helpers';
-import sharedRunLocally, { RunLocallyArgs } from './sharedRunLocally';
-import { installSignalHandlers } from './lib/process';
-
-// ✅ Add this single line at the top of the file
-installSignalHandlers();
-
-yargs(hideBin(process.argv))
-  .command('$0 <projectSlug>', 'Run the project locally', (yargs) => {
-    // ... configuration
-  })
-  .parse();
-```
-
-That's it! All processes spawned by this CLI will now be automatically cleaned up on exit/error/signal.
-
-## Step 2: Replace execAsync Calls with managedExecAsync
-
-### Example: Updating background/src/lib/local/createLocalAnalyzer.ts
-
-**Before:**
-
-```typescript
-import execAsync from '../virtualized/common/execAsync';
-
-export default async function createLocalAnalyzer({
-  projectSlug,
-  commitSha,
-  steps,
-}: CreateLocalAnalyzerOptions): Promise<
-  ChildProcessWithoutNullStreams | undefined
-> {
-  let process: ChildProcessWithoutNullStreams | undefined;
-
-  await execAsync({
-    command: 'node',
-    args: ['dist/project/start.js', ...args],
-    env: {
-      ...process.env,
-      PROJECT_SLUG: projectSlug,
-      COMMIT_SHA: commitSha,
-    },
-    onStart: async (proc) => {
-      process = proc;
-    },
-  });
-
-  return process;
-}
-```
-
-**After:**
-
-```typescript
-import { managedExecAsync, ProcessType } from '../process';
-
-export default async function createLocalAnalyzer({
-  projectSlug,
-  commitSha,
-  steps,
-}: CreateLocalAnalyzerOptions): Promise<string> {
-  // ✅ Returns process ID instead of ChildProcess
-  const { processId } = managedExecAsync({
-    command: 'node',
-    args: ['dist/project/start.js', ...args],
-    processType: ProcessType.Analyzer,
-    processName: `analyzer-${projectSlug}`,
-    metadata: {
-      projectSlug,
-      commitSha,
-      steps,
-    },
-    env: {
-      ...process.env,
-      PROJECT_SLUG: projectSlug,
-      COMMIT_SHA: commitSha,
-    },
-    returnProcessId: true,
-  });
-
-  // ✅ Return process ID for tracking
-  return processId;
-}
-```
-
-## Step 3: Update Process Tracking
-
-### Example: Updating orchestrate.ts
-
-**Before:**
-
-```typescript
-interface ProcessMap {
-  server?: ChildProcessWithoutNullStreams;
-  capture?: ChildProcessWithoutNullStreams;
-}
-
-const processMap: ProcessMap = {};
-
-// Start server
-await execAsync({
-  command: 'pnpm',
-  args: ['runLocally', projectSlug],
-  onStart: (process) => {
-    processMap.server = process;
-  },
-});
-
-// Later: cleanup
-if (processMap.server) {
-  await killProcess('server', projectSlug, processMap.server.pid);
-}
-```
-
-**After:**
-
-```typescript
-import {
-  managedExecAsync,
-  getGlobalProcessManager,
-  ProcessType,
-} from './lib/process';
-
-const manager = getGlobalProcessManager();
-
-// ✅ Start server with automatic tracking
-const { processId: serverId } = managedExecAsync({
-  command: 'pnpm',
-  args: ['runLocally', projectSlug],
-  processType: ProcessType.Server,
-  processName: `server-${projectSlug}`,
-  metadata: { projectSlug },
-  returnProcessId: true,
-});
-
-// ✅ Later: cleanup is as simple as
-await manager.shutdown(serverId);
-
-// ✅ Or even better: let signal handlers clean up automatically!
-// No manual cleanup needed
-```
-
-## Step 4: Handle Parent-Child Relationships
-
-### Example: Server + Capture Orchestration
-
-**Before:**
-
-```typescript
-let serverProcess: ChildProcessWithoutNullStreams;
-let captureProcess: ChildProcessWithoutNullStreams;
-
-// Start server
-await execAsync({
-  command: 'pnpm',
-  args: ['runLocally', projectSlug],
-  onStart: (proc) => {
-    serverProcess = proc;
-  },
-});
-
-// Start capture
-await execAsync({
-  command: 'pnpm',
-  args: ['captureStatic', projectSlug],
-  onStart: (proc) => {
-    captureProcess = proc;
-  },
-});
-
-// Cleanup: must manually track and kill both
-if (serverProcess) await killProcess('server', projectSlug, serverProcess.pid);
-if (captureProcess)
-  await killProcess('capture', projectSlug, captureProcess.pid);
-```
-
-**After:**
-
-```typescript
-import {
-  managedExecAsync,
-  getGlobalProcessManager,
-  ProcessType,
-} from './lib/process';
-
-const manager = getGlobalProcessManager();
-
-// ✅ Start server
-const { processId: serverId } = managedExecAsync({
-  command: 'pnpm',
-  args: ['runLocally', projectSlug],
-  processType: ProcessType.Server,
-  processName: `server-${projectSlug}`,
-  metadata: { projectSlug },
-  returnProcessId: true,
-});
-
-// ✅ Start capture as child of server
-const { processId: captureId } = managedExecAsync({
-  command: 'pnpm',
-  args: ['captureStatic', projectSlug],
-  processType: ProcessType.Capture,
-  processName: `capture-${projectSlug}`,
-  parentId: serverId, // ✅ Link parent-child relationship
-  metadata: { projectSlug },
-  returnProcessId: true,
-});
-
-// ✅ Cleanup: shutting down parent kills children too
-await manager.shutdown(serverId, { shutdownChildren: true });
-// Both server and capture are now killed!
-
-// ✅ Or better yet: signal handlers do this automatically
-```
-
-## Step 5: Query and Monitor Processes
-
-### Example: Monitoring Long-Running Processes
-
-```typescript
-import { getGlobalProcessManager, ProcessType } from './lib/process';
-
-const manager = getGlobalProcessManager();
-
-// ✅ Monitor all analyzers
-function monitorAnalyzers() {
-  const analyzers = manager.listByType(ProcessType.Analyzer);
-
-  console.log(`Running ${analyzers.length} analyzer(s):`);
-  analyzers.forEach((proc) => {
-    const uptime = Date.now() - proc.startedAt;
-    console.log(`  - ${proc.name} (PID ${proc.pid}): ${uptime}ms`);
-    if (proc.metadata) {
-      console.log(`    Metadata:`, proc.metadata);
-    }
-  });
-}
-
-// ✅ Find specific process
-function findProjectAnalyzer(projectSlug: string) {
-  const analyzers = manager.findByName(`analyzer-${projectSlug}`);
-  return analyzers[0] || null;
-}
-
-// ✅ Wait for process to complete
-async function waitForAnalysis(projectSlug: string) {
-  const manager = getGlobalProcessManager();
-
-  return new Promise<void>((resolve) => {
-    const checkInterval = setInterval(() => {
-      const analyzer = findProjectAnalyzer(projectSlug);
-
-      if (!analyzer || analyzer.state !== 'running') {
-        clearInterval(checkInterval);
-        resolve();
-      }
-    }, 1000);
-  });
-}
-```
-
-## Step 6: Handle Errors and Cleanup
-
-### Example: Graceful Error Handling
-
-**Before:**
-
-```typescript
-let serverProcess: ChildProcessWithoutNullStreams;
-
-try {
-  await execAsync({
-    command: 'node',
-    args: ['server.js'],
-    onStart: (proc) => {
-      serverProcess = proc;
-    },
-  });
-} catch (error) {
-  console.error('Server failed:', error);
-  // ❌ Manual cleanup needed
-  if (serverProcess) {
-    await killProcess('server', projectSlug, serverProcess.pid);
-  }
-  throw error;
-}
-```
-
-**After:**
-
-```typescript
-import { managedExecAsync, ProcessType } from './lib/process';
-
-try {
-  const exitCode = await managedExecAsync({
-    command: 'node',
-    args: ['server.js'],
-    processType: ProcessType.Server,
-    processName: 'main-server',
-  });
-
-  if (exitCode !== 0) {
-    throw new Error(`Server exited with code ${exitCode}`);
-  }
-} catch (error) {
-  console.error('Server failed:', error);
-  // ✅ No manual cleanup needed - signal handlers got it!
-  throw error;
-}
-```
-
-## Complete Integration Example
-
-Here's a complete before/after for `orchestrate.ts`:
-
-### Before:
-
-```typescript
-import execAsync from './lib/virtualized/common/execAsync';
-import killProcessAndSubprocesses from '~codeyam/utils/src/lib/killProcessAndSubprocesses.server';
-
-interface ProcessMap {
-  server?: ChildProcessWithoutNullStreams;
-  capture?: ChildProcessWithoutNullStreams;
-}
-
-async function orchestrate(projectSlug: string) {
-  const processMap: ProcessMap = {};
-
-  try {
-    // Start server
-    await execAsync({
-      command: 'pnpm',
-      args: ['runLocally', projectSlug],
-      onStart: (proc) => {
-        processMap.server = proc;
-        console.log(`Server started with PID ${proc.pid}`);
-      },
-    });
-
-    // Start capture
-    await execAsync({
-      command: 'pnpm',
-      args: ['captureStatic', projectSlug],
-      onStart: (proc) => {
-        processMap.capture = proc;
-        console.log(`Capture started with PID ${proc.pid}`);
-      },
-    });
-  } catch (error) {
-    console.error('Orchestration failed:', error);
-
-    // Manual cleanup
-    if (processMap.server) {
-      await killProcessAndSubprocesses(
-        'server',
-        projectSlug,
-        processMap.server.pid,
-      );
-    }
-    if (processMap.capture) {
-      await killProcessAndSubprocesses(
-        'capture',
-        projectSlug,
-        processMap.capture.pid,
-      );
-    }
-
-    throw error;
-  }
-}
-
-// SIGINT handler
-process.on('SIGINT', async () => {
-  console.log('Cleaning up...');
-  if (processMap.server) {
-    await killProcessAndSubprocesses(
-      'server',
-      projectSlug,
-      processMap.server.pid,
-    );
-  }
-  if (processMap.capture) {
-    await killProcessAndSubprocesses(
-      'capture',
-      projectSlug,
-      processMap.capture.pid,
-    );
-  }
-  process.exit(0);
-});
-```
-
-### After:
-
-```typescript
-import {
-  installSignalHandlers,
-  managedExecAsync,
-  getGlobalProcessManager,
-  ProcessType,
-} from './lib/process';
-
-// ✅ One line replaces all manual signal handling
-installSignalHandlers();
-
-async function orchestrate(projectSlug: string) {
-  const manager = getGlobalProcessManager();
-
-  // ✅ Start server with automatic tracking
-  const { processId: serverId } = managedExecAsync({
-    command: 'pnpm',
-    args: ['runLocally', projectSlug],
-    processType: ProcessType.Server,
-    processName: `server-${projectSlug}`,
-    metadata: { projectSlug },
-    returnProcessId: true,
-    onStdout: (data) => {
-      const serverInfo = manager.getInfo(serverId);
-      console.log(`[Server ${serverInfo?.pid}] ${data}`);
-    },
-  });
-
-  // ✅ Start capture as child of server
-  const { processId: captureId } = managedExecAsync({
-    command: 'pnpm',
-    args: ['captureStatic', projectSlug],
-    processType: ProcessType.Capture,
-    processName: `capture-${projectSlug}`,
-    parentId: serverId,
-    metadata: { projectSlug },
-    returnProcessId: true,
-    onStdout: (data) => {
-      const captureInfo = manager.getInfo(captureId);
-      console.log(`[Capture ${captureInfo?.pid}] ${data}`);
-    },
-  });
-
-  // ✅ No try/catch needed for cleanup
-  // ✅ No SIGINT handler needed
-  // ✅ All processes automatically cleaned up on exit/error/signal
-}
-```
-
-## Migration Checklist
-
-For each CLI entry point:
-
-- [ ] Add `installSignalHandlers()` at the top of the file
-- [ ] Replace `execAsync` with `managedExecAsync`
-- [ ] Replace `ProcessMap` tracking with `managedExecAsync({ returnProcessId: true })`
-- [ ] Remove manual `killProcess` / `killProcessAndSubprocesses` calls
-- [ ] Remove manual SIGINT/SIGTERM handlers
-- [ ] Add parent-child relationships where appropriate
-- [ ] Add metadata for easier debugging/monitoring
-- [ ] Test that processes are cleaned up on Ctrl+C
-- [ ] Test that processes are cleaned up on uncaught errors
-- [ ] Update tests to use the new process management system
-
-## Testing Your Integration
-
-1. **Test Ctrl+C cleanup:**
-
-   ```bash
-   pnpm runLocally my-project
-   # Press Ctrl+C
-   # Check that all processes are killed: ps aux | grep CODEYAM
-   ```
-
-2. **Test error cleanup:**
-
-   ```typescript
-   // Add a deliberate error in your code
-   throw new Error('Test error');
-   // Check that all processes are killed
-   ```
-
-3. **Test normal exit:**
-
-   ```bash
-   pnpm runLocally my-project --steps analyze
-   # Let it complete normally
-   # Check that all processes are cleaned up
-   ```
-
-4. **Monitor processes:**
-   ```typescript
-   const manager = getGlobalProcessManager();
-   console.log('Active processes:', manager.listAll());
-   ```
-
-## Tips
-
-1. **Always use processType**: This helps with querying and debugging
-2. **Use descriptive processNames**: Include project slug or other identifiers
-3. **Add metadata**: Store useful context for debugging
-4. **Use parent-child relationships**: Makes cleanup easier and more organized
-5. **Let signal handlers do the work**: Don't write manual cleanup code
-6. **Trust the tests**: 57 tests ensure the system works correctly