@pcamarajr/scout 0.4.0 → 0.6.0

package/dist/scaffold.js

@@ -0,0 +1,82 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Onboarding artifacts written by `scout init` so any AI agent in the consuming
+ * repo can help a QA team configure Scout and author `.scout.md` scenarios.
+ *
+ * Three files, two ownership models:
+ *   - AGENTS.md (repo root) — SHARED with the user and other tools. Scout owns
+ *     only a managed block delimited by the markers below; everything outside
+ *     it is left untouched.
+ *   - .claude/skills/scout/SKILL.md and .cursor/rules/scout.mdc — Scout-OWNED,
+ *     overwritten on every init (init is the upgrade path).
+ *
+ * Re-running init refreshes all three. `scout.config.json` is never touched here.
+ */
+export const SCOUT_BLOCK_START = "<!-- scout:start -->";
+export const SCOUT_BLOCK_END = "<!-- scout:end -->";
+const AGENTS_FILE = "AGENTS.md";
+const SKILL_FILE = path.join(".claude", "skills", "scout", "SKILL.md");
+const CURSOR_RULE_FILE = path.join(".cursor", "rules", "scout.mdc");
+/** Resolve the bundled `templates/` dir, whether running from `src/` or `dist/`. */
+export function templatesDir() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    // here is <pkg>/src or <pkg>/dist → templates sits at <pkg>/templates
+    return path.join(here, "..", "templates");
+}
+function readTemplate(name) {
+    return fs.readFileSync(path.join(templatesDir(), name), "utf8");
+}
+/**
+ * Embed `body` inside the scout managed block in `existing` content.
+ *
+ *  - no existing content        → just the block.
+ *  - existing WITH a block       → replace ONLY the block's contents.
+ *  - existing WITHOUT a block    → append the block, preserving everything else.
+ */
+export function applyManagedBlock(existing, body) {
+    const block = `${SCOUT_BLOCK_START}\n${body.trim()}\n${SCOUT_BLOCK_END}\n`;
+    if (existing === undefined || existing.trim() === "") {
+        return block;
+    }
+    const startIdx = existing.indexOf(SCOUT_BLOCK_START);
+    const endIdx = existing.indexOf(SCOUT_BLOCK_END);
+    if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+        const before = existing.slice(0, startIdx);
+        const after = existing.slice(endIdx + SCOUT_BLOCK_END.length);
+        // Trim a leading newline off `after` so we don't accumulate blank lines.
+        return `${before}${block}${after.replace(/^\n/, "")}`;
+    }
+    // No block yet — append, keeping the user's content and a clean separator.
+    const sep = existing.endsWith("\n") ? "\n" : "\n\n";
+    return `${existing}${sep}${block}`;
+}
+/** Write/refresh AGENTS.md (managed block), the Claude skill, and the Cursor rule. */
+export function scaffoldAgentOnboarding(deps = {}) {
+    const cwd = deps.cwd ?? process.cwd();
+    const log = deps.log ?? ((m) => console.log(m));
+    // 1. AGENTS.md — managed block, never clobbers surrounding content.
+    const agentsPath = path.join(cwd, AGENTS_FILE);
+    const body = readTemplate("AGENTS.md");
+    const existing = fs.existsSync(agentsPath) ? fs.readFileSync(agentsPath, "utf8") : undefined;
+    const had = existing !== undefined;
+    const hadBlock = had && existing.includes(SCOUT_BLOCK_START);
+    fs.writeFileSync(agentsPath, applyManagedBlock(existing, body));
+    log(hadBlock
+        ? `✓ ${AGENTS_FILE} — refreshed the Scout block.`
+        : had
+            ? `✓ ${AGENTS_FILE} — appended the Scout block (your content kept).`
+            : `✓ ${AGENTS_FILE} created.`);
+    // 2. Claude Code skill — Scout-owned, overwrite.
+    const skillPath = path.join(cwd, SKILL_FILE);
+    fs.mkdirSync(path.dirname(skillPath), { recursive: true });
+    fs.writeFileSync(skillPath, readTemplate("SKILL.md"));
+    log(`✓ ${SKILL_FILE}`);
+    // 3. Cursor rule — Scout-owned, overwrite.
+    const cursorPath = path.join(cwd, CURSOR_RULE_FILE);
+    fs.mkdirSync(path.dirname(cursorPath), { recursive: true });
+    fs.writeFileSync(cursorPath, readTemplate("scout.mdc"));
+    log(`✓ ${CURSOR_RULE_FILE}`);
+}
+//# sourceMappingURL=scaffold.js.map

