Add -t/--filter flag for file path filtering

CLAUDE.md

@@ -12,6 +12,7 @@ Transcript-based shell integration test runner. Bun + TypeScript.
   - `--clean-env` — start with empty environment
   - `--path <path>` — prepend to `$PATH` (repeatable)
   - `--timeout <dur>` — per-command timeout (default `10s`)
+  - `-t, --filter <pattern>` — only run files whose path contains `<pattern>`
   - `-v, --verbose` — print each command as it runs
   - `--port-from <n>` — auto-assign `$PORT` starting from n (default `5400`)
   - `--parallel` — run files in parallel

README.md

@@ -113,6 +113,7 @@ Options:
   --clean-env      Start with empty environment
   --path <path>    Prepend <path> to PATH (repeatable)
   --timeout <dur>  Per-command timeout (default: "10s")
+  -t, --filter     Only run files matching <pattern> (substring match)
   -v, --verbose    Print each command as it runs
   --port-from <n>  Auto-assign $PORT starting from n (default: "5400")
   --parallel       Run files in parallel

STDIN.md

@@ -0,0 +1,57 @@
+# Stdin / Prompt Support
+
+## The challenge
+
+Currently, the shell's stdin is consumed by the script itself (`buildScript` writes all commands at once, then `proc.stdin.end()`). There's no channel left to feed stdin to individual commands.
+
+## Simplest design: heredoc injection
+
+Add a `< ` prefix for stdin lines in `.shout` files. At script-build time, transform the command into a heredoc pipe. No runtime changes needed.
+
+**Syntax:**
+
+```
+$ read -p "Name: " name && echo "Hello, $name"
+< Chris
+Name: Hello, Chris
+
+$ cat
+< line one
+< line two
+line one
+line two
+
+$ grep -c foo
+< foo bar
+< baz
+< foo baz
+2
+```
+
+**Implementation:** In `parse.ts`, collect `< ` lines as a new `stdin: string[]` field on `Command`. In `buildScript`, when `cmd.stdin` is non-empty, wrap the command:
+
+```sh
+# instead of:
+some_command
+# generate:
+some_command <<'__SHOUT_STDIN__'
+line one
+line two
+__SHOUT_STDIN__
+```
+
+This is ~30 lines of change across parse + run, and fits cleanly into the existing architecture.
+
+## What it wouldn't handle
+
+- **Interactive prompts with branching** (send input, read output, decide next input) — would require per-command execution, a much bigger refactor
+- **Timing-sensitive input** (send after a delay) — same issue
+- **Binary stdin** — heredocs are text-only
+
+## Alternative: named pipes (more complex)
+
+For each command needing stdin, create a FIFO in the temp dir and redirect from it. Shout would write to the FIFO from the Node side at the right time. This could support interactive flows but adds significant complexity to the sentinel-based output parsing — you'd need to synchronize "when to write the next stdin chunk."
+
+## Recommendation
+
+The heredoc approach covers the 90% case (testing CLIs that read input, `cat`, `read`, piped filters) with minimal change.

src/cli/index.ts

@@ -80,20 +80,26 @@ program
   .option("--timeout <dur>", "Per-command timeout", "10s")
   .option("-v, --verbose", "Print each command as it runs")
   .option("--port-from <n>", "Auto-assign $PORT starting from <n>", "5400")
+  .option("-t, --filter <pattern>", "Only run files matching <pattern> (substring match)")
   .option("--parallel", "Run files in parallel")
   .action(async (fileArgs: string[], opts) => {
     const timeoutMs = parseDuration(opts.timeout)
     const paths = fileArgs.length > 0 ? fileArgs : ["."]
-    const files = await findShoutFiles(paths)
-
-    if (files.length === 0) {
-      console.error("No .shout files found")
-      process.exit(1)
-    }
+    let files = await findShoutFiles(paths)
 
     const start = performance.now()
     const results: TestResult[] = []
     const cwd = process.cwd()
+
+    if (opts.filter) {
+      const pattern = opts.filter
+      files = files.filter(f => relative(cwd, f).includes(pattern))
+    }
+
+    if (files.length === 0) {
+      console.error(opts.filter ? `No .shout files matching "${opts.filter}"` : "No .shout files found")
+      process.exit(1)
+    }
     const portFrom = parseInt(opts.portFrom, 10)
     if (Number.isNaN(portFrom)) {
       console.error("--port-from must be an integer")

web/index.html

@@ -248,6 +248,7 @@ Options:
   --clean-env      Start with empty environment
   --path <path>    Prepend <path> to PATH (repeatable)
   --timeout <dur>  Per-command timeout (default: "10s")
+  -t, --filter     Only run files matching <pattern> (substring match)
   -v, --verbose    Print each command as it runs
   --port-from <n>  Auto-assign $PORT starting from n (default: "5400")
   --parallel       Run files in parallel