@kadj-amoah/showrunner 1.1.1 → 1.1.3

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 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.3] — 2026-05-24
+
+UX polish on the post-install discovery path, prompted by author feedback during the CachyOS install smoke-test of v1.1.2 ("the entire welcome wagon needs to be worked on"). No functional change — pure copy + structure.
+
+### Changed
+
+- **Bare-command welcome rewritten to one-thing-at-a-time.** Each state (chromium missing, no project here, project here) now shows a single next command and a one-line description, instead of a 15-line wall that duplicated `init`'s footer and crammed multiple ideas per line. The outside-project branch now just points at `showrunner init` and defers all sequencing to `init`'s own output.
+- **`init` next-steps footer tightened.** The previous `cp .env.example .env       # then paste in: KEY_A, KEY_B` line conflated three things (file op, key list, no-keys alternative). Now split: step 2 is the `cp`, step 3 lists each required env var on its own line alongside the dashboard URL it's issued from, with the `agent_bridge` alternative as a single parenthetical at the end. Each step is exactly one observable action.
+
+## [1.1.2] — 2026-05-24
+
+Hot-fix for a regression discovered while smoke-testing the v1.1.1 install on CachyOS.
+
+### Fixed
+
+- **`showrunner --version` crashed on fresh global install with `ERR_MODULE_NOT_FOUND` for `@babel/parser`.** The babel runtime deps (`@babel/parser`, `@babel/traverse`, `@babel/types`) used by the `instrument` stage were in `devDependencies`, so they weren't installed alongside the published package. The CLI bundle loads all subcommand modules eagerly, so the failure surfaced before any subcommand could run. Moved the three packages to `dependencies`. (`@types/babel__traverse` stays in `devDependencies` — type-only.) This bug was almost certainly latent in v1.1.0 as well; nobody hit it because the v1.1.0 install hung on the silent playwright postinstall (the issue v1.1.1 fixed).
+
+### Added
+
+- **`showrunner install-browser`** subcommand — wraps the Playwright browser install by shelling out to the bundled `playwright-core`'s CLI directly, which sidesteps the misleading "install your project's dependencies first" warning that plain `npx playwright install` emits when invoked outside a Node project.
+- **Bare-command welcome now detects missing chromium** and prepends a clear "First-time setup: `showrunner install-browser`" hint when the browser cache doesn't have it. Removes the implicit assumption that users will know they need to bootstrap a browser after install.
+
 ## [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.

package/dist/cli.js

@@ -5660,23 +5660,35 @@ function printNextSteps(projectName, resolved) {
   let step = 1;
   lines.push(`  ${step++}. cd ${projectName}`);
   if (envVars.length > 0) {
-    const keysList = envVars.join(", ");
-    lines.push(`  ${step++}. cp .env.example .env       # then paste in: ${keysList}`);
+    lines.push(`  ${step++}. cp .env.example .env`);
+    lines.push(`  ${step++}. Edit .env to fill in:`);
+    for (const v of envVars) {
+      const dash = PROVIDER_DASHBOARDS[v];
+      lines.push(`       ${v}${dash ? `  (get it at ${dash})` : ""}`);
+    }
+    lines.push(
+      `     (No keys? Switch llm.default.provider to \`agent_bridge\` in demo.yaml \u2014 uses your local Claude CLI instead.)`
+    );
   } else {
     lines.push(
-      `  ${step++}. (no .env needed \u2014 agent_bridge LLM + ${resolved.tts} TTS don't require API keys)`
+      `  ${step++}. (.env not needed \u2014 agent_bridge LLM + ${resolved.tts} TTS don't use API keys.)`
     );
   }
-  lines.push(`  ${step++}. $EDITOR docs/PRD.md          # replace the stub with your product brief`);
+  lines.push(`  ${step++}. Edit docs/PRD.md (the stub explains what each section is for).`);
   lines.push(`  ${step++}. showrunner doctor -c demo.yaml`);
-  lines.push(`  ${step++}. showrunner run -c demo.yaml  # \u2192 output/demo_final.mp4`);
+  lines.push(`  ${step++}. showrunner run -c demo.yaml   # \u2192 output/demo_final.mp4`);
   lines.push("");
   lines.push(
-    `Optional: \`showrunner understand -c demo.yaml --interactive\` if you'd rather answer five questions than write the PRD upfront.`
+    `Don't want to write a PRD? Run \`showrunner understand -c demo.yaml --interactive\` instead \u2014 it asks 5 questions and builds the product model from your answers.`
   );
   lines.push("");
   process.stdout.write(lines.join("\n"));
 }
