@kadj-amoah/showrunner 1.1.6 → 1.1.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +187 -186
- package/README.md +213 -191
- package/dist/cli.js +149 -19
- package/dist/cli.js.map +1 -1
- package/dist/index.d.ts +11 -0
- package/dist/index.js +8 -1
- package/dist/index.js.map +1 -1
- package/package.json +85 -85
package/CHANGELOG.md
CHANGED
|
@@ -1,186 +1,187 @@
|
|
|
1
|
-
# Changelog
|
|
2
|
-
|
|
3
|
-
All notable changes to Showrunner are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); the project tracks loose semver — minor bumps for new capability, patch for fixes.
|
|
4
|
-
|
|
5
|
-
## [1.1.
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
- `
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
### Changed
|
|
78
|
-
|
|
79
|
-
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
###
|
|
91
|
-
|
|
92
|
-
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
-
|
|
134
|
-
- `
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
- **
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
- **`
|
|
143
|
-
-
|
|
144
|
-
- **`
|
|
145
|
-
- **
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
-
|
|
150
|
-
-
|
|
151
|
-
-
|
|
152
|
-
-
|
|
153
|
-
|
|
154
|
-
###
|
|
155
|
-
|
|
156
|
-
- `
|
|
157
|
-
- `
|
|
158
|
-
-
|
|
159
|
-
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
-
|
|
165
|
-
-
|
|
166
|
-
-
|
|
167
|
-
- `
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
-
|
|
174
|
-
- `
|
|
175
|
-
-
|
|
176
|
-
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
[1.1.
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to Showrunner are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); the project tracks loose semver — minor bumps for new capability, patch for fixes.
|
|
4
|
+
|
|
5
|
+
## [1.1.8] — 2026-05-24
|
|
6
|
+
|
|
7
|
+
### Added
|
|
8
|
+
|
|
9
|
+
- Bare-command welcome detects missing `ffmpeg` and `ffprobe` alongside `chromium`. Lists per-OS install hints (apt / pacman / dnf / brew / winget).
|
|
10
|
+
- Init wizard prints the resolved cwd and gates further prompts behind an explicit confirm before scaffolding.
|
|
11
|
+
|
|
12
|
+
### Docs
|
|
13
|
+
|
|
14
|
+
- README first-demo section leads with `cd <product-root>` and explains why running `init` from a non-product directory breaks the scaffold's defaults.
|
|
15
|
+
- New "After installing: run the doctor first" section pointing at the system-only `showrunner doctor` pass.
|
|
16
|
+
|
|
17
|
+
## [1.1.7] — 2026-05-24
|
|
18
|
+
|
|
19
|
+
### Fixed
|
|
20
|
+
|
|
21
|
+
- `understand --agent` was spawning `claude` with cwd = `process.cwd()`, which is typically the scaffold directory rather than the product codebase. The agent had nothing useful to read and timed out.
|
|
22
|
+
|
|
23
|
+
### Added
|
|
24
|
+
|
|
25
|
+
- `--project-dir <path>` flag on `showrunner understand` for explicit per-invocation override.
|
|
26
|
+
- `project.codebase_root` field on the config schema, resolved relative to the config's directory.
|
|
27
|
+
- Resolution order when `--agent` is set: `--project-dir` flag, then `project.codebase_root`, then `configDir/..` (when `-c` is given), then `process.cwd()`. The resolved path is logged alongside the rule that selected it.
|
|
28
|
+
- Scaffolded `demo.yaml` writes `codebase_root: ..` by default.
|
|
29
|
+
|
|
30
|
+
### Changed
|
|
31
|
+
|
|
32
|
+
- Claude spawn passes `--allowedTools "Read,Glob,Grep"` explicitly.
|
|
33
|
+
- Agent timeout reduced from 180s to 90s.
|
|
34
|
+
|
|
35
|
+
## [1.1.6] — 2026-05-24
|
|
36
|
+
|
|
37
|
+
### Added
|
|
38
|
+
|
|
39
|
+
- `showrunner understand --agent` delegates project exploration to the local `claude` CLI. Spawns `claude -p --output-format json`; the agent uses its native Read/Glob/Grep tools to walk the project and synthesise `product_model.json` matching the existing Zod schema. Mutually exclusive with `--interactive`. Errors if `claude` is missing from PATH.
|
|
40
|
+
|
|
41
|
+
### Changed
|
|
42
|
+
|
|
43
|
+
- Error message for empty `comprehension.sources` now names all three options: add a source, `--interactive`, or `--agent`.
|
|
44
|
+
|
|
45
|
+
### Known limitations
|
|
46
|
+
|
|
47
|
+
- `type: codebase` entries in `comprehension.sources` remain non-functional in the non-`--agent` path. Directories are silently skipped and `include` / `exclude` globs are ignored. Wiring real codebase support to the document path remains future work.
|
|
48
|
+
|
|
49
|
+
## [1.1.5] — 2026-05-24
|
|
50
|
+
|
|
51
|
+
### Added
|
|
52
|
+
|
|
53
|
+
- `showrunner set-target -c <config> --url <url>` re-probes a URL and rewrites `recording.target_url` in `demo.yaml`. `--force` skips the probe.
|
|
54
|
+
- Port-scan during `init`. When the typed URL doesn't respond, probes common dev ports on `localhost` in parallel (3000, 3001, 4321, 5173, 5174, 8000, 8080) and offers responding ports as a `select`.
|
|
55
|
+
- Agent-driven dev-server discovery. When the LLM provider is `agent_bridge` and `claude` is on PATH, the wizard offers to inspect the project, propose a dev-server command + URL, spawn it detached and unref'd, then poll the URL for up to 60 seconds. Reports the spawned PID.
|
|
56
|
+
|
|
57
|
+
### Changed
|
|
58
|
+
|
|
59
|
+
- `init`'s URL section is now a cascade: direct probe → port-scan → optional agent discovery → fallback. Each step short-circuits on success.
|
|
60
|
+
- `src/setup/targetProbe.ts` is shared between `init` and `set-target`.
|
|
61
|
+
|
|
62
|
+
### Known limitations
|
|
63
|
+
|
|
64
|
+
- Spawned dev-server PIDs are not tracked across runs. Stop manually with `kill <pid>`.
|
|
65
|
+
- `set-target` rewrites `demo.yaml` via `yaml.dump`, which strips comments.
|
|
66
|
+
- Agent discovery only fires when the LLM provider is `agent_bridge`.
|
|
67
|
+
|
|
68
|
+
## [1.1.4] — 2026-05-24
|
|
69
|
+
|
|
70
|
+
### Added
|
|
71
|
+
|
|
72
|
+
- `showrunner init` is interactive by default when stdout is a TTY. The wizard detects the environment (`claude` CLI, `ffmpeg`/`ffprobe`, chromium, provider env vars), then prompts through project name, resolution, LLM provider (defaults to `agent_bridge` when `claude` is detected), inline API key paste, TTS provider, inline API key paste, target URL with a HEAD probe.
|
|
73
|
+
- A real `.env` is written with the pasted keys alongside `.env.example`.
|
|
74
|
+
- `--yes` flag skips prompts and uses defaults or passed flags. Automatically forced when stdout is not a TTY.
|
|
75
|
+
- `@clack/prompts` dependency for the wizard UI.
|
|
76
|
+
|
|
77
|
+
### Changed
|
|
78
|
+
|
|
79
|
+
- `init` next-steps footer adapts to wizard state. Skips the "edit `.env`" step when keys were pasted; lists only the still-missing keys otherwise.
|
|
80
|
+
|
|
81
|
+
## [1.1.3] — 2026-05-24
|
|
82
|
+
|
|
83
|
+
### Changed
|
|
84
|
+
|
|
85
|
+
- Bare-command welcome rewritten. Each state (chromium missing / no project / in project) now shows one next command and one line of context, instead of a 15-line block that duplicated `init`'s footer.
|
|
86
|
+
- `init` next-steps footer split conflated steps. Each required env var is listed individually with the provider's dashboard URL; the `agent_bridge` alternative is a single parenthetical at the end.
|
|
87
|
+
|
|
88
|
+
## [1.1.2] — 2026-05-24
|
|
89
|
+
|
|
90
|
+
### Fixed
|
|
91
|
+
|
|
92
|
+
- `showrunner --version` crashed on fresh global install with `ERR_MODULE_NOT_FOUND` for `@babel/parser`. The babel runtime dependencies (`@babel/parser`, `@babel/traverse`, `@babel/types`) used by the `instrument` stage were in `devDependencies` and therefore absent from the published tarball. Moved to `dependencies`. `@types/babel__traverse` stays in `devDependencies` (type-only).
|
|
93
|
+
|
|
94
|
+
### Added
|
|
95
|
+
|
|
96
|
+
- `showrunner install-browser` subcommand. Wraps the bundled `playwright-core` CLI directly, sidestepping the "install your dependencies first" warning that bare `npx playwright install` emits when invoked outside a Node project.
|
|
97
|
+
- Welcome detects missing chromium and surfaces an `install-browser` hint.
|
|
98
|
+
|
|
99
|
+
## [1.1.1] — 2026-05-24
|
|
100
|
+
|
|
101
|
+
### Changed
|
|
102
|
+
|
|
103
|
+
- Replace `playwright` with `playwright-core`. Eliminates the ~300 MB browser auto-download on `npm install`. `npx playwright install chromium` is now a required post-install step (enforced by `doctor`).
|
|
104
|
+
- `doctor` failure rows include per-OS install hints for `ffmpeg` and `ffprobe` (apt / pacman / dnf on Linux, brew on macOS, winget / choco on Windows).
|
|
105
|
+
- `doctor` probes the root / admin Playwright cache and warns when a browser is present there but missing from the user cache (the typical aftermath of `sudo npx playwright install`).
|
|
106
|
+
|
|
107
|
+
### Removed
|
|
108
|
+
|
|
109
|
+
- `fluent-ffmpeg` and `@types/fluent-ffmpeg`. The package was listed but never imported; ffmpeg invocations have always gone through `child_process.spawn` via the internal `runFfmpeg()` wrapper.
|
|
110
|
+
|
|
111
|
+
### Fixed
|
|
112
|
+
|
|
113
|
+
- Generated Playwright spec at `src/manifest/playwrightCodegen.ts` imported `expect` from `'playwright'`, which doesn't export it. The `assert_visible` action now emits `locator.waitFor({ state: 'visible' })`.
|
|
114
|
+
|
|
115
|
+
### Docs
|
|
116
|
+
|
|
117
|
+
- README leads with `npx @kadj-amoah/showrunner`. Browser bootstrap (`npx playwright install chromium`) is called out as required.
|
|
118
|
+
- Troubleshooting note added for Arch / CachyOS / Fedora users who see Playwright's "OS not officially supported" warning during browser install.
|
|
119
|
+
|
|
120
|
+
## [1.1.0] — 2026-05-23
|
|
121
|
+
|
|
122
|
+
First tagged release. Versioned `1.1.0` rather than `0.1.0` because the project has been tracked as "v1.1 — reliability hardening + provider-agnostic refactor" throughout development; this is the first cut where the pipeline works end-to-end against real Next.js targets and the LLM + TTS layers are swappable. No `1.0.0` was ever published.
|
|
123
|
+
|
|
124
|
+
### Added
|
|
125
|
+
|
|
126
|
+
- **Provider-agnostic LLM layer** (`llm.default` + per-stage `llm.overrides`). Four providers:
|
|
127
|
+
- `anthropic` — Claude via the official SDK with structured outputs.
|
|
128
|
+
- `openai` — `gpt-4o`-style models via `response_format: json_schema` with `json_object` fallback.
|
|
129
|
+
- `agent_bridge` — spawn a headless CLI agent like `claude -p --output-format json`; **no API key on file required**. Supports `spawn` and `file_poll` modes.
|
|
130
|
+
- `custom` — dynamic-import an operator-supplied module conforming to the `LLMProvider` interface.
|
|
131
|
+
- **Provider-agnostic TTS layer** (`voiceover.provider`). Three providers:
|
|
132
|
+
- `elevenlabs` — the only one that returns per-character alignment.
|
|
133
|
+
- `openai` — `tts-1-hd` via the audio API.
|
|
134
|
+
- `custom` — dynamic-import for in-house TTS pipelines.
|
|
135
|
+
- **`alignment_strategy: required | best_effort`** — when a TTS provider doesn't return alignment, switch automatically to per-segment synthesis (one TTS call per segment) so audio doesn't get sliced across mid-word boundaries.
|
|
136
|
+
- **`showrunner doctor`** — preflight checks before any run. Validates config syntax, provider env vars, ffmpeg + ffprobe on PATH, Playwright chromium binary, target URL reachability, free disk on every output dir, free memory + computed ffmpeg thread cap, and lifecycle script executability. Wired into `run` implicitly (escape with `--skip-doctor`).
|
|
137
|
+
- **`showrunner record-actions`** with scroll capture. Drives a headed browser; captures click / input / change / keydown / submit / **scroll** events; coalesces them into a clean action stream. Scroll capture is 250 ms debounced with direction coalescing.
|
|
138
|
+
- **DOM preflight in the `script` stage** — scrapes the live target's actionable selector inventory (≈60–80 entries on a typical marketing site) before asking the LLM for a manifest. The LLM is constrained to inventory selectors only, with a one-shot remediation retry if it strays.
|
|
139
|
+
- **Resource preflight** in `record` and `mux` stages — checks free disk against estimated artifact sizes, computes an ffmpeg `-threads` cap from free RAM × resolution × quality preset (`SHOWRUNNER_FFMPEG_THREADS` env override available).
|
|
140
|
+
- **Structured ffmpeg errors** — categorized as `oom | no_space | codec_missing | permission | unknown`, with per-category remediation hints.
|
|
141
|
+
- **`--resolution` flag** on both `init` and `run`. Presets: `low` (854×480), `standard` (720p, the default), `high` (1080p), `extreme` (4K). On `run` it overrides both `recording.viewport` and `output.resolution` in one step so they stay matched and mux doesn't upscale.
|
|
142
|
+
- **`init` flags**: `--llm-provider`, `--tts-provider`, `--resolution`. Scaffolds a `demo.yaml` with the right provider blocks, an `.env.example` listing only the env vars that combination actually needs (deduplicated when LLM + TTS both use OpenAI), and a real `docs/PRD.md` stub with section guides.
|
|
143
|
+
- **Legacy config auto-migration** — pre-v0.1 `demo.yaml` files with flat `voiceover.{voice_id, model, ...}` fields and no `llm` block are normalized at load time. Existing configs keep working with zero edits.
|
|
144
|
+
- **`validate --strict`** — exit nonzero on missing provider env vars (otherwise warns).
|
|
145
|
+
- **Captions** — SRT + VTT emitted alongside the final MP4 when `output.captions.enabled` is set. Whole-segment cues are used as a fallback when per-character alignment isn't available.
|
|
146
|
+
|
|
147
|
+
### Changed
|
|
148
|
+
|
|
149
|
+
- `engines.node` bumped to `>=20.6` (needed for `process.loadEnvFile`).
|
|
150
|
+
- `init` defaults: `script.vo_review_gate: false` (was true), `recording.viewport: 1280×720` (was 1920×1080), `output.resolution: 1280x720`. Each is opt-in to the larger/stricter value via a one-line edit.
|
|
151
|
+
- `tsup` configured with `skipNodeModulesBundle: true` and `target: 'node20'`. Built `dist/cli.js` dropped from 1.75 MB to 247 KB and no longer crashes with `Dynamic require of "tty" is not supported` — `npm link` and `npm i -g` are viable now.
|
|
152
|
+
- README rewritten for v0.1 — install path (with `npm link`), full prereqs (Node ≥ 20.6, ffmpeg, chromium), provider-choice tables, pipeline-per-stage table, daily-commands cookbook, troubleshooting section.
|
|
153
|
+
|
|
154
|
+
### Fixed
|
|
155
|
+
|
|
156
|
+
- `understand --interactive` no longer silently exits after the second question on piped stdin. Replaced `readline/promises.question()` with a queued `'line'`-event reader that handles both TTY and pipe semantics.
|
|
157
|
+
- `understand --output <path>` now correctly takes precedence over `project.product_model` in the config (was silently overridden).
|
|
158
|
+
- Script-stage prompt now bans Tailwind arbitrary-value class names (`.max-w-[1280px]`) which aren't legal CSS and crashed Playwright with a `SyntaxError`. A post-validator catches violations and retries once with a remediation prompt before accepting the manifest.
|
|
159
|
+
- `looksUnstable()` heuristic now catches Next.js compiled-CSS classes like `__variable_3eb911` (leading underscores were previously slipping past).
|
|
160
|
+
- `mux` output write now falls back to a timestamped sibling MP4 when the canonical path is locked by a media player, with a warning, instead of failing the run.
|
|
161
|
+
|
|
162
|
+
### Known limitations (Tier 3 — coded but not exercised end-to-end)
|
|
163
|
+
|
|
164
|
+
- OpenAI LLM + OpenAI TTS provider paths are wired but were not run with a real API key in v0.1 validation. The agent_bridge + ElevenLabs combination is the validated default.
|
|
165
|
+
- `agent_bridge` file_poll mode is coded but only `spawn` mode was exercised.
|
|
166
|
+
- Custom provider modules (LLM + TTS) — dynamic-import loader is wired but no reference implementation has been swapped in.
|
|
167
|
+
- `instrument`, `capture-auth`, `trace`, `preview`, `rerun-segment`, `print-vo`, `approve-vo` commands are mostly thin wrappers but were not stress-tested in v0.1.
|
|
168
|
+
- Background music mix and title-card logo / custom-font rendering are coded but were not exercised.
|
|
169
|
+
- 1920×1080 mux remains RAM-sensitive on tight boxes; the thread-cap heuristic mitigates but the safe default is `--resolution standard`.
|
|
170
|
+
|
|
171
|
+
### Validation artifact
|
|
172
|
+
|
|
173
|
+
A real end-to-end run against the Credstone Atlas marketing site produced `output/ct-website-atlas_demo.mp4` (4.3 MB, H.264 + AAC, 1280×720, 48.2 s, with SRT + VTT) using:
|
|
174
|
+
- `agent_bridge` LLM (via local `claude` CLI, no Anthropic key on file)
|
|
175
|
+
- ElevenLabs TTS with `alignment_strategy: required`
|
|
176
|
+
- DOM preflight + selector validator producing inventory-only manifest selectors
|
|
177
|
+
- Full mux preflight + thread cap on a 5.9 GB RAM machine with 1.1 GB free at run time
|
|
178
|
+
|
|
179
|
+
[1.1.0]: https://github.com/kadj-amoah/showrunner/releases/tag/v1.1.0
|
|
180
|
+
[1.1.1]: https://github.com/kadj-amoah/showrunner/releases/tag/v1.1.1
|
|
181
|
+
[1.1.2]: https://github.com/kadj-amoah/showrunner/releases/tag/v1.1.2
|
|
182
|
+
[1.1.3]: https://github.com/kadj-amoah/showrunner/releases/tag/v1.1.3
|
|
183
|
+
[1.1.4]: https://github.com/kadj-amoah/showrunner/releases/tag/v1.1.4
|
|
184
|
+
[1.1.5]: https://github.com/kadj-amoah/showrunner/releases/tag/v1.1.5
|
|
185
|
+
[1.1.6]: https://github.com/kadj-amoah/showrunner/releases/tag/v1.1.6
|
|
186
|
+
[1.1.7]: https://github.com/kadj-amoah/showrunner/releases/tag/v1.1.7
|
|
187
|
+
[1.1.8]: https://github.com/kadj-amoah/showrunner/releases/tag/v1.1.8
|