process-management · v1.0.0 · 2025-10-08 · sha256 1a040d7e07fe9a46
process-management v1.0.0A
Immutable. This exact content never changes and is served at /api/v1/blob/1a040d7e07fe9a46.
---
version: "1.0.0"
globs: "*.ts,*.js"
description: "Process management and zombie process prevention patterns"
lastUpdated: "2025-10-08"
dependencies: ["bun-runtime", "quality-standards"]
---
# Process Management Rules
## Zombie Process Prevention
**ALWAYS use the process cleanup utility for spawning child processes:**
```typescript
// ❌ 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:
```typescript
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:
```typescript
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:
```typescript
// 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);
});
```
## Timeout Enforcement
**ALWAYS set timeouts for spawned processes:**
```typescript
// ❌ BAD - No timeout
await proc.exited;
// ✅ GOOD - With timeout
await Promise.race([
proc.exited,
new Promise((_, reject) =>
setTimeout(() => reject(new Error('Timeout')), 30000)
)
]);
```
## Cleanup Patterns
### Try-Finally Pattern
```typescript
let proc;
try {
proc = processManager.spawn(['command']);
await proc.exited;
} finally {
if (proc) {
await processManager.kill(proc);
}
await processManager.killAll(); // Cleanup all
}
```
### Async Function Cleanup
```typescript
async function myFunction() {
try {
const proc = processManager.spawn(['command']);
return await proc.exited;
} finally {
await processManager.killAll(3000);
}
}
```
## Key Files
- [Process Cleanup Utility](mdc:tests/utils/process-cleanup.ts) - Global process manager
- [CI Local Script](mdc:scripts/ci-local.ts) - Example usage in CI
- [Build Automation](mdc:scripts/automation/build-and-test.ts) - Example usage in automation
## Rules Summary
1. ✅ **Always** use `processManager.spawn()` instead of `Bun.spawn()` directly
2. ✅ **Always** set timeouts for process execution
3. ✅ **Always** kill processes on timeout/error
4. ✅ **Always** cleanup in `finally` blocks
5. ✅ **Always** call `processManager.killAll()` at script end
6. ❌ **Never** leave spawned processes untracked
7. ❌ **Never** spawn processes without timeout
8. ❌ **Never** forget cleanup in test `afterEach`