feat(cli): opt-in parallel batch rendering (#62)

[jbrecht]

Closes #62. Implements the one performance lever the baseline audit recommended.

What

Render multiple tutorial × language jobs concurrently via --render-concurrency <n> (or renderConcurrency in forge.config.ts). Default is 1 (serial) — today's behavior, byte-for-byte.

Because the record phase is mostly real-time waiting (each step holds for its narration; the CPU is near-idle), a batch — e.g. regenerating a whole tutorial set like umami's — runs near-linearly faster in parallel. No change to any rendered output.

How

• The nested for tutorial { for lang { await render } } loop is flattened to a job list run through the existing mapLimit primitive (now exported from core). mapLimit(jobs, 1, …) reproduces the old serial, ordered, fail-fast behavior exactly.
• config.renderConcurrency (zod-validated positive int) + the CLI flag; resolveRenderConcurrency clamps bad/missing values to 1, so the worst case is serial.

Opt-in by design

Concurrency > 1 requires a parallel-safe adapter — concurrent renders each run their own setup/teardown against your app, so a shared seed DB must isolate per render. There's no fork here to decide: tutorial-forge can't isolate your DB, so it offers the knob + documents the contract (new adapters.md → Parallel rendering section). Whether umami's adapter can use it is an umami-side concern. TTS cache is already concurrency-safe (atomic writes).

Tests

mapLimit unit tests (run in CI): respects the concurrency cap, preserves result order, and — the key guarantee — limit 1 is strictly sequential and fail-fast, so the default path is provably unchanged. 179 core tests pass; build/typecheck clean across all packages.

Coverage note: the CLI batch loop is thin glue over mapLimit + render() (build/type-checked); the concurrency engine itself is unit-tested. I didn't add a live multi-render test because the example app's adapter isn't guaranteed parallel-safe — exactly the contract this documents.

Semver

Adds a CLI flag + config option + the mapLimit export (all additive) → next release is a minor (0.13.0), bundling this with #50 and #49.

🤖 Generated with Claude Code

[jbrecht]

Review round complete — all three reviewers + measured verdict

Following code-reviewer (correctness), performance-engineer (delivery), and qa-engineer (coverage):

Three real fixes landed (commit c8793d5)

• mapLimit fail semantics — on error, now awaits in-flight items before rejecting (was orphaning started renders past the call); matches the documented "in-flight finish, no new scheduling".
• Lang dedupe — --lang "es,es" no longer produces two jobs writing the same work dir (corruption under concurrency). Extracted pure buildRenderJobs.
• TTS cache temp-file race — unique per-call temp paths so concurrent renders synthesizing the same key (same-language batch regen) can't clobber each other.

Coverage

CLI vitest harness added (resolveRenderConcurrency + buildRenderJobs), mapLimit stop-on-error semantics pinned, and CI flipped to pnpm -r test so the CLI package's logic is now gated (it wasn't before). 190 unit tests across core+cli.

Measured speedup (the perf-engineer's sandbox couldn't run renders; I did)

2-job batch (getting-started ×2), warm cache, this machine:

	wall-clock
serial	122.8s
--render-concurrency 2	63.1s
speedup	1.95×

Output is byte-identical (durations Δ=0ms) — concurrency changes only when jobs run. Near-linear because the record phase (~92%, idle-bound) overlaps cleanly and the ~2s encode barely contends.