@kadj-amoah/showrunner 1.1.6 → 1.1.7

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 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.7] — 2026-05-24
+
+Hot-fix the most embarrassing thing about v1.1.6: `showrunner understand --agent` was pointing the agent at the wrong directory.
+
+### Fixed
+
+- **`understand --agent` now anchors the agent at the actual product codebase, not the Showrunner scaffold.** v1.1.6 spawned `claude` with `cwd = process.cwd()`. The canonical workflow has the user `cd` into their Showrunner scaffold (`cd my-demo`) before running commands, which meant the agent explored a directory containing only template files (the scaffold's stub README, PRD stub, `scripts/`, `segments/`, `output/`) — nothing about the actual product. The agent spent 180s exploring noise and timed out.
+- **Resolution order in v1.1.7** when `--agent` is set:
+  1. `--project-dir <path>` flag (explicit per-invocation override)
+  2. `project.codebase_root` field in `demo.yaml`, resolved relative to the config's directory
+  3. `configDir/..` (the canonical scaffold-inside-product layout) — used when `-c demo.yaml` is given but no explicit anchor exists
+  4. `process.cwd()` (only when no `-c` was given)
+- Resolved path is now logged prominently before the agent spawns: `Generating product_model via local claude agent { projectDir: ..., source: ... }`. The `source` field tells you which rule resolved the path.
+
+### Added
+
+- **`--project-dir <path>`** flag on `showrunner understand`. Override the agent's exploration root for a single invocation.
+- **`project.codebase_root`** field in the config schema. Persistent override per project.
+- **`init`'s generated `demo.yaml` now writes `codebase_root: ..` by default**, so newly scaffolded projects get the right behaviour without the user having to know about the field.
+
+### Changed
+
+- **Claude spawn now passes `--allowedTools "Read,Glob,Grep"`** to be explicit about which tools the agent may use without prompting. v1.1.6 relied on claude's `default` permission mode, which is supposed to auto-approve reads but leaves room for ambiguity around Glob/Grep/Bash. Being explicit short-circuits any related stalling.
+- **Agent spawn timeout dropped from 180s to 90s.** Failure should fail fast; three-minute waits on retest are painful.
+
 ## [1.1.6] — 2026-05-24
 
 Closes a long-latent gap: `showrunner understand` now has an `--agent` mode that delegates codebase exploration to the local `claude` CLI rather than relying on `comprehension.sources` to be set up correctly.

package/dist/cli.js

@@ -76,7 +76,14 @@ import "zod";
 import { z } from "zod";
 var projectSchema = z.object({
   name: z.string().min(1),
-  product_model: z.string().optional()
+  product_model: z.string().optional(),
+  /**
+   * Path to the product's codebase, resolved relative to demo.yaml's directory.
+   * Used by `understand --agent` to anchor the agent's exploration.
+   * Defaults to `..` because the canonical scaffold layout places the
+   * Showrunner project inside or beside the product directory.
+   */
+  codebase_root: z.string().optional()
 });
 var comprehensionSourceSchema = z.object({
   type: z.enum(["prd", "readme", "codebase", "openapi", "changelog", "custom"]),
@@ -6423,6 +6430,11 @@ function demoYamlTemplate(opts) {
 project:
   name: ${opts.name}
   # product_model: ./product_model.json   # uncomment to skip comprehension
+  # Where the product codebase lives, relative to this demo.yaml. Used by
+  # \`showrunner understand --agent\` to anchor the agent's exploration.
+  # Default \`..\` matches the canonical layout where the Showrunner scaffold
+  # sits inside (or beside) the product directory.
+  codebase_root: ..
 
 comprehension:
   mode: documents
@@ -7623,8 +7635,17 @@ async function generateProductModelViaAgent(opts) {
   const provider = new AgentBridgeLLMProvider({
     mode: "spawn",
     command: opts.command ?? "claude",
-    args: opts.args ?? ["-p", "--output-format", "json"],
-    timeoutMs: opts.timeoutMs ?? 18e4,
+    args: opts.args ?? [
+      "-p",
+      "--output-format",
+      "json",
+      // Explicitly allow read-only filesystem tools so claude doesn't stall on
+      // permission ambiguity in headless mode. Comma-separated per claude CLI syntax.
+      "--allowedTools",
+      "Read,Glob,Grep"
+    ],
+    // 90s cap — was 180s in v1.1.6, dropped here because failures should fail fast.
+    timeoutMs: opts.timeoutMs ?? 9e4,
     cwd: opts.projectDir
   });
   const userPrompt = [
@@ -7748,6 +7769,7 @@ async function understandCommand(opts) {
   let outputRel = opts.output ?? "./product_model.json";
   let sources = [];
   let llmConfig;
+  let loadedCodebaseRoot;
   if (opts.config) {
     let loaded;
     try {
@@ -7765,6 +7787,7 @@ async function understandCommand(opts) {
     }
     sources = loaded.config.comprehension.sources.map((s) => ({ path: s.path, type: s.type }));
     llmConfig = loaded.config.llm;
+    loadedCodebaseRoot = loaded.config.project.codebase_root;
     const envFile = resolve25(loaded.configDir, ".env");
     try {
       process.loadEnvFile(envFile);
@@ -7776,8 +7799,19 @@ async function understandCommand(opts) {
   let productModel;
   try {
     if (opts.agent) {
-      const projectDir = process.cwd();
-      logger.info("Generating product_model via local `claude` agent", { projectDir });
+      const projectDir = resolveAgentProjectDir({
+        flagOverride: opts.projectDir,
+        codebaseRoot: opts.config ? loadedCodebaseRoot : void 0,
+        configDir: opts.config ? configDir : void 0
+      });
+      logger.info("Generating product_model via local `claude` agent", {
+        projectDir,
+        source: resolveAgentProjectDirSource({
+          flagOverride: opts.projectDir,
+          codebaseRoot: opts.config ? loadedCodebaseRoot : void 0,
+          configDir: opts.config ? configDir : void 0
+        })
+      });
       productModel = await generateProductModelViaAgent({ projectDir });
     } else if (opts.interactive) {
       const answers = await runInteractiveQA();
@@ -7822,6 +7856,24 @@ async function understandCommand(opts) {
   await writeFile15(outputPath, JSON.stringify(productModel, null, 2) + "\n", "utf8");
   logger.info("Wrote product_model.json", { path: outputPath });
 }
+function resolveAgentProjectDir(input) {
+  if (input.flagOverride) {
+    return isAbsolute13(input.flagOverride) ? input.flagOverride : resolve25(process.cwd(), input.flagOverride);
+  }
+  if (input.codebaseRoot && input.configDir) {
+    return isAbsolute13(input.codebaseRoot) ? input.codebaseRoot : resolve25(input.configDir, input.codebaseRoot);
+  }
+  if (input.configDir) {
+    return resolve25(input.configDir, "..");
+  }
+  return process.cwd();
+}
+function resolveAgentProjectDirSource(input) {
+  if (input.flagOverride) return "--project-dir flag";
+  if (input.codebaseRoot && input.configDir) return "project.codebase_root in demo.yaml";
+  if (input.configDir) return "configDir/..  (default; set project.codebase_root to override)";
+  return "cwd (no -c flag)";
+}
 
 // src/commands/instrument.ts
 import { mkdir as mkdir16, readdir as readdir4, writeFile as writeFile16 } from "fs/promises";
@@ -8442,7 +8494,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.6").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.7").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);
@@ -8481,7 +8533,10 @@ program.command("doctor").description("Run preflight checks on the current confi
 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, interactive Q&A, or agent-driven repo exploration").option("-c, --config <path>", "path to demo.yaml").option("--interactive", "use interactive Q&A mode (5 prompts, no LLM)").option(
   "--agent",
-  "delegate to the local `claude` CLI: it explores the current directory with its read tools and synthesizes the product model. Closes the type=codebase gap in demo.yaml sources."
+  "delegate to the local `claude` CLI: it explores the project with its read tools and synthesizes the product model. Closes the type=codebase gap in demo.yaml sources."
+).option(
+  "--project-dir <path>",
+  "directory the --agent run should explore. Overrides project.codebase_root from demo.yaml. Defaults to configDir/.. when -c is given, or cwd otherwise."
 ).option("--output <path>", "output path for product_model.json").action(understandCommand);
 program.command("instrument").description("Suggest data-testid attributes for a codebase").requiredOption("-c, --config <path>", "path to demo.yaml").requiredOption("--output <path>", "unified diff output path").option("--glob <pattern>", "override comprehension.sources with an ad-hoc glob (relative to configDir)").action(instrumentCommand);
 program.command("record-actions").description("Author manifest actions by demonstrating them in a live browser").requiredOption("-c, --config <path>", "path to demo.yaml").option("--segment <id>", "replace actions for an existing segment id").option("--output <path>", "manifest output path (default ./scripts/manifest.json)").action(recordActionsCommand);
@@ -8507,7 +8562,7 @@ async function printWelcome() {
   } catch {
   }
   const browserMissing = await isChromiumMissing();
-  const lines = ["", `Showrunner v1.1.6`, ""];
+  const lines = ["", `Showrunner v1.1.7`, ""];
   if (browserMissing) {
     lines.push(`Showrunner records using Chromium. You haven't installed it yet.`);
     lines.push(``);