# Shout — Proposed Improvements

Two additions to the shout test framework: automatic process cleanup and test isolation primitives.

## 1. Automatic Process Cleanup

### Problem

Any test that backgrounds a process (`&`) must manually clean it up. If a test fails or times out before reaching its cleanup command, the process is orphaned and holds its port indefinitely. Every test author has to remember the `trap` pattern:

```
$ my-server &; SVR=$!; trap "kill $SVR 2>/dev/null" EXIT; ...
```

This is error-prone and noisy.

### Proposal

Shout already owns the shell process (via `Bun.spawn`). After the shell exits, shout should kill the entire process group to reap any lingering children.

In `run.ts`, after the shell completes:

```ts
// Kill the shell's process group to clean up backgrounded children
try {
  process.kill(-proc.pid, "SIGTERM")
} catch {}
```

The `-pid` syntax sends the signal to the entire process group. Since shout spawns the shell, the shell and all its children share a process group.

This requires no syntax changes, no test file modifications, and no action from test authors. Background a process, forget about it — shout cleans up.

For defense in depth, follow up with SIGKILL after a short grace period:

```ts
try {
  process.kill(-proc.pid, "SIGTERM")
} catch {}
setTimeout(() => {
  try { process.kill(-proc.pid, "SIGKILL") } catch {}
}, 500)
```

### Migration

Remove the manual `kill` / `trap` lines from existing test files. They become no-ops but add visual noise.

## 2. Test Isolation Primitives

### Problem

Every test file that needs a server repeats the same boilerplate:

```
$ PORT=19001 ... dev-server > /dev/null 2>&1 & SVR=$!; trap "kill $SVR 2>/dev/null" EXIT; i=0; while ! curl -sf http://localhost:19001/...; do ...; done; echo "ok"
ok

$ mkdir -p .config/dev && echo '{"server":"http://localhost:19001",...}' > .config/dev/config.json
```

Each test picks a hardcoded port. Adding a new test means manually checking which ports are taken. Parallel test runs risk port collisions.

### Proposal: `# setup` directive

A new directive that includes commands from a shared file before the test's own commands:

```
# setup tests/setup.shout
```

The setup file is a normal `.shout` file. Its commands are prepended to the test's script (same shell, same working directory, same environment). This is purely textual inclusion — no new execution model.

Example `tests/setup.shout`:

```
$ dev-server > /dev/null 2>&1 &
$ mkdir -p .config/dev && echo "{\"server\":\"http://localhost:$PORT\",\"token\":\"dev-token-1\"}" > .config/dev/config.json
$ i=0; while ! curl -sf http://localhost:$PORT/api/whoami -H "Authorization: Bearer dev-token-1" > /dev/null 2>&1; do i=$((i+1)); if [ $i -gt 30 ]; then echo "server failed"; exit 1; fi; sleep 0.2; done; echo "ok"
ok
```

Then a test file becomes:

```
# Phase 1 — Linear Timeline
# setup tests/setup.shout

$ dev init myapp
initialized repo myapp in ./myapp

$ cd myapp
...
```

### Proposal: `--port-from <N>` flag

A CLI flag that auto-assigns ports to test files:

```sh
shout --port-from 19000 tests/
```

Shout sets `$PORT` in each test file's environment, incrementing from the base. When `--parallel` is used, each file gets a unique port with no coordination needed.

Implementation in the runner:

```ts
let nextPort = options.portFrom
for (const file of files) {
  const env = { ...baseEnv, PORT: String(nextPort++) }
  await runFile(file, { ...options, env })
}
```

Test files reference `$PORT` instead of hardcoded values. Combined with `# setup`, the per-file boilerplate drops to one line.

### Proposal: `# env` directive

For cases simpler than `# setup` — setting environment variables without a separate file:

```
# env PORT=19001
# env NODE_ENV=production
```

These are injected into the shell environment before any commands run. Lighter than a setup file when all you need is a few variables.