@codeyam/codeyam-cli 0.1.0-staging.1 → 0.1.0-staging.1669d45

package/analyzer-template/process/README.md

@@ -1,507 +0,0 @@
-# Process Management System
-
-A comprehensive, test-driven process management system for CodeYam that provides:
-
-- Automatic tracking and registration of all spawned processes
-- Graceful shutdown with signal escalation (SIGINT → SIGTERM → SIGKILL)
-- Parent-child process relationships
-- Process metadata and querying capabilities
-- Global cleanup on exit/error/signal
-
-## Test Coverage
-
-✅ 57 tests passing across 3 test suites:
-
-- `ProcessManager.test.ts` - 32 tests for core functionality
-- `GlobalProcessManager.test.ts` - 8 tests for singleton and signal handling
-- `managedExecAsync.test.ts` - 17 tests for the managed spawn wrapper
-
-## Architecture
-
-### Core Components
-
-1. **ProcessManager** (`ProcessManager.ts`)
-   - Central registry for tracking process lifecycle
-   - Manages state transitions (running → completed/failed/killed)
-   - Supports parent-child relationships
-   - Event emitter for process lifecycle events
-
-2. **GlobalProcessManager** (`GlobalProcessManager.ts`)
-   - Singleton wrapper around ProcessManager
-   - Installs signal handlers for graceful shutdown
-   - Ensures cleanup on SIGINT, SIGTERM, uncaughtException, unhandledRejection
-
-3. **managedExecAsync** (`managedExecAsync.ts`)
-   - Drop-in replacement for `spawn()` with automatic lifecycle management
-   - Registers processes with the global manager
-   - Supports all spawn options plus additional metadata
-
-## Quick Start
-
-### 1. Add Signal Handlers to CLI Entry Points
-
-At the top of each CLI entry point (e.g., `runLocally.ts`, `orchestrate.ts`):
-
-```typescript
-import { installSignalHandlers } from './lib/process';
-
-// Install once at the top of the file
-installSignalHandlers();
-
-// Rest of your code...
-```
-
-This ensures ALL processes are cleaned up when:
-
-- User presses Ctrl+C (SIGINT)
-- Process receives SIGTERM
-- Uncaught exception occurs
-- Unhandled promise rejection occurs
-
-### 2. Use managedExecAsync Instead of spawn
-
-#### Before:
-
-```typescript
-import { spawn } from 'child_process';
-
-const process = spawn('node', ['dist/analyzer/start.js'], {
-  detached: true,
-  env: { ...process.env, CODEYAM_PROCESS_NAME: 'analyzer' },
-});
-
-// No automatic cleanup, must manually track
-```
-
-#### After:
-
-```typescript
-import { managedExecAsync, ProcessType } from './lib/process';
-
-const exitCode = await managedExecAsync({
-  command: 'node',
-  args: ['dist/analyzer/start.js'],
-  processType: ProcessType.Analyzer,
-  processName: 'main-analyzer',
-  metadata: { projectId: 'abc123' },
-});
-
-// Automatically tracked and cleaned up on exit!
-```
-
-### 3. Manual Process Control
-
-For cases where you need more control:
-
-```typescript
-import { getGlobalProcessManager, ProcessType } from './lib/process';
-
-const manager = getGlobalProcessManager();
-
-// List all running processes
-const allProcesses = manager.listAll();
-console.log(`Running ${allProcesses.length} processes`);
-
-// Find specific processes
-const servers = manager.listByType(ProcessType.Server);
-const analyzersByName = manager.findByName('main-analyzer');
-
-// Shutdown specific processes
-await manager.shutdown(processId);
-
-// Shutdown all processes of a type
-await manager.shutdownByType(ProcessType.Capture);
-
-// Shutdown everything
-await manager.shutdownAll();
-```
-
-## Process Types
-
-```typescript
-enum ProcessType {
-  Server = 'server', // Web servers (Next.js, Remix, etc.)
-  Analyzer = 'analyzer', // Analysis workers
-  Capture = 'capture', // Playwright capture processes
-  Controller = 'controller', // Controller servers
-  Worker = 'worker', // Worker threads
-  Project = 'project', // Project-specific processes
-  Other = 'other', // Miscellaneous
-}
-```
-
-## Process States
-
-```typescript
-enum ProcessState {
-  Running = 'running', // Process is currently running
-  Completed = 'completed', // Process exited normally (exit code 0)
-  Failed = 'failed', // Process exited with non-zero code
-  Killed = 'killed', // Process was killed by signal
-}
-```
-
-## Advanced Usage
-
-### Parent-Child Relationships
-
-Track hierarchical process relationships:
-
-```typescript
-// Start parent
-const { processId: parentId } = managedExecAsync({
-  command: 'node',
-  args: ['server.js'],
-  processType: ProcessType.Server,
-  processName: 'main-server',
-  returnProcessId: true,
-});
-
-// Start child with parent reference
-const { processId: childId } = managedExecAsync({
-  command: 'node',
-  args: ['worker.js'],
-  processType: ProcessType.Worker,
-  processName: 'worker-1',
-  parentId,
-  returnProcessId: true,
-});
-
-// Shutdown parent and all children
-await manager.shutdown(parentId, { shutdownChildren: true });
-```
-
-### Process Metadata
-
-Store arbitrary metadata with processes:
-
-```typescript
-await managedExecAsync({
-  command: 'node',
-  args: ['analyze.js'],
-  processType: ProcessType.Analyzer,
-  processName: 'project-analyzer',
-  metadata: {
-    projectId: 'project-123',
-    commitSha: 'abc123def',
-    analysisType: 'full',
-    startedBy: 'user@example.com',
-  },
-});
-
-// Query later
-const analyzers = manager.listByType(ProcessType.Analyzer);
-analyzers.forEach((proc) => {
-  console.log(`Analyzing ${proc.metadata?.projectId}`);
-});
-```
-
-### Stream Output
-
-Capture stdout/stderr:
-
-```typescript
-const output: string[] = [];
-const errors: string[] = [];
-
-await managedExecAsync({
-  command: 'npm',
-  args: ['run', 'build'],
-  processType: ProcessType.Other,
-  processName: 'build',
-  onStdout: (data) => output.push(data.toString()),
-  onStderr: (data) => errors.push(data.toString()),
-});
-
-console.log('Build output:', output.join(''));
-```
-
-### Abort Signals
-
-Cancel processes programmatically:
-
-```typescript
-const abortController = new AbortController();
-
-const buildPromise = managedExecAsync({
-  command: 'npm',
-  args: ['run', 'build'],
-  processType: ProcessType.Other,
-  signal: abortController.signal,
-});
-
-// Cancel after 30 seconds
-setTimeout(() => abortController.abort(), 30000);
-
-await buildPromise; // Will be killed if timeout reached
-```
-
-### Event Listeners
-
-React to process lifecycle events:
-
-```typescript
-const manager = getGlobalProcessManager();
-
-manager.on('processStarted', (info) => {
-  console.log(`Started ${info.name} (PID: ${info.pid})`);
-});
-
-manager.on('processExited', (info) => {
-  console.log(`Exited ${info.name} with code ${info.exitCode}`);
-});
-```
-
-## Integration Examples
-
-### Example 1: Update runLocally.ts
-
-```typescript
-import {
-  installSignalHandlers,
-  managedExecAsync,
-  ProcessType,
-} from './lib/process';
-
-installSignalHandlers();
-
-async function runLocally(args: RunLocallyArgs) {
-  // Start analyzer
-  const analyzerExitCode = await managedExecAsync({
-    command: 'node',
-    args: ['dist/project/start.js', ...buildArgs(args)],
-    processType: ProcessType.Analyzer,
-    processName: 'local-analyzer',
-    metadata: { projectSlug: args.projectSlug },
-    env: {
-      ...process.env,
-      PROJECT_SLUG: args.projectSlug,
-    },
-  });
-
-  if (analyzerExitCode !== 0) {
-    throw new Error(`Analyzer failed with code ${analyzerExitCode}`);
-  }
-
-  // All processes automatically cleaned up on exit
-}
-```
-
-### Example 2: Update orchestrate.ts
-
-```typescript
-import {
-  installSignalHandlers,
-  managedExecAsync,
-  getGlobalProcessManager,
-  ProcessType,
-} from './lib/process';
-
-installSignalHandlers();
-
-async function runOrchestration(projectSlug: string) {
-  const manager = getGlobalProcessManager();
-
-  // Start server
-  const { processId: serverId } = managedExecAsync({
-    command: 'pnpm',
-    args: ['runLocally:no-build', projectSlug],
-    processType: ProcessType.Server,
-    processName: 'project-server',
-    metadata: { projectSlug },
-    returnProcessId: true,
-  });
-
-  // Start capture with parent relationship
-  const { processId: captureId } = managedExecAsync({
-    command: 'pnpm',
-    args: ['captureStatic:no-build', projectSlug],
-    processType: ProcessType.Capture,
-    processName: 'screenshot-capture',
-    parentId: serverId,
-    metadata: { projectSlug },
-    returnProcessId: true,
-  });
-
-  // Monitor progress
-  const checkProgress = setInterval(() => {
-    const capture = manager.getInfo(captureId);
-    if (capture?.state !== 'running') {
-      clearInterval(checkProgress);
-    }
-  }, 1000);
-
-  // Cleanup happens automatically via signal handlers
-}
-```
-
-## Cleanup Behavior
-
-### Automatic Cleanup Triggers
-
-The system automatically cleans up ALL managed processes when:
-
-1. **Normal Exit**: Process exits normally
-2. **SIGINT**: User presses Ctrl+C
-3. **SIGTERM**: System sends termination signal
-4. **Uncaught Exception**: Unhandled error occurs
-5. **Unhandled Rejection**: Promise rejection not caught
-
-### Cleanup Strategy
-
-For each process, the system:
-
-1. Sends SIGINT and waits up to 5 seconds
-2. If still running, sends SIGTERM and waits up to 5 seconds
-3. If still running, sends SIGKILL and waits up to 2 seconds
-4. Recursively kills all child processes first (bottom-up)
-
-### Manual Cleanup
-
-You can also manually clean up:
-
-```typescript
-const manager = getGlobalProcessManager();
-
-// Cleanup completed processes older than 1 minute
-manager.cleanupCompleted({ retentionMs: 60000 });
-
-// Shutdown all and cleanup immediately
-await manager.shutdownAll();
-manager.cleanupCompleted({ retentionMs: 0 });
-```
-
-## Migration Guide
-
-### Migrating from execAsync
-
-The old `execAsync` function can be gradually replaced:
-
-```typescript
-// Old way
-import execAsync from './lib/virtualized/common/execAsync';
-
-await execAsync({
-  command: 'node',
-  args: ['script.js'],
-  env: { CODEYAM_PROCESS_NAME: 'my-script' },
-  // ... other options
-});
-
-// New way
-import { managedExecAsync, ProcessType } from './lib/process';
-
-await managedExecAsync({
-  command: 'node',
-  args: ['script.js'],
-  processType: ProcessType.Other,
-  processName: 'my-script',
-  env: { CUSTOM_VAR: 'value' },
-  // ... other options
-});
-```
-
-### Migrating Process Tracking
-
-Old manual tracking code:
-
-```typescript
-const processMap: ProcessMap = { server: undefined, capture: undefined };
-
-const serverProcess = spawn('node', ['server.js']);
-processMap.server = serverProcess;
-
-// ... later ...
-if (processMap.server) {
-  await killProcess(processMap.server.pid);
-}
-```
-
-New automatic tracking:
-
-```typescript
-const { processId } = managedExecAsync({
-  command: 'node',
-  args: ['server.js'],
-  processType: ProcessType.Server,
-  processName: 'server',
-  returnProcessId: true,
-});
-
-// ... later ...
-const manager = getGlobalProcessManager();
-await manager.shutdown(processId);
-
-// Or just let signal handlers clean up automatically!
-```
-
-## Testing
-
-Run the test suite:
-
-```bash
-# Run all process management tests
-npx jest background/src/lib/process/__tests__/
-
-# Run specific test file
-npx jest background/src/lib/process/__tests__/ProcessManager.test.ts
-
-# Run with coverage
-npx jest background/src/lib/process/__tests__/ --coverage
-```
-
-## Troubleshooting
-
-### Processes Not Cleaning Up
-
-If processes aren't being cleaned up:
-
-1. Ensure `installSignalHandlers()` is called at the top of your CLI entry point
-2. Check that you're using `managedExecAsync` instead of raw `spawn()`
-3. Verify the global process manager is being used
-
-### Orphaned Processes
-
-If you find orphaned processes:
-
-```bash
-# Find all CodeYam processes
-ps aux | grep CODEYAM
-
-# Kill all CodeYam processes
-pkill -f CODEYAM_PROCESS_NAME
-```
-
-### Test Pollution
-
-If tests are interfering with each other:
-
-```typescript
-afterEach(async () => {
-  const manager = getGlobalProcessManager();
-  await manager.shutdownAll();
-  manager.cleanupCompleted({ retentionMs: 0 });
-});
-```
-
-## Future Enhancements
-
-Potential improvements:
-
-- [ ] Persistent process registry (SQLite) for cross-restart tracking
-- [ ] Process resource monitoring (CPU, memory)
-- [ ] Automatic restart on failure
-- [ ] Process pooling and reuse
-- [ ] Integration with Docker container lifecycle
-- [ ] Web dashboard for process monitoring
-- [ ] Structured logging integration
-- [ ] Metrics/telemetry export
-
-## API Reference
-
-See the inline documentation in:
-
-- `ProcessManager.ts` - Core process management
-- `GlobalProcessManager.ts` - Singleton and signal handling
-- `managedExecAsync.ts` - Managed spawn wrapper
-- `index.ts` - Exported API

package/background/src/lib/process/GlobalProcessManager.js.map

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