process-management

Process Management Rules

Zombie Process Prevention

ALWAYS use the process cleanup utility for spawning child processes:

// ❌ BAD - Can create zombie processes
const proc = Bun.spawn(['command', 'args']);
await Promise.race([proc.exited, timeout]); // Process not killed on timeout

// ✅ GOOD - Automatic cleanup
import processManager from './tests/utils/process-cleanup';
const proc = processManager.spawn(['command', 'args']);
try {
  await Promise.race([proc.exited, timeout]);
} catch (error) {
  await processManager.kill(proc, 15, 2000);
} finally {
  await processManager.killAll(3000);
}

Process Spawning Patterns

Script Files

For automation scripts that spawn processes:

import processManager from '../tests/utils/process-cleanup';

async function runCommand(command: string[], timeout: number) {
  const proc = processManager.spawn(command, {
    cwd: process.cwd(),
    stdio: ['ignore', 'pipe', 'pipe']
  });
  
  try {
    const exitCode = await Promise.race([
      proc.exited,
      new Promise<never>((_, reject) => 
        setTimeout(() => reject(new Error('Timeout')), timeout)
      )
    ]);
    return exitCode === 0;
  } catch (error) {
    await processManager.kill(proc, 15, 2000);
    throw error;
  }
}

Test Files

Always use process manager in tests:

import { describe, test, beforeEach, afterEach } from 'bun:test';
import processManager from '../utils/process-cleanup';

describe('My Test Suite', () => {
  afterEach(async () => {
    // Cleanup all spawned processes after each test
    await processManager.killAll(3000);
  });
  
  test('should spawn process', async () => {
    const proc = processManager.spawn(['echo', 'hello']);
    await proc.exited;
  });
});

Signal Handling

Always ensure scripts handle cleanup on exit:

// Automatic via processManager (recommended)
import processManager from './tests/utils/process-cleanup';
// Signal handlers are automatically set up

// Or manual (if needed)
process.on('SIGINT', async () => {
  console.log('Cleaning up...');
  await processManager.killAll(3000);
  process.exit(0);
});