@kadj-amoah/showrunner 1.1.5 → 1.1.6

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 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.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

@@ -7587,6 +7587,71 @@ 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"],
+    timeoutMs: opts.timeoutMs ?? 18e4,
+    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,6 +7740,10 @@ 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 = [];
@@ -7705,16 +7774,20 @@ 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 = process.cwd();
+      logger.info("Generating product_model via local `claude` agent", { projectDir });
+      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 +7809,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) {
@@ -7832,7 +7906,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 +7952,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 +8442,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.6").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 +8479,10 @@ 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 current directory with its read tools and synthesizes the product model. Closes the type=codebase gap in demo.yaml sources."
+).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 +8507,7 @@ async function printWelcome() {
   } catch {
   }
   const browserMissing = await isChromiumMissing();
-  const lines = ["", `Showrunner v1.1.5`, ""];
+  const lines = ["", `Showrunner v1.1.6`, ""];
   if (browserMissing) {
     lines.push(`Showrunner records using Chromium. You haven't installed it yet.`);
     lines.push(``);