@kadj-amoah/showrunner 1.1.0 → 1.1.1

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 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.
 
+## [1.1.1] — 2026-05-24
+
+Cross-OS reliability + first-run UX patch. Addresses install-time UX findings from a Linux (CachyOS/Arch) audit of v1.1.0 *and* the post-install "what do I do now?" gaps the author hit when installing on a fresh OS. No behavioural changes to the pipeline itself.
+
+### Added
+
+- **Bare-command welcome.** Running `showrunner` with no subcommand now prints a context-aware welcome: in a project root (where `demo.yaml` exists) it suggests the next `doctor`/`run` commands; outside one, it suggests `init` and the canonical first-run sequence. Previously fell through to stock `--help`.
+- **`init` next-steps footer.** After scaffolding, `init` prints a numbered next-steps block referencing the actual files written and the API keys that the chosen provider combo requires. Skips the `.env` step entirely when the provider combo needs no keys (e.g. `agent_bridge` LLM + `custom` TTS).
+- **`run` stage-failure summary.** When the pipeline dies inside a stage, the top-level error now identifies the failed stage and prints a stage-specific remediation block (e.g. "Manifest generation failed. Hand-author scripts/manifest.json and resume: --stages record,voiceover,mux"). Introduces `PipelineStageError` so the failure path is structurally distinct from generic crashes.
+
+### Changed
+
+- **Swap `playwright` → `playwright-core`.** The published package no longer triggers a multi-minute, ~300 MB Chromium/Firefox/WebKit download on `npm install`. Users must now run `npx playwright install chromium` after install — this was always recommended but is now mandatory and is detected by `doctor`. Generated Playwright spec output also imports from `playwright-core`.
+- **`doctor`: per-OS install hints.** When `ffmpeg` or `ffprobe` is missing from PATH, the failure row now includes a platform-specific install command (`apt`/`pacman`/`dnf` on Linux, `brew` on macOS, `winget`/`choco` on Windows).
+- **`doctor`: sudo-cache detection for Playwright browsers.** When the configured browser binary isn't in the user cache, `doctor` now probes the root/admin cache (`/root/.cache/ms-playwright` on Linux, equivalent paths on macOS/Windows). If the browser is found there, the failure row tells the user explicitly: re-run `npx playwright install` *without* `sudo` so the binary lands in the user cache.
+- **`doctor`: actionable env-var hints.** When a provider's API-key env var is missing, the failure row now points to the provider's dashboard URL and suggests switching to `agent_bridge` for the LLM slot (no key required). Previously the row just said "NOT set".
+- **`doctor`: actionable target-URL hint.** When the recording target URL is unreachable, the failure row tells the user to start their dev server *or* edit `recording.target_url` in `demo.yaml`.
+- **`doctor`: "fix in this order" footer.** When two or more FAIL rows exist, doctor now prints an enumerated remediation list after the rows so the user has one ordered checklist instead of scattered hints.
+
+### Removed
+
+- **`fluent-ffmpeg` and `@types/fluent-ffmpeg` dependencies.** Showrunner has always used direct `spawn()` for ffmpeg (via the internal `runFfmpeg()` wrapper). The dependency was carried unused and emitted a deprecation warning on every install. Pure cleanup; no source changes.
+
+### Fixed
+
+- **Generated Playwright spec used `expect` not exported from the runtime package.** The codegen at `src/manifest/playwrightCodegen.ts:24` imported `expect` from `'playwright'`, which doesn't actually export `expect` (that lives in `@playwright/test`). Latent bug — `assert_visible` actions in generated specs now use the locator's native `.waitFor({ state: 'visible' })`, which is in `playwright-core`.
+
+### Docs
+
+- README: lead with `npx @kadj-amoah/showrunner` install path; demote global install. Browser-bootstrap step (`npx playwright install chromium`) is now called out as mandatory and unmissable.
+- README troubleshooting: documents the "OS not officially supported" warning on Arch/CachyOS/Fedora (safe to ignore — Playwright falls back to the Ubuntu 24.04 build) and the sudo/root-cache footgun.
+
 ## [1.1.0] — 2026-05-23
 
 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.

