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

package/analyzer-template/packages/supabase/src/lib/scenarioToDb.ts

@@ -1,34 +0,0 @@
-import { Scenario } from '~codeyam/types';
-import { type Insertable } from 'kysely';
-import { ScenariosTable } from './kysely/tables/scenariosTable';
-import { randomUUID } from 'crypto';
-
-export default function scenarioToDb(
-  scenario: Scenario,
-): Insertable<ScenariosTable> {
-  const {
-    id,
-    projectId,
-    analysisId,
-    previousVersionId,
-    analysis,
-    metadata,
-    ...remaining
-  } = scenario;
-
-  delete remaining.userScenarios;
-  delete remaining.comments;
-
-  if ('created_at' in remaining) {
-    delete remaining.created_at;
-  }
-
-  return {
-    ...remaining,
-    id: id ?? randomUUID(),
-    metadata: metadata ? JSON.stringify(metadata) : null,
-    project_id: projectId,
-    analysis_id: analysisId,
-    previous_version_id: previousVersionId,
-  };
-}

package/analyzer-template/packages/supabase/src/lib/updateCommitMetadata.ts

@@ -1,188 +0,0 @@
-/*
- * updates commit metadata by merging partial updates with existing data.
- * uses database transactions to ensure atomic updates and handle concurrent modifications.
- */
-import {
-  Commit,
-  CommitMetadata,
-  CommitRunStatus,
-  DeepReadonly,
-} from '~codeyam/types';
-import { getDatabase } from './kysely/db';
-import { awsLog } from '~codeyam/utils';
-import { deepMerge, DeepUpdate } from './jsonUpdateUtils';
-import dbToCommit from './dbToCommit';
-import { ExpressionBuilder } from 'kysely';
-
-type UpdateCommitMetadataArgs = {
-  commitId?: string;
-  commitSha?: string;
-  metadataUpdate?: DeepUpdate<CommitMetadata>;
-  runStatusUpdate?: DeepUpdate<CommitRunStatus>;
-  archiveCurrentRun?: boolean;
-  updateCallback?: (
-    metadata: CommitMetadata,
-    commit: DeepReadonly<Commit>,
-  ) => void | Promise<void>;
-};
-
-export default async function updateCommitMetadata({
-  commitId,
-  commitSha,
-  metadataUpdate,
-  runStatusUpdate,
-  archiveCurrentRun,
-  updateCallback,
-}: UpdateCommitMetadataArgs): Promise<CommitMetadata | null> {
-  try {
-    return await getDatabase()
-      .transaction()
-      .execute(async (trx) => {
-        const commit = await trx
-          .selectFrom('commits')
-          .selectAll()
-          .$if(!!commitId, (qb: any) => qb.where('id', '=', commitId))
-          .$if(!!commitSha, (qb: any) => qb.where('sha', '=', commitSha))
-          .executeTakeFirst();
-
-        if (!commit) {
-          awsLog(
-            `CodeYam Error: updateCommitMetadata(): Commit ${commitId} not found`,
-          );
-          return null;
-        }
-
-        // Initialize metadata if it doesn't exist (metadata is already parsed from DB)
-        const currentMetadata: CommitMetadata = commit.metadata || {};
-
-        // if the convenience parameter for latest run was supplied, merge it in
-        if (runStatusUpdate) {
-          runStatusUpdate.lastUpdatedAt ??= new Date().toISOString();
-
-          if (runStatusUpdate.currentEntityShas !== undefined) {
-            console.log(
-              `[updateCommitMetadata] Updating currentRun.currentEntityShas`,
-            );
-            console.log(`[updateCommitMetadata] Commit SHA: ${commitSha}`);
-            console.log(
-              `[updateCommitMetadata] Previous entity SHAs:`,
-              currentMetadata.currentRun?.currentEntityShas,
-            );
-            console.log(
-              `[updateCommitMetadata] New entity SHAs:`,
-              runStatusUpdate.currentEntityShas,
-            );
-            console.log(
-              `[updateCommitMetadata] Archive flag:`,
-              archiveCurrentRun,
-            );
-          }
-
-          metadataUpdate = deepMerge(metadataUpdate ?? {}, {
-            currentRun: runStatusUpdate,
-          });
-        } else if (!metadataUpdate && !updateCallback) {
-          return currentMetadata; // nothing to update
-        }
-
-        // Deep merge the baseline status updates
-        const updatedMetadata: CommitMetadata = metadataUpdate
-          ? deepMerge(currentMetadata, metadataUpdate)
-          : currentMetadata;
-
-        // Archive current run if requested
-        if (archiveCurrentRun && updatedMetadata.currentRun) {
-          console.log(
-            `[updateCommitMetadata] ========================================`,
-          );
-          console.log(`[updateCommitMetadata] ARCHIVING CURRENT RUN`);
-          console.log(`[updateCommitMetadata] Commit SHA: ${commitSha}`);
-          console.log(
-            `[updateCommitMetadata] Current run entity SHAs:`,
-            updatedMetadata.currentRun.currentEntityShas,
-          );
-          console.log(
-            `[updateCommitMetadata] Current run PIDs: analyzer=${updatedMetadata.currentRun.analyzerPid}, capture=${updatedMetadata.currentRun.capturePid}`,
-          );
-          console.log(
-            `[updateCommitMetadata] Current run completed: analyses=${updatedMetadata.currentRun.analysesCompleted}, captures=${updatedMetadata.currentRun.capturesCompleted}`,
-          );
-          console.log(
-            `[updateCommitMetadata] Historical runs before archiving: ${updatedMetadata.historicalRuns?.length || 0}`,
-          );
-
-          const runToArchive: CommitRunStatus = {
-            ...updatedMetadata.currentRun,
-            archivedAt: new Date().toISOString(),
-          };
-
-          console.log(
-            `[updateCommitMetadata] Run to archive:`,
-            JSON.stringify(runToArchive, null, 2),
-          );
-
-          updatedMetadata.historicalRuns = [
-            ...(updatedMetadata.historicalRuns || []),
-            runToArchive,
-          ];
-
-          console.log(
-            `[updateCommitMetadata] Historical runs after archiving: ${updatedMetadata.historicalRuns.length}`,
-          );
-          console.log(
-            `[updateCommitMetadata] All historical runs:`,
-            JSON.stringify(
-              updatedMetadata.historicalRuns.map((r) => ({
-                entityShas: r.currentEntityShas,
-                archivedAt: r.archivedAt,
-                completed: {
-                  analyses: r.analysesCompleted,
-                  captures: r.capturesCompleted,
-                },
-              })),
-              null,
-              2,
-            ),
-          );
-          console.log(
-            `[updateCommitMetadata] ========================================`,
-          );
-        }
-
-        // Allow callback to perform complex atomic updates
-        if (updateCallback) {
-          await updateCallback(updatedMetadata, dbToCommit(commit));
-        }
-
-        try {
-          const result = await trx
-            .updateTable('commits')
-            .set({ metadata: JSON.stringify(updatedMetadata) })
-            .where('id', '=', commit.id)
-            .returningAll()
-            .executeTakeFirst();
-
-          if (!result) {
-            awsLog(
-              `CodeYam Error: updateCommitMetadata(): Failed to update commit ${commitId}`,
-            );
-            return currentMetadata;
-          }
-
-          return updatedMetadata;
-        } catch (error) {
-          awsLog(
-            `CodeYam Error: updateCommitMetadata(): Failed to update commit ${commitId}`,
-            error,
-          );
-          return currentMetadata;
-        }
-      });
-  } catch (error) {
-    awsLog(
-      `CodeYam Error: updateCommitMetadata(): Transaction failed for commit ${commitId}`,
-      error,
-    );
-    return null;
-  }
-}

