shout/CLAUDE.md

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

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
• 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/