package/README.md

@@ -19,7 +19,51 @@ Showrunner is built to deploy on Linux but develops fine on WSL2 or macOS.
 
 ## Install
 
-Until the GitHub Packages release lands, install from source:
+Published to both npmjs.org (zero-friction install) and GitHub Packages (mirrors the GitHub Releases timeline). Pick whichever matches your workflow.
+
+Showrunner ships with `playwright-core`, which means **no browsers are downloaded during `npm install`**. You must run the browser-bootstrap step (`npx playwright install chromium`) after install — otherwise the first recording attempt will fail with a "browser binary missing" error from `doctor`.
+
+### npx (no install, recommended for first-time use)
+
+```bash
+npx @kadj-amoah/showrunner --version    # → 1.1.1
+npx playwright install chromium         # required: bootstraps the browser
+```
+
+Running `showrunner` with no arguments prints a context-aware welcome with the next command to run — from outside a project it suggests `showrunner init`; inside a project root it suggests `showrunner doctor -c demo.yaml`.
+
+### Global install (`npm i -g`)
+
+```bash
+npm install -g @kadj-amoah/showrunner
+npx playwright install chromium         # required: bootstraps the browser
+showrunner --version                    # → 1.1.1
+```
+
+> **Linux note:** if `npm i -g` needs `sudo`, **do not** run `sudo npx playwright install` afterwards — the browser will land in `/root/.cache/ms-playwright` where your user-mode `showrunner` process can't find it. Run `npx playwright install chromium` as your normal user. (`showrunner doctor` will detect and warn about this case.)
+
+### GitHub Packages
+
+Requires a one-time `~/.npmrc` setup since GitHub Packages requires auth even for public packages:
+
+```bash
+# Generate a Personal Access Token at github.com/settings/tokens
+# Scope needed: read:packages
+echo "@kadj-amoah:registry=https://npm.pkg.github.com" >> ~/.npmrc
+echo "//npm.pkg.github.com/:_authToken=YOUR_TOKEN_HERE" >> ~/.npmrc
+
+npm install -g @kadj-amoah/showrunner
+npx playwright install chromium
+```
+
+### Directly from a git tag (no registry at all)
+
+```bash
+npm install -g github:kadj-amoah/showrunner#v1.1.1
+npx playwright install chromium
+```
+
+### From source
 
 ```bash
 git clone https://github.com/kadj-amoah/showrunner.git
@@ -30,7 +74,7 @@ npm link                    # makes `showrunner` available globally
 npx playwright install chromium
 ```
 
-Verify with `showrunner --help`.
+Verify any of the above with `showrunner --help`.
 
 ## First demo in five commands
 
@@ -121,6 +165,8 @@ showrunner trace -c demo.yaml --segment <id>
 - **`vo_review_gate` halted the pipeline** — by design. Edit `scripts/vo_script.txt`, then `showrunner approve-vo -c demo.yaml`. (The init scaffold ships with this off — you have to opt in via `script.vo_review_gate: true`.)
 - **Output file is locked by a media player** — close VLC/QuickTime/your-browser-tab. Showrunner falls back to writing a timestamped sibling MP4 with a warning, but the canonical path needs the lock released.
 - **DOM preflight failed** — your dev server isn't on the URL in `demo.yaml`, or it's behind auth. Bring the server up, configure `recording.auth` for session/form/setup-script flows.
+- **Playwright warns "your OS is not officially supported"** — on Arch / CachyOS / Fedora during `npx playwright install`. Safe to ignore; Playwright falls back to the Ubuntu 24.04 build, which works fine.
+- **`browser binary missing` even though I ran `npx playwright install`** — you likely ran the install under `sudo`, so the browser is in the root cache. Re-run as your normal user: `npx playwright install chromium`. `showrunner doctor` detects this and prints the specific cache it found the browser in.
 
 ## Configuration reference