package/analyzer-template/packages/supabase/src/lib/updateProjectMetadata.ts

@@ -1,96 +0,0 @@
-/*
- * Updates project metadata by merging partial updates with existing data.
- * Uses database transactions to ensure atomic updates and handle concurrent modifications.
- */
-import { DeepReadonly, Project, ProjectMetadata } from '~codeyam/types';
-import { getDatabase } from './kysely/db';
-import { awsLog } from '~codeyam/utils';
-import { deepMerge } from './jsonUpdateUtils';
-import dbToProject from './dbToProject';
-import { ExpressionBuilder } from 'kysely';
-
-type UpdateProjectMetadataArgs = {
-  projectId?: string;
-  projectSlug?: string;
-  metadataUpdate?: Project['metadata'];
-  updateCallback?: (
-    metadata: Project['metadata'],
-    project: DeepReadonly<Project>,
-  ) => void | Promise<void>;
-};
-
-export default async function updateProjectMetadata({
-  projectId,
-  projectSlug,
-  metadataUpdate,
-  updateCallback,
-}: UpdateProjectMetadataArgs): Promise<ProjectMetadata | null> {
-  if (!projectId && !projectSlug) {
-    throw new Error('Either projectId or projectSlug must be provided');
-  }
-  try {
-    return await getDatabase()
-      .transaction()
-      .execute(async (trx) => {
-        const project = await trx
-          .selectFrom('projects')
-          .selectAll()
-          .$if(!!projectId, (qb: any) => qb.where('id', '=', projectId))
-          .$if(!!projectSlug, (qb: any) => qb.where('slug', '=', projectSlug))
-          .executeTakeFirst();
-
-        if (!project) {
-          awsLog(
-            `CodeYam Error: updateProjectMetadata(): Project ${projectId} not found`,
-          );
-          return null;
-        }
-
-        // Initialize metadata if it doesn't exist (metadata is already parsed from DB)
-        const currentMetadata: ProjectMetadata = project.metadata || {};
-        if (!metadataUpdate && !updateCallback) {
-          return currentMetadata; // nothing to update
-        }
-
-        // Deep merge the baseline status updates
-        const updatedMetadata: ProjectMetadata = metadataUpdate
-          ? deepMerge(currentMetadata, metadataUpdate)
-          : currentMetadata;
-
-        // Allow callback to perform complex atomic updates
-        if (updateCallback) {
-          await updateCallback(updatedMetadata, dbToProject(project));
-        }
-
-        try {
-          const result = await trx
-            .updateTable('projects')
-            .set({ metadata: JSON.stringify(updatedMetadata) })
-            .where('id', '=', project.id)
-            .returningAll()
-            .executeTakeFirst();
-
-          if (!result) {
-            awsLog(
-              `CodeYam Error: updateProjectMetadata(): Failed to update project ${projectId}`,
-            );
-            return null;
-          }
-
-          return updatedMetadata;
-        } catch (error) {
-          awsLog(
-            `CodeYam Error: updateProjectMetadata(): Failed to update project ${projectId}`,
-            error,
-          );
-          return null;
-        }
-      });
-  } catch (error) {
-    awsLog(
-      `CodeYam Error: updateProjectMetadata(): Transaction failed for project ${projectId}`,
-      error,
-    );
-    return null;
-  }
-}

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)