@codeyam/codeyam-cli 0.1.0-staging.596f0eb → 0.1.0-staging.6e699e5

package/analyzer-template/packages/analyze/src/lib/files/scenarios/generateKeyAttributes.ts

@@ -1,115 +0,0 @@
-import {
-  Analysis,
-  Entity,
-  DEFAULT_SCENARIO_NAME,
-  ReadonlyAnalysisMap,
-} from '~codeyam/types';
-import measureAndReportExecutionTime from '../../utils/measureAndReportExecutionTime';
-import { AI, generateEntityKeyAttributes } from '~codeyam/ai';
-import { awsLog } from '~codeyam/utils';
-import { gatherRelevantDependentKeyAttributes } from '~codeyam/ai';
-import { gatherDataForMocks } from './generateScenarioData';
-
-export interface GenerateEntityKeyAttributesArgs {
-  entity: Entity;
-  analysis: Analysis;
-  dependentAnalyses: ReadonlyAnalysisMap;
-  error?: boolean;
-  model: AI.Model;
-  updateProgress?: (detail: string) => void;
-}
-
-export default async function generateKeyAttributes({
-  entity,
-  analysis,
-  dependentAnalyses,
-  error,
-  model,
-  updateProgress,
-}: GenerateEntityKeyAttributesArgs): Promise<void> {
-  if (!['visual', 'library'].includes(entity.entityType)) return;
-
-  // Merge direct dataForMocks with recursively gathered data from dependencies
-  const structure = {
-    arguments: analysis.metadata.scenariosDataStructure?.arguments ?? [],
-    dataForMocks: {
-      ...(analysis.metadata.scenariosDataStructure?.dataForMocks ?? {}),
-      ...gatherDataForMocks(analysis, dependentAnalyses),
-    },
-  };
-
-  awsLog(`🔮 Generating ${error ? 'error ' : ''}scenarios for`, {
-    filePath: entity.filePath,
-    entityName: entity.name,
-    structure,
-  });
-
-  if (
-    !structure ||
-    (Object.keys(structure.dataForMocks ?? {}).length === 0 &&
-      (structure.arguments ?? []).length === 0)
-  ) {
-    if (!error) {
-      analysis.scenarios = [
-        {
-          projectId: analysis.projectId,
-          analysisId: analysis.id,
-          name: DEFAULT_SCENARIO_NAME,
-          description: 'The only external state the component can be in.',
-          metadata: {
-            testName: 'it("renders correctly")',
-            keyAttributeInstructions: {},
-          },
-        },
-      ];
-    }
-
-    return;
-  }
-
-  if (!analysis.metadata.keyAttributes) {
-    const {
-      result: { keyAttributes, llmCall: keyAttributesLLMCall },
-    } = await measureAndReportExecutionTime(
-      () =>
-        generateEntityKeyAttributes({
-          entity,
-          mergedDataStructure: analysis.metadata.mergedDataStructure,
-          model,
-        }),
-      `Generating entity key attributes`,
-      updateProgress,
-    );
-
-    const relevantDependentKeyAttributes = gatherRelevantDependentKeyAttributes(
-      entity,
-      analysis.metadata.mergedDataStructure,
-      dependentAnalyses,
-    );
-
-    analysis.metadata.keyAttributes = [
-      ...keyAttributes,
-      ...relevantDependentKeyAttributes.map((ka) => ({
-        ...ka,
-        // Spread to convert readonly arrays to mutable arrays (with fallback for undefined)
-        validValueOptions: [...(ka.validValueOptions ?? [])],
-        errorValueOptions: [...(ka.errorValueOptions ?? [])],
-        // Convert readonly dependencies array to mutable if present
-        ...(ka.dependencies && {
-          dependencies: ka.dependencies.map((dep) => ({ ...dep })),
-        }),
-      })),
-    ].filter(
-      (ka, index, self) =>
-        self.findIndex((k) => k.internalPath === ka.internalPath) === index,
-    );
-
-    if (keyAttributesLLMCall) {
-      analysis.metadata.llmCalls ||= [];
-      analysis.metadata.llmCalls.push({
-        name: `generateEntityKeyAttributes`,
-        id: keyAttributesLLMCall.id,
-      });
-    }
-  }
-}

package/analyzer-template/process/INTEGRATION_COMPLETE.md

@@ -1,333 +0,0 @@
-# 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)