package/dist/scaffold.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.js","sourceRoot":"","sources":["../src/scaffold.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -82,6 +82,8 @@ export interface RunResult {
     durationMs: number;
     screenshots: string[];
     trace?: string;
+    /** Paced preview clip (MP4, or WebM fallback) — only when --record-video and verified */
+    video?: string;
     /** true when this AI run replaced a broken cached script */
     healed?: boolean;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pcamarajr/scout",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Self-healing browser QA: natural-language scenarios verified by an AI agent, replayed deterministically in CI",
   "type": "module",
   "license": "MIT",
@@ -35,7 +35,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "templates"
   ],
   "scripts": {
     "build": "tsc",

package/templates/AGENTS.md

@@ -0,0 +1,100 @@
+# Scout — browser QA for AI agents
+
+Scout turns **natural-language scenarios** into **AI-verified, deterministically-replayed** browser tests. A scenario is written in plain English in a `.scout.md` file; on its first `scout go` an AI agent drives a real browser (Playwright), judges the outcome, and records a deterministic script. Every later run replays that script with **no LLM** — fast and free — and only falls back to AI when the script breaks (self-heal).
+
+This file is the **single source of truth** for how an AI agent should help a QA team work with Scout in this repo. The Claude Code skill and the Cursor rule both point here.
+
+## Your primary job: co-author scenarios with QA
+
+When a QA person describes a flow they want covered, **you write the `.scout.md` directly** — do not make them hand-write it. You have full repo context (routes, components, copy, auth), so you can author a richer, more accurate spec than the CLI scaffold (`scout create`) ever could. Then you verify it and iterate with the human until it is green.
+
+The loop:
+
+1. **Author** — translate the QA person's intent into one or more scenarios in a `.scout.md` file (format below). Capture the flow *and* the expected behavior, in plain language. No selectors, no code.
+2. **Verify** — run `scout go` (optionally `-s <slug>` to target one scenario). The first run is AI-driven, in a real browser.
+3. **Interpret** — read the verdict Scout reports and relay it to the human verbatim (see *Verdicts* below).
+4. **Iterate** — refine the scenario text with QA until the verdict is `verified`, then commit the `.scout.md` and the recorded script.
+
+> `scout create <name> -f <feature> -c <text>` exists as a convenience for **humans without an agent**. As the agent, prefer authoring the `.scout.md` directly — you can write a fuller spec from repo context.
+
+## ⛔ Verification-integrity rule (non-negotiable)
+
+**Never declare a scenario working, passing, or done without actually running `scout go` and reporting the real verdict.**
+
+- Do **not** fabricate, assume, or predict success. Run it.
+- Report the verdict Scout produced **verbatim** — including the `reason` line.
+- If the result is `failed`, `partial`, or `blocked`, say so honestly. If a replay **healed**, surface that and show the script diff so a human can review what changed.
+
+This rule protects Scout's entire value proposition: a verdict is trustworthy only because it came from a real run. Inventing one poisons the suite.
+
+## The `.scout.md` authoring guide
+
+Scenarios live as markdown under `.scout/specs/**/*.scout.md` — **one file per feature/component**, versioned and reviewed like any other test. The markdown is a **pure input**: a run never writes back to it (status lives in `.scout/runs/`), so the spec diff only ever reflects an intent change.
+
+Format:
+
+```markdown
+---
+feature: Paywall          # optional; defaults to the filename
+profile: anon             # optional; default auth profile for scenarios below
+tags: [monetization]      # optional
+---
+
+## Free user hits paywall on ep 3
+Open ep 3 of series X without login; the paywall appears with a signup CTA.
+
+## Subscriber bypasses paywall
+profile: qa               # per-scenario override (also: notes, tags)
+
+Logged-in subscriber opens ep 3; the episode plays with no paywall.
+```
+
+Rules that matter when you author:
+
+- **Frontmatter** (YAML, optional): `feature` (defaults to the filename), `profile` (default auth profile), `tags`.
+- **Each `## heading` is one scenario.** Its logical slug is `<file-slug>/<scenario-slug>` (e.g. `paywall/free-user-hits-paywall-on-ep-3`) and must be unique across the suite. Duplicate headings in a file, or a scenario with no body text, are hard errors.
+- **Per-scenario overrides:** immediately under a heading you may place `profile:`, `notes:`, and `tags:` lines (before the prose) to override the file-level defaults.
+- **Body = flow + expected behavior, in plain language.** Describe what the user does and what must (or must not) be true. No CSS selectors, no Playwright code — the agent discovers the real elements at run time and records them.
+- A `.scout.md` whose every `##` lives inside a fenced ```` ``` ```` block parses as **zero scenarios** (that is how `example.scout.md` documents the format without polluting the suite).
+
+## Base URL and secrets
+
+There is a **default base URL** set at `scout init` (in `scout.config.json`). It can be **overridden per run** without editing the file:
+
+- `scout go --base-url https://staging.example.com`
+- `SCOUT_BASE_URL=https://staging.example.com scout go`
+- Precedence: `--base-url` flag > `SCOUT_BASE_URL` env > `baseUrl` in `scout.config.json`.
+
+Recorded scripts store navigation **relative to the base URL in effect at record time**, so a script recorded against `:3000` replays unchanged against staging.
+
+For credentials and tokens, never put a literal secret in a scenario. Use a **`$ENV:VAR` placeholder** — Scout resolves it from the environment at run time, in both **form fills** and **`browser_navigate` URLs** (e.g. `/renew?token=$ENV:RENEW_TOKEN`). The real value never enters the committed script and never passes through the LLM. Declare the allowed env vars per auth profile in `scout.config.json` (`profiles.<name>.env`).
+
+## Verdicts (what `scout go` reports)
+
+| Verdict | Meaning |
+|---|---|
+| `verified` ✅ | All expected behavior confirmed by assertions. |
+| `failed` ❌ | Broken behavior — the `reason` says exactly what. |
+| `partial` ⚠️ | Only part of the expected behavior was confirmed. |
+| `blocked` 🚫 | Couldn't reach the flow at all (app down, login broken). |
+
+**Healed:** when a cached script breaks but the AI re-verifies and re-records it, the run is flagged `healed`. The recorded-script diff is the heal diff — review it; a legitimate UI change is fine to commit, an unexpected one is a real regression.
+
+**Runner failure ≠ UI verdict:** an AI run can die without producing a verdict (turn budget exhausted, SDK error). Scout flags that as `runnerFailure` / 💥 — it is an infrastructure failure, **not** a judgment about the app. Rerun it; don't debug the app over it.
+
+## Secondary: helping triage a failed replay
+
+When a replay comes back `failed`/`partial`/`blocked` or `healed`, you can help — but the **human stays in the loop on intent**. Triage flow:
+
+1. Read the `reason` and open the run artifacts under `.scout/runs/<timestamp>-<slug>/` — `report.md` (verdict + recorded script), `trace.zip` (`npx playwright show-trace`), screenshots, and `transcript.md` for AI runs.
+2. Decide *with the human* whether this is a **real regression** (the app broke → fix the app) or a **legitimate UI change** (the spec/script is stale → re-verify with `scout go --ai -s <slug>` to re-record, then review the diff).
+3. Never silently re-record to make a red suite green. A green verdict must reflect reality.
+
+## Defer to the live CLI for commands and flags
+
+Commands and flags evolve — read them live instead of trusting a copy:
+
+- `scout --help` — all commands.
+- `scout <command> --help` — flags for one command (e.g. `scout go --help`).
+
+The core commands you will use: `scout go` (verify/replay), `scout list` (scenarios + status), `scout report` (suite summary, `--check` for a CI gate). `scout init` is the setup/upgrade entry point and also refreshes these onboarding files.

package/templates/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: scout
+description: >
+  Help a QA team use Scout — browser QA where natural-language scenarios are
+  AI-verified once and then replayed deterministically. TRIGGER when the user
+  mentions Scout, a `.scout.md` scenario, `scout.config.json`, `scout go` /
+  `scout init` / `scout report`, browser/E2E/QA testing of a user flow, or asks
+  to author, verify, replay, or triage a browser test scenario. Do NOT trigger
+  for unrelated unit tests or non-browser work.
+---
+
+# Scout
+
+Scout is self-healing browser QA: QA describes a flow in plain English, an AI
+agent verifies it once in a real browser and records a deterministic script,
+and every later run replays that script with no LLM.
+
+Your job is to **co-author `.scout.md` scenarios** with QA, **verify** them with
+`scout go`, and **report the real verdict** — never claim a scenario passes
+without running it.
+
+**Read `AGENTS.md` at the repo root — it is the canonical, always-current guide**
+to the authoring loop, the `.scout.md` format, base-URL/secret handling,
+verdicts, and failure triage. Follow it. For commands and flags, run
+`scout --help` / `scout <command> --help`.

package/templates/scout.mdc

@@ -0,0 +1,21 @@
+---
+description: Scout browser QA — authoring and verifying .scout.md scenarios.
+globs:
+  - "**/*.scout.md"
+  - "scout.config.json"
+alwaysApply: false
+---
+
+# Scout
+
+When working with Scout files (`*.scout.md`, `scout.config.json`), you are
+helping a QA team with **browser QA**: natural-language scenarios that are
+AI-verified once and then replayed deterministically.
+
+Co-author `.scout.md` scenarios with QA, verify them with `scout go`, and report
+the **real** verdict — never claim a scenario passes without running it.
+
+**Read `AGENTS.md` at the repo root** — it is the canonical, always-current
+guide to the authoring loop, the `.scout.md` format, base-URL/secret handling,
+verdicts, and failure triage. For commands and flags, run `scout --help` /
+`scout <command> --help`.