+var PROVIDER_DASHBOARDS = {
+  ANTHROPIC_API_KEY: "https://console.anthropic.com/settings/keys",
+  OPENAI_API_KEY: "https://platform.openai.com/api-keys",
+  ELEVENLABS_API_KEY: "https://elevenlabs.io/app/settings/api-keys"
+};
 function requiredEnvVars(resolved) {
   const vars = /* @__PURE__ */ new Set();
   if (resolved.llm === "anthropic") vars.add("ANTHROPIC_API_KEY");
@@ -6114,6 +6126,50 @@ and \`at_word\` actions degrade to \`at\`).
 `;
 }
 
+// src/commands/installBrowser.ts
+import { spawn as spawn4 } from "child_process";
+import { access as access3 } from "fs/promises";
+import { fileURLToPath } from "url";
+import { dirname as dirname11, join as join11 } from "path";
+var DEFAULT_BROWSER = "chromium";
+async function installBrowserCommand(opts) {
+  const browser = opts.browser ?? DEFAULT_BROWSER;
+  const cli = await resolvePlaywrightCoreCli();
+  logger.info(`installing Playwright ${browser} (via bundled playwright-core, no project required)`);
+  const child = spawn4(process.execPath, [cli, "install", browser], {
+    stdio: "inherit",
+    env: process.env
+  });
+  const code = await new Promise((resolve27, reject) => {
+    child.on("error", reject);
+    child.on("close", (c) => resolve27(c ?? 0));
+  });
+  if (code !== 0) {
+    logger.error(`playwright install exited with code ${code}`);
+    process.exit(code);
+  }
+  logger.info(`${browser} installed. Try \`showrunner doctor -c demo.yaml\` next.`);
+}
+async function resolvePlaywrightCoreCli() {
+  const here = fileURLToPath(import.meta.url);
+  let dir = dirname11(here);
+  const root = dir.split(/[\\/]/)[0] + "/";
+  while (dir && dir !== root) {
+    const candidate = join11(dir, "node_modules", "playwright-core", "cli.js");
+    try {
+      await access3(candidate);
+      return candidate;
+    } catch {
+    }
+    const parent = dirname11(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new Error(
+    "Could not locate playwright-core CLI inside Showrunner's node_modules. This is a packaging bug \u2014 please file an issue."
+  );
+}
+
 // src/commands/validate.ts
 import { stat as stat10 } from "fs/promises";
 import { isAbsolute as isAbsolute9, resolve as resolve16 } from "path";
@@ -6266,7 +6322,7 @@ async function pathExists2(p) {
 
 // src/commands/rerunSegment.ts
 import { mkdir as mkdir12, rename as rename3, writeFile as writeFile13 } from "fs/promises";
-import { join as join11, resolve as resolve19 } from "path";
+import { join as join12, resolve as resolve19 } from "path";
 import { chromium as chromium4, firefox as firefox4, webkit as webkit4 } from "playwright-core";
 var RERUN_BUFFER_MS = 500;
 var browserMap4 = { chromium: chromium4, firefox: firefox4, webkit: webkit4 };
@@ -6385,7 +6441,7 @@ async function rerunSegmentCommand(opts) {
     await page.waitForTimeout(config.recording.segment_buffer_ms);
     const traceDir = resolve19(configDir, config.recording.trace_dir);
     await mkdir12(traceDir, { recursive: true });
-    await ctx.tracing.stopChunk({ path: join11(traceDir, `${segment.id}.zip`) });
+    await ctx.tracing.stopChunk({ path: join12(traceDir, `${segment.id}.zip`) });
     const videoHandle = page.video();
     await ctx.close();
     if (!videoHandle) {
@@ -6393,9 +6449,9 @@ async function rerunSegmentCommand(opts) {
       process.exit(1);
     }
     const original = await videoHandle.path();
-    const dest = join11(videoDir, `${segment.id}.webm`);
+    const dest = join12(videoDir, `${segment.id}.webm`);
     await rename3(original, dest);
-    const metadataPath = join11(videoDir, `${segment.id}.rerun.json`);
+    const metadataPath = join12(videoDir, `${segment.id}.rerun.json`);
     await writeFile13(
       metadataPath,
       JSON.stringify(
@@ -6424,7 +6480,7 @@ async function rerunSegmentCommand(opts) {
 
 // src/commands/captureAuth.ts
 import { mkdir as mkdir14 } from "fs/promises";
-import { dirname as dirname11, isAbsolute as isAbsolute10, resolve as resolve21 } from "path";
+import { dirname as dirname12, isAbsolute as isAbsolute10, resolve as resolve21 } from "path";
 import { createInterface } from "readline/promises";
 
 // src/recording/headed.ts
@@ -6511,7 +6567,7 @@ async function captureAuthCommand(opts) {
   }
   const cookiesRel = opts.outputCookies ?? "./auth/session.json";
   const cookiesPath = isAbsolute10(cookiesRel) ? cookiesRel : resolve21(loaded.configDir, cookiesRel);
-  await mkdir14(dirname11(cookiesPath), { recursive: true });
+  await mkdir14(dirname12(cookiesPath), { recursive: true });
   logger.info("Launching headed browser for auth capture", {
     target: loaded.config.recording.target_url,
     output: cookiesPath
@@ -6552,7 +6608,7 @@ Then re-run \`showrunner run --config <demo.yaml>\`.
 
 // src/commands/trace.ts
 import { readdir as readdir2, stat as stat12 } from "fs/promises";
-import { isAbsolute as isAbsolute11, join as join12, resolve as resolve22 } from "path";
+import { isAbsolute as isAbsolute11, join as join13, resolve as resolve22 } from "path";
 async function traceCommand(opts) {
   let loaded;
   try {
@@ -6566,7 +6622,7 @@ async function traceCommand(opts) {
   }
   const traceDir = resolve22(loaded.configDir, loaded.config.recording.trace_dir);
   const videoDir = resolve22(loaded.configDir, loaded.config.recording.output_dir);
-  const slicePlanPath = join12(videoDir, "slice_plan.json");
+  const slicePlanPath = join13(videoDir, "slice_plan.json");
   if (opts.all) {
     let plan;
     try {
@@ -6577,14 +6633,14 @@ async function traceCommand(opts) {
       process.exit(1);
     }
     for (const seg of plan.segments) {
-      const tracePath = seg.trace_path && isAbsolute11(seg.trace_path) ? seg.trace_path : seg.trace_path ? resolve22(loaded.configDir, seg.trace_path) : join12(traceDir, `${seg.id}.zip`);
+      const tracePath = seg.trace_path && isAbsolute11(seg.trace_path) ? seg.trace_path : seg.trace_path ? resolve22(loaded.configDir, seg.trace_path) : join13(traceDir, `${seg.id}.zip`);
       logger.info(`Opening trace for ${seg.id}`, { path: tracePath });
       await openTrace(tracePath);
     }
     return;
   }
   if (opts.segment) {
-    const tracePath = join12(traceDir, `${opts.segment}.zip`);
+    const tracePath = join13(traceDir, `${opts.segment}.zip`);
     if (!await fileExists8(tracePath)) {
       logger.error(`No trace found at ${tracePath}`);
       process.exit(1);
@@ -6689,7 +6745,7 @@ async function fileExists9(path) {
 
 // src/commands/understand.ts
 import { mkdir as mkdir15, readFile as readFile10, writeFile as writeFile14 } from "fs/promises";
-import { dirname as dirname12, isAbsolute as isAbsolute12, resolve as resolve24 } from "path";
+import { dirname as dirname13, isAbsolute as isAbsolute12, resolve as resolve24 } from "path";
 
 // src/productModel/prompts.ts
 var PRODUCT_MODEL_SYSTEM_PROMPT = `You build product_model.json for Showrunner, an automated product demo recorder.
@@ -6894,7 +6950,7 @@ async function understandCommand(opts) {
     }
   }
   const outputPath = isAbsolute12(outputRel) ? outputRel : resolve24(configDir, outputRel);
-  await mkdir15(dirname12(outputPath), { recursive: true });
+  await mkdir15(dirname13(outputPath), { recursive: true });
   let productModel;
   const provider = resolveDefaultLLMProvider({ configDir, llm: llmConfig });
   try {
@@ -6942,7 +6998,7 @@ async function understandCommand(opts) {
 
 // src/commands/instrument.ts
 import { mkdir as mkdir16, readdir as readdir3, writeFile as writeFile15 } from "fs/promises";
-import { dirname as dirname13, isAbsolute as isAbsolute13, join as join13, resolve as resolve25, relative as relative2 } from "path";
+import { dirname as dirname14, isAbsolute as isAbsolute13, join as join14, resolve as resolve25, relative as relative2 } from "path";
 
 // src/instrument/scan.ts
 import { readFile as readFile11 } from "fs/promises";
@@ -7167,7 +7223,7 @@ async function instrumentCommand(opts) {
   async function walk(root, accept) {
     const entries = await readdir3(root, { withFileTypes: true });
     for (const entry of entries) {
-      const abs = join13(root, entry.name);
+      const abs = join14(root, entry.name);
       if (entry.isDirectory()) {
         if (IGNORED_DIRS.has(entry.name)) continue;
         await walk(abs, accept);
@@ -7224,7 +7280,7 @@ async function instrumentCommand(opts) {
     logger.warn(`Skipped suggestion at ${s.file}:${s.line} \u2014 ${s.reason}`);
   }
   const outputPath = isAbsolute13(opts.output) ? opts.output : resolve25(loaded.configDir, opts.output);
-  await mkdir16(dirname13(outputPath), { recursive: true });
+  await mkdir16(dirname14(outputPath), { recursive: true });
   await writeFile15(outputPath, patch, "utf8");
   logger.info("Wrote instrumentation patch", { path: outputPath, suggestions: suggestions.length });
   process.stdout.write(`
@@ -7559,7 +7615,7 @@ async function fileExists10(path) {
 
 // src/cli.ts
 var program = new Command();
-program.name("showrunner").description("Automated product demo recording & production tool").version("1.1.1").option("--json", "emit structured JSON logs to stdout").option("--log-level <level>", "log level (debug|info|warn|error)").hook("preAction", (thisCmd) => {
+program.name("showrunner").description("Automated product demo recording & production tool").version("1.1.3").option("--json", "emit structured JSON logs to stdout").option("--log-level <level>", "log level (debug|info|warn|error)").hook("preAction", (thisCmd) => {
   const opts = thisCmd.opts();
   if (opts.json) logger.setJson(true);
   if (opts.logLevel) logger.setLevel(opts.logLevel);
@@ -7592,6 +7648,7 @@ program.command("init").description("Scaffold a new Showrunner project").option(
   "scaffold resolution: low (854x480) | standard (720p) | high (1080p) | extreme (4K)",
   "standard"
 ).action(initCommand);
+program.command("install-browser").description("Install the Playwright browser binary (chromium by default) \u2014 wraps playwright-core install").option("--browser <name>", "browser to install: chromium | firefox | webkit", "chromium").action(installBrowserCommand);
 program.command("doctor").description("Run preflight checks on the current config + environment").requiredOption("-c, --config <path>", "path to demo.yaml").option("--json", "emit results as JSON instead of human-readable rows").action(doctorCommand);
 program.command("validate").description("Validate a demo.yaml config file").requiredOption("-c, --config <path>", "path to demo.yaml").option("--strict", "exit nonzero on any warning (e.g. missing provider env var)").action(validateCommand);
 program.command("understand").description("Build product_model.json from documents or interactive Q&A").option("-c, --config <path>", "path to demo.yaml").option("--interactive", "use interactive Q&A mode").option("--output <path>", "output path for product_model.json").action(understandCommand);
@@ -7609,41 +7666,51 @@ program.parseAsync(process.argv).catch((err) => {
   process.exit(1);
 });
 async function printWelcome() {
-  const { access: access3 } = await import("fs/promises");
+  const { access: access4 } = await import("fs/promises");
   const { resolve: resolve27 } = await import("path");
   const demoYaml = resolve27(process.cwd(), "demo.yaml");
   let inProject = false;
   try {
-    await access3(demoYaml);
+    await access4(demoYaml);
     inProject = true;
   } catch {
   }
-  const lines = ["", `Showrunner v1.1.1 \u2014 automated product-demo recording & production`, ""];
-  if (inProject) {
-    lines.push(`Detected demo.yaml in this directory. Likely next:`);
+  const browserMissing = await isChromiumMissing();
+  const lines = ["", `Showrunner v1.1.3`, ""];
+  if (browserMissing) {
+    lines.push(`Showrunner records using Chromium. You haven't installed it yet.`);
     lines.push(``);
-    lines.push(`  showrunner doctor -c demo.yaml      # preflight checks`);
-    lines.push(`  showrunner run -c demo.yaml         # run the full pipeline`);
+    lines.push(`  showrunner install-browser`);
     lines.push(``);
-    lines.push(`Other commands: \`showrunner --help\``);
-  } else {
-    lines.push(`No demo.yaml here. To scaffold a new project:`);
+    lines.push(`(~150 MB, one-off. Re-run \`showrunner\` after it finishes for the next step.)`);
+  } else if (inProject) {
+    lines.push(`This is a Showrunner project (found demo.yaml).`);
     lines.push(``);
-    lines.push(`  showrunner init --name my-demo --url http://localhost:3000`);
+    lines.push(`  showrunner doctor -c demo.yaml     # check everything is wired correctly`);
+    lines.push(`  showrunner run -c demo.yaml        # then run the full pipeline`);
     lines.push(``);
-    lines.push(`Then inside the new directory:`);
+    lines.push(`Full command list: \`showrunner --help\``);
+  } else {
+    lines.push(`No Showrunner project in this directory. To create one:`);
     lines.push(``);
-    lines.push(`  cd my-demo`);
-    lines.push(`  cp .env.example .env                 # paste provider keys, or use agent_bridge (no keys)`);
-    lines.push(`  $EDITOR docs/PRD.md                  # write your product brief`);
-    lines.push(`  showrunner doctor -c demo.yaml       # preflight`);
-    lines.push(`  showrunner run -c demo.yaml          # full pipeline \u2192 output/demo_final.mp4`);
+    lines.push(`  showrunner init`);
     lines.push(``);
-    lines.push(`See all commands: \`showrunner --help\``);
+    lines.push(`\`init\` scaffolds the project and prints the next 4 commands tailored to your provider choice.`);
   }
   lines.push("");
   process.stdout.write(lines.join("\n"));
 }
+async function isChromiumMissing() {
+  try {
+    const { chromium: chromium6 } = await import("playwright-core");
+    const exec = chromium6.executablePath();
+    const { stat: stat15 } = await import("fs/promises");
+    await stat15(exec);
+    return false;
+  } catch {
+    return true;
+  }
+}
 function parseStages(value) {
   const requested = value.split(",").map((s) => s.trim());
   const invalid = requested.filter((s) => !stageChoices.includes(s));