@kadj-amoah/showrunner 1.1.4 → 1.1.6

package/CHANGELOG.md

@@ -2,6 +2,51 @@
 
 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.
+
+### Added
+
+- **`showrunner set-target` subcommand.** `set-target -c demo.yaml --url http://new-url:port` re-probes the URL, and on success rewrites `recording.target_url` in `demo.yaml`. `--force` skips the probe if you know better. Lets you re-point an existing project after starting your dev server, without re-running `init`.
+- **Port-scan during `init`.** When the user-entered URL doesn't respond, the wizard probes common dev ports on `localhost` in parallel (3000, 3001, 4321, 5173, 5174, 8000, 8080 — covers Next, CRA, Astro, Vite, Django, Vue CLI). Responding ports are offered as a `select` list so the user can just pick the one that's actually up. Total scan time is ~1 second worst case (parallel probes with 800ms timeout each).
+- **Agent-driven dev-server discovery (Phase C).** When the user picks `agent_bridge` as the LLM and has `claude` on PATH, the wizard offers to inspect the project and propose a `command + args + url`. On confirm:
+  1. Showrunner snapshots `package.json`, README head, `.env.example`, and common framework configs (vite/next/astro/nuxt/svelte/vue/webpack/remix/gatsby/rsbuild) — total payload capped at ~10 KB.
+  2. Spawns `claude -p --output-format json` with a structured prompt + Zod schema for the response.
+  3. Validates the proposal (`command`, `args[]`, `url`, `confidence`, one-sentence `rationale`).
+  4. Shows the proposal as a `note` and asks the user to confirm spawning it.
+  5. On confirm: spawns the dev-server detached + unref'd, polls the proposed URL every 750ms for up to 60s, and reports the spawned PID so the user can stop it later with `kill <pid>`.
+
+### Changed
+
+- **`init`'s URL section is now a cascade** (`text` prompt → direct probe → port-scan offer → optional agent discovery → fallback). Each step short-circuits on success, so the common case (server already running on the typed URL) still wraps in one quick probe.
+- **`src/setup/targetProbe.ts`** is now used by both `init` and `set-target`; previously the probe was inlined in `doctor`.
+
+### Known limitations
+
+- The agent-spawned dev server doesn't get tracked across runs — Showrunner doesn't write a PID file or offer a `teardown` for it. Stop it manually with `kill <pid>` (the wizard prints the PID prominently). PID-tracking is a candidate for v1.2.0.
+- `set-target` rewrites `demo.yaml` via `yaml.dump`, which strips comments from the file. Acceptable trade-off for now; CHANGELOG warns the user inline.
+- Agent discovery requires `agent_bridge` as the LLM choice. Future versions will also dispatch via `anthropic` / `openai` providers when those are selected.
+
 ## [1.1.4] — 2026-05-24
 
 **Phase A of the interactive-setup overhaul.** `showrunner init` now walks you through configuration via a real terminal wizard instead of scaffolding placeholder files and expecting you to fill them in afterwards.