# shout

Transcript-based shell integration test runner. Bun + TypeScript.

## Commands

- `bun test` — run unit tests
- `bunx tsc --noEmit` — type check
- `bun run src/cli/index.ts [files...]` — run shout CLI (`--port-from <n>` auto-assigns `$PORT`)

## Architecture

- `src/parse.ts` — parses `.shout` files into `ShoutFile` (list of `Command`)
- `src/run.ts` — executes commands via `Bun.spawn(["setsid", "/bin/sh"])`, captures output with sentinels
- `src/match.ts` — wildcard-aware output matching and diff generation
- `src/format.ts` — evaluates pass/fail, formats failures and summary
- `src/update.ts` — rewrites `.shout` files with actual output (`--update` mode)
- `src/duration.ts` — parses duration strings (`10s`, `500ms`, `1m`)
- `src/cli/index.ts` — CLI entry point via `commander`
- `src/index.ts` — barrel exports

## .shout file format

- `$ ` prefix = command to execute
- Lines between commands = expected output (stdout+stderr merged)
- `...` on its own line = multi-line wildcard (matches zero or more lines)
- `...` inline = matches any characters on that line
- `[N]` on last line of expected output = assert exit code N
- `[*]` = assert any non-zero exit code; default expects 0
- `#` after a command = comment (stripped); `#` in expected output is literal
- `@env KEY=VALUE` before first command = set environment variable
- `@setup path.shout` before first command = prepend commands (and `@env`) from another file
- Each file runs in a fresh temp dir with a single `/bin/sh` session

## Style

- Strict TypeScript, Bun runtime
- No classes — plain functions and types
- Tests in `src/*.test.ts`, example `.shout` files in `test/`