@kadj-amoah/showrunner 1.1.5 → 1.1.7

package/CHANGELOG.md

@@ -2,6 +2,50 @@
 
 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.
+
+### Added
+
+- **`showrunner understand --agent`** — when set, Showrunner skips the `comprehension.sources` reading path entirely and hands the project off to the local `claude` agent (spawned via `claude -p --output-format json` from `process.cwd()`). The agent uses its native Read/Glob/Grep tools to explore the repository, identify the product, and synthesize a `product_model.json` matching the existing schema. Validated against `productModelSchema` like every other path; retries on schema-violation just like the doc-driven path.
+- Mutually exclusive with `--interactive`. Errors clearly if `claude` isn't on PATH.
+
+### Why this matters
+
+Until v1.1.5, the `comprehension.sources` config accepted `type: codebase` with `include`/`exclude` globs, but the implementation (`src/commands/understand.ts:71-88`) called `readFile()` directly on `src.path` for every source type, treating directories as files (which silently fail with `EISDIR`) and ignoring the glob fields entirely. `--agent` sidesteps this: instead of teaching Showrunner to walk codebases itself (which would mean micromatch, fast-glob, binary filters, file caps, vendored-dir defaults), it lets the agent — which already has those capabilities — do the discovery.
+
+The `codebase` source type in `comprehension.sources` is **still non-functional** when passed to `understand` without `--agent` (treated as single file → silently skipped). Wiring real codebase support to the document path remains a candidate for a future release, but `--agent` is the recommended path now.
+
+### Updated error messages
+
+- When `comprehension.sources` is empty, the error now mentions all three escape hatches: add sources, `--interactive`, or `--agent`.
+
 ## [1.1.5] — 2026-05-24
 
 **Phase B + Phase C of the interactive-setup overhaul shipped together.** When the wizard's URL probe fails, it now tries progressively smarter strategies before falling back to a warning.

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
@@ -7587,6 +7599,80 @@ Regenerate the product_model strictly matching the schema.`
   }
 }
 
+// src/productModel/generateViaAgent.ts
+var DEFAULT_MAX_TOKENS5 = 8e3;
+var AGENT_SYSTEM_PROMPT = [
+  "You are helping Showrunner build a product_model.json for a product demo recording.",
+  "",
+  "You have read-only filesystem tools (Read, Glob, Grep) and can explore the project freely.",
+  "Use them \u2014 do NOT guess from the prompt alone.",
+  "",
+  "What to look for, in order:",
+  "  1. package.json (or pyproject.toml, Cargo.toml, etc.) \u2014 name, description, scripts, deps",
+  "  2. README.md / README.* at the project root \u2014 product description, primary user, features",
+  "  3. docs/PRD.md or similar \u2014 explicit product brief if present",
+  "  4. src/ tree (sample a few files) \u2014 what the product actually DOES, names of routes/pages/components",
+  "  5. .env.example \u2014 hints at integrations and external services",
+  "  6. Any framework config (next.config, vite.config, astro.config, etc.) \u2014 confirms what kind of app this is",
+  "",
+  "When you have enough signal, synthesize a product_model.json matching the requested schema.",
+  "",
+  "Rules:",
+  '  - product_name: short, exact product name as branded. Take this from package.json "name" only if it looks human, else from README.',
+  "  - tagline: one sentence, 8\u201315 words, plain language. Derived from README/PRD, not invented.",
+  `  - primary_user: one short phrase. Inferred from the README's "who is this for" framing if explicit, else from the product's shape.`,
+  "  - core_flows: 2\u20134 user flows. Each has id (kebab-case), name, 3\u20136 imperative steps from the user's POV, optional entry_url. Ground these in the actual routes/pages the codebase exposes.",
+  "  - key_features: 3\u20136 short bullets. No marketing fluff.",
+  "  - demo_recommendation.suggested_flows: ids from core_flows, in demo order.",
+  "  - demo_recommendation.suggested_duration_seconds: 60\u201390 typical.",
+  "  - confidence: 'high' if you found explicit, clear sources; 'medium' if you had to infer; 'low' if the codebase was sparse and you mostly guessed.",
+  "  - source: always 'documents' (this path counts as document-driven, just agentically discovered).",
+  "  - generated_at: ISO-8601 timestamp.",
+  "",
+  "Output exactly the structured JSON. No prose, no commentary, no markdown fence outside the JSON."
+].join("\n");
+async function generateProductModelViaAgent(opts) {
+  const provider = new AgentBridgeLLMProvider({
+    mode: "spawn",
+    command: opts.command ?? "claude",
+    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 = [
+    `Project directory: ${opts.projectDir}`,
+    "",
+    "Explore this directory with your filesystem tools, then synthesize a product_model.json."
+  ].join("\n");
+  logger.debug("Generating product_model via agent", { projectDir: opts.projectDir });
+  try {
+    return await generateWithRetry(provider, {
+      systemPrompt: AGENT_SYSTEM_PROMPT,
+      userPrompt,
+      schema: productModelSchema,
+      schemaName: "product_model",
+      maxTokens: DEFAULT_MAX_TOKENS5,
+      retryRenderer: (errorText, prevUserPrompt) => `${prevUserPrompt}
+
+Your previous output failed validation with this error:
+${errorText}
+
+Regenerate the product_model strictly matching the schema.`
+    });
+  } catch (err) {
+    throw new ProductModelGenerationError(err instanceof Error ? err.message : String(err));
+  }
+}
+
 // src/productModel/interactive.ts
 import { createInterface as createInterface2 } from "readline";
 var LineReader = class {
@@ -7675,10 +7761,15 @@ function clamp(n, lo, hi) {
 
 // src/commands/understand.ts
 async function understandCommand(opts) {
+  if (opts.interactive && opts.agent) {
+    logger.error("--interactive and --agent are mutually exclusive. Pick one.");
+    process.exit(2);
+  }
   let configDir = process.cwd();
   let outputRel = opts.output ?? "./product_model.json";
   let sources = [];
   let llmConfig;
+  let loadedCodebaseRoot;
   if (opts.config) {
     let loaded;
     try {
@@ -7696,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);
@@ -7705,16 +7797,31 @@ async function understandCommand(opts) {
   const outputPath = isAbsolute13(outputRel) ? outputRel : resolve25(configDir, outputRel);
   await mkdir15(dirname13(outputPath), { recursive: true });
   let productModel;
-  const provider = resolveDefaultLLMProvider({ configDir, llm: llmConfig });
   try {
-    if (opts.interactive) {
+    if (opts.agent) {
+      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();
       logger.info("Generating product_model from interactive answers");
+      const provider = resolveDefaultLLMProvider({ configDir, llm: llmConfig });
       productModel = await generateProductModelFromInteractive({ answers, provider });
     } else {
       if (sources.length === 0) {
         logger.error(
-          "No `comprehension.sources` configured in demo.yaml. Add at least one source (prd, readme, codebase, etc.) or re-run with --interactive."
+          "No `comprehension.sources` configured in demo.yaml. Add at least one source (prd, readme, codebase, etc.), re-run with --interactive (Q&A), or re-run with --agent (the local `claude` CLI explores your repo)."
         );
         process.exit(2);
       }
@@ -7736,6 +7843,7 @@ async function understandCommand(opts) {
       logger.info("Generating product_model from documents", {
         sources: docs.map((d) => d.path)
       });
+      const provider = resolveDefaultLLMProvider({ configDir, llm: llmConfig });
       productModel = await generateProductModelFromDocs({ sources: docs, provider });
     }
   } catch (err) {
@@ -7748,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";
@@ -7832,7 +7958,7 @@ function pickAttr(node, attr) {
 
 // src/instrument/suggest.ts
 import { z as z10 } from "zod";
-var DEFAULT_MAX_TOKENS5 = 8e3;
+var DEFAULT_MAX_TOKENS6 = 8e3;
 var suggestionSchema = z10.object({
   suggestions: z10.array(
     z10.object({
@@ -7878,7 +8004,7 @@ For each, return {file, line, original (exact source line), replacement (source
       userPrompt,
       schema: suggestionSchema,
       schemaName: "instrument_suggestions",
-      maxTokens: DEFAULT_MAX_TOKENS5
+      maxTokens: DEFAULT_MAX_TOKENS6
     });
     return result.suggestions;
   } catch (err) {
@@ -8368,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.5").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);
@@ -8405,7 +8531,13 @@ program.command("set-target").description("Update demo.yaml's recording.target_u
 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);
+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 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);
 program.command("preview").description("Preview the generated Playwright script in UI Mode").requiredOption("-c, --config <path>", "path to demo.yaml").action(previewCommand);
@@ -8430,7 +8562,7 @@ async function printWelcome() {
   } catch {
   }
   const browserMissing = await isChromiumMissing();
-  const lines = ["", `Showrunner v1.1.5`, ""];
+  const lines = ["", `Showrunner v1.1.7`, ""];
   if (browserMissing) {
     lines.push(`Showrunner records using Chromium. You haven't installed it yet.`);
     lines.push(``);