@pcamarajr/scout 0.3.0 → 0.5.0

package/dist/runner/video.js

@@ -0,0 +1,197 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+const BASE_SLOWMO = 200;
+function clamp(n, lo, hi) {
+    return Math.min(hi, Math.max(lo, n));
+}
+/**
+ * Maps the single `videoSpeed` knob (0,1] to concrete pacing. <1 = slower.
+ * At 1.0 the replay runs at natural speed; the default 0.4 yields a clip a
+ * human can actually follow.
+ */
+export function pacingFor(videoSpeed = 0.4) {
+    const speed = clamp(videoSpeed, 0.1, 1);
+    return {
+        slowMoMs: Math.round(BASE_SLOWMO * (1 / speed - 1)),
+        assertDwellMs: Math.round(500 / speed),
+        titleCardMs: 1500,
+        verdictCardMs: 1800,
+    };
+}
+const FONT_CANDIDATES = [
+    "/System/Library/Fonts/Supplemental/Arial.ttf",
+    "/Library/Fonts/Arial.ttf",
+    "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
+    "/usr/share/fonts/truetype/liberation/LiberationSans-Regular.ttf",
+    "/usr/share/fonts/TTF/DejaVuSans.ttf",
+    "C:\\Windows\\Fonts\\arial.ttf",
+];
+/** First usable font: SCOUT_VIDEO_FONT override, then common system paths. */
+export function resolveFont() {
+    const override = process.env.SCOUT_VIDEO_FONT;
+    if (override && fs.existsSync(override))
+        return override;
+    return FONT_CANDIDATES.find((f) => fs.existsSync(f));
+}
+/** Resolves the ffmpeg binary (FFMPEG_PATH or PATH), or undefined if absent. */
+export function findFfmpeg() {
+    const bin = process.env.FFMPEG_PATH || "ffmpeg";
+    const probe = spawnSync(bin, ["-version"], { stdio: "ignore" });
+    return probe.status === 0 ? bin : undefined;
+}
+function probeDurationMs(ffmpegBin, file) {
+    const ffprobe = process.env.FFPROBE_PATH ||
+        (ffmpegBin.endsWith("ffmpeg") ? ffmpegBin.replace(/ffmpeg$/, "ffprobe") : "ffprobe");
+    const r = spawnSync(ffprobe, ["-v", "error", "-show_entries", "format=duration", "-of", "default=nw=1:nk=1", file], { encoding: "utf8" });
+    if (r.status === 0) {
+        const seconds = parseFloat(r.stdout.trim());
+        if (!Number.isNaN(seconds))
+            return Math.round(seconds * 1000);
+    }
+    return undefined;
+}
+const VERDICT_COLOR = {
+    verified: "0x2ECC71",
+    failed: "0xE74C3C",
+    partial: "0xF39C12",
+    blocked: "0x95A5A6",
+};
+const VERDICT_LABEL = {
+    verified: "VERIFICADO",
+    failed: "FALHOU",
+    partial: "PARCIAL",
+    blocked: "BLOQUEADO",
+};
+/** drawtext text=' ' wraps the value, so only quotes/backslashes must go. */
+function safeText(s) {
+    return s.replace(/['\\]/g, "").trim();
+}
+/** Approx Arial glyph advance as a fraction of font size — for width fitting. */
+const GLYPH_RATIO = 0.56;
+/**
+ * drawtext can't wrap, so we shrink the font to fit `maxWidth`, and if even the
+ * minimum size overflows we truncate with an ellipsis. Keeps long scenario
+ * names and step labels inside the portrait frame instead of bleeding off-edge.
+ */
+function fitText(value, maxWidth, maxSize, minSize) {
+    const len = Math.max(value.length, 1);
+    const size = Math.floor(maxWidth / (len * GLYPH_RATIO));
+    if (size >= maxSize)
+        return { text: value, size: maxSize };
+    if (size >= minSize)
+        return { text: value, size };
+    const maxChars = Math.max(4, Math.floor(maxWidth / (minSize * GLYPH_RATIO)) - 1);
+    return { text: value.length > maxChars ? value.slice(0, maxChars - 1) + "…" : value, size: minSize };
+}
+/**
+ * Builds the ffmpeg `-vf` filtergraph that bakes the overlays. Drawn in array
+ * order (later filters sit on top): step captions first, then the opening
+ * card, then the verdict card last so it covers the held final frame.
+ * Returns "" when no font is available — caller still transcodes, just plain.
+ */
+export function buildOverlayFilter(spec) {
+    const { font, width, durationMs, pacing } = spec;
+    if (!font)
+        return "";
+    const dur = durationMs / 1000;
+    const titleSec = Math.min(pacing.titleCardMs / 1000, dur * 0.4);
+    const verdictStart = Math.max(titleSec, dur - pacing.verdictCardMs / 1000);
+    const ff = safeText(font);
+    const between = (a, b) => `enable='between(t,${a.toFixed(2)},${b.toFixed(2)})'`;
+    const text = (value, opts) => [
+        `drawtext=fontfile='${ff}'`,
+        `text='${safeText(value)}'`,
+        `fontcolor=${opts.color}`,
+        `fontsize=${opts.size}`,
+        opts.box ? "box=1:boxcolor=black@0.55:boxborderw=14" : "",
+        "x=(w-text_w)/2",
+        `y=${opts.y}`,
+        "expansion=none",
+        between(opts.a, opts.b),
+    ]
+        .filter(Boolean)
+        .join(":");
+    const fullBox = (a, b, alpha = "0.6") => `drawbox=x=0:y=0:w=iw:h=ih:color=black@${alpha}:t=fill:${between(a, b)}`;
+    const filters = [];
+    // Step captions — bounded so a long script can't explode the graph.
+    spec.timeline.slice(0, 80).forEach((entry, i) => {
+        const a = Math.max(entry.tMs / 1000, titleSec);
+        const next = spec.timeline[i + 1];
+        const b = next ? next.tMs / 1000 : verdictStart;
+        if (a >= b)
+            return;
+        const fit = fitText(entry.label, width - 68, 26, 14); // box border eats horizontal room
+        filters.push(text(fit.text, { size: fit.size, color: "white", y: "h-text_h-60", box: true, a, b }));
+    });
+    // Opening card.
+    const title = fitText(spec.scenarioName, width - 40, 40, 18);
+    filters.push(fullBox(0, titleSec));
+    filters.push(text(title.text, { size: title.size, color: "white", y: "(h/2)-70", a: 0, b: titleSec }));
+    filters.push(text("scout preview", { size: 22, color: "0xBDC3C7", y: "(h/2)+10", a: 0, b: titleSec }));
+    // Closing verdict card.
+    const verdict = fitText(VERDICT_LABEL[spec.verdict], width - 40, 52, 24);
+    filters.push(fullBox(verdictStart, dur));
+    filters.push(text(verdict.text, {
+        size: verdict.size,
+        color: VERDICT_COLOR[spec.verdict],
+        y: "(h-text_h)/2",
+        a: verdictStart,
+        b: dur,
+    }));
+    return filters.join(",");
+}
+/**
+ * Transcodes the paced WebM to an H.264 MP4 (GitHub-playable) with baked
+ * overlays. On any ffmpeg problem the raw WebM is returned as a fallback so
+ * `--record-video` always yields a playable file.
+ */
+export function generateVideo(input) {
+    const ffmpeg = findFfmpeg();
+    if (!ffmpeg) {
+        return {
+            output: input.webmPath,
+            warning: "ffmpeg não encontrado — MP4 com overlays não gerado, mantido o WebM cru. Instale ffmpeg (brew install ffmpeg / apt-get install ffmpeg) ou defina FFMPEG_PATH.",
+        };
+    }
+    const font = resolveFont();
+    const durationMs = probeDurationMs(ffmpeg, input.webmPath) ??
+        (input.timeline.at(-1)?.tMs ?? 0) + input.pacing.verdictCardMs;
+    const filter = buildOverlayFilter({
+        font: font ?? "",
+        width: input.width,
+        height: input.height,
+        durationMs,
+        scenarioName: input.scenarioName,
+        verdict: input.verdict,
+        timeline: input.timeline,
+        pacing: input.pacing,
+    });
+    const args = [
+        "-y",
+        "-i",
+        input.webmPath,
+        ...(filter ? ["-vf", filter] : []),
+        "-c:v",
+        "libx264",
+        "-pix_fmt",
+        "yuv420p",
+        "-movflags",
+        "+faststart",
+        "-an",
+        input.outPath,
+    ];
+    const run = spawnSync(ffmpeg, args, { stdio: "ignore" });
+    if (run.status !== 0) {
+        return {
+            output: input.webmPath,
+            warning: "ffmpeg falhou ao gerar o MP4 — mantido o WebM cru.",
+        };
+    }
+    return {
+        output: input.outPath,
+        warning: font
+            ? undefined
+            : "Nenhuma fonte encontrada para os overlays — MP4 gerado sem legendas. Defina SCOUT_VIDEO_FONT apontando para um .ttf.",
+    };
+}
+//# sourceMappingURL=video.js.map

package/dist/runner/video.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"video.js","sourceRoot":"","sources":["../../src/runner/video.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,MAAM,SAAS,CAAC;AA6BzB,MAAM,WAAW,GAAG,GAAG,CAAC;AAExB,SAAS,KAAK,CAAC,CAAS,EAAE,EAAU,EAAE,EAAU;IAC9C,OAAO,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;AACvC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,UAAU,GAAG,GAAG;IACxC,MAAM,KAAK,GAAG,KAAK,CAAC,UAAU,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;IACxC,OAAO;QACL,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,WAAW,GAAG,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC;QACnD,aAAa,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,KAAK,CAAC;QACtC,WAAW,EAAE,IAAI;QACjB,aAAa,EAAE,IAAI;KACpB,CAAC;AACJ,CAAC;AAED,MAAM,eAAe,GAAG;IACtB,8CAA8C;IAC9C,0BAA0B;IAC1B,iDAAiD;IACjD,iEAAiE;IACjE,qCAAqC;IACrC,+BAA+B;CAChC,CAAC;AAEF,8EAA8E;AAC9E,MAAM,UAAU,WAAW;IACzB,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;IAC9C,IAAI,QAAQ,IAAI,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,QAAQ,CAAC;IACzD,OAAO,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;AACvD,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,UAAU;IACxB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,QAAQ,CAAC;IAChD,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;IAChE,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;AAC9C,CAAC;AAED,SAAS,eAAe,CAAC,SAAiB,EAAE,IAAY;IACtD,MAAM,OAAO,GACX,OAAO,CAAC,GAAG,CAAC,YAAY;QACxB,CAAC,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IACvF,MAAM,CAAC,GAAG,SAAS,CACjB,OAAO,EACP,CAAC,IAAI,EAAE,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,KAAK,EAAE,mBAAmB,EAAE,IAAI,CAAC,EACrF,EAAE,QAAQ,EAAE,MAAM,EAAE,CACrB,CAAC;IACF,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACnB,MAAM,OAAO,GAAG,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;QAC5C,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC;YAAE,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IAChE,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,aAAa,GAA4B;IAC7C,QAAQ,EAAE,UAAU;IACpB,MAAM,EAAE,UAAU;IAClB,OAAO,EAAE,UAAU;IACnB,OAAO,EAAE,UAAU;CACpB,CAAC;AAEF,MAAM,aAAa,GAA4B;IAC7C,QAAQ,EAAE,YAAY;IACtB,MAAM,EAAE,QAAQ;IAChB,OAAO,EAAE,SAAS;IAClB,OAAO,EAAE,WAAW;CACrB,CAAC;AAEF,6EAA6E;AAC7E,SAAS,QAAQ,CAAC,CAAS;IACzB,OAAO,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;AACxC,CAAC;AAED,iFAAiF;AACjF,MAAM,WAAW,GAAG,IAAI,CAAC;AAEzB;;;;GAIG;AACH,SAAS,OAAO,CACd,KAAa,EACb,QAAgB,EAChB,OAAe,EACf,OAAe;IAEf,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IACtC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,GAAG,CAAC,GAAG,GAAG,WAAW,CAAC,CAAC,CAAC;IACxD,IAAI,IAAI,IAAI,OAAO;QAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAC3D,IAAI,IAAI,IAAI,OAAO;QAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IAClD,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,GAAG,CAAC,OAAO,GAAG,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACjF,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AACvG,CAAC;AAaD;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAiB;IAClD,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IACjD,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IACrB,MAAM,GAAG,GAAG,UAAU,GAAG,IAAI,CAAC;IAC9B,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,WAAW,GAAG,IAAI,EAAE,GAAG,GAAG,GAAG,CAAC,CAAC;IAChE,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,GAAG,MAAM,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IAC3E,MAAM,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;IAE1B,MAAM,OAAO,GAAG,CAAC,CAAS,EAAE,CAAS,EAAE,EAAE,CAAC,qBAAqB,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;IAChG,MAAM,IAAI,GAAG,CACX,KAAa,EACb,IAAqF,EACrF,EAAE,CACF;QACE,sBAAsB,EAAE,GAAG;QAC3B,SAAS,QAAQ,CAAC,KAAK,CAAC,GAAG;QAC3B,aAAa,IAAI,CAAC,KAAK,EAAE;QACzB,YAAY,IAAI,CAAC,IAAI,EAAE;QACvB,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,yCAAyC,CAAC,CAAC,CAAC,EAAE;QACzD,gBAAgB;QAChB,KAAK,IAAI,CAAC,CAAC,EAAE;QACb,gBAAgB;QAChB,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;KACxB;SACE,MAAM,CAAC,OAAO,CAAC;SACf,IAAI,CAAC,GAAG,CAAC,CAAC;IACf,MAAM,OAAO,GAAG,CAAC,CAAS,EAAE,CAAS,EAAE,KAAK,GAAG,KAAK,EAAE,EAAE,CACtD,yCAAyC,KAAK,WAAW,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;IAE3E,MAAM,OAAO,GAAa,EAAE,CAAC;IAE7B,oEAAoE;IACpE,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE;QAC9C,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,GAAG,IAAI,EAAE,QAAQ,CAAC,CAAC;QAC/C,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QAClC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,YAAY,CAAC;QAChD,IAAI,CAAC,IAAI,CAAC;YAAE,OAAO;QACnB,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,kCAAkC;QACxF,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,EAAE,aAAa,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IACtG,CAAC,CAAC,CAAC;IAEH,gBAAgB;IAChB,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,KAAK,GAAG,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;IAC7D,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC;IACnC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC;IACvG,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC;IAEvG,wBAAwB;IACxB,MAAM,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,KAAK,GAAG,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;IACzE,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC,CAAC;IACzC,OAAO,CAAC,IAAI,CACV,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE;QACjB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC;QAClC,CAAC,EAAE,cAAc;QACjB,CAAC,EAAE,YAAY;QACf,CAAC,EAAE,GAAG;KACP,CAAC,CACH,CAAC;IAEF,OAAO,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC3B,CAAC;AAmBD;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,KAAyB;IACrD,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;IAC5B,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO;YACL,MAAM,EAAE,KAAK,CAAC,QAAQ;YACtB,OAAO,EACL,+JAA+J;SAClK,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GAAG,WAAW,EAAE,CAAC;IAC3B,MAAM,UAAU,GACd,eAAe,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC;QACvC,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,aAAa,CAAC;IACjE,MAAM,MAAM,GAAG,kBAAkB,CAAC;QAChC,IAAI,EAAE,IAAI,IAAI,EAAE;QAChB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,UAAU;QACV,YAAY,EAAE,KAAK,CAAC,YAAY;QAChC,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,MAAM,EAAE,KAAK,CAAC,MAAM;KACrB,CAAC,CAAC;IAEH,MAAM,IAAI,GAAG;QACX,IAAI;QACJ,IAAI;QACJ,KAAK,CAAC,QAAQ;QACd,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAClC,MAAM;QACN,SAAS;QACT,UAAU;QACV,SAAS;QACT,WAAW;QACX,YAAY;QACZ,KAAK;QACL,KAAK,CAAC,OAAO;KACd,CAAC;IACF,MAAM,GAAG,GAAG,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;IACzD,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrB,OAAO;YACL,MAAM,EAAE,KAAK,CAAC,QAAQ;YACtB,OAAO,EAAE,oDAAoD;SAC9D,CAAC;IACJ,CAAC;IAED,OAAO;QACL,MAAM,EAAE,KAAK,CAAC,OAAO;QACrB,OAAO,EAAE,IAAI;YACX,CAAC,CAAC,SAAS;YACX,CAAC,CAAC,sHAAsH;KAC3H,CAAC;AACJ,CAAC"}

package/dist/specs.d.ts

@@ -0,0 +1,33 @@
+import type { Scenario } from "./types.js";
+/**
+ * Scenario specs live as markdown files under `.scout/specs/**\/*.scout.md`.
+ * One file per feature/component; each `## heading` is one scenario. The
+ * markdown is the human-authored source of truth — a *pure input* that is
+ * never written back to by a run (status/last-run derive from `.scout/runs/`).
+ *
+ * The format mirrors the Playwright Agents test-plan layout (feature file with
+ * scenario sections) and adds YAML frontmatter as a superset for scout-specific
+ * config (profile, tags). Per-scenario overrides may follow a heading as
+ * `key: value` lines before the prose.
+ */
+export declare const SPECS_DIR = "specs";
+export declare function slugify(name: string): string;
+/** A logical slug `<file>/<scenario>` → a single filesystem-safe token. */
+export declare function slugToToken(slug: string): string;
+/** Parse a single `.scout.md` file into its scenarios. */
+export declare function parseSpec(specFile: string, root: string, cwd: string): Scenario[];
+/** Load every scenario across all spec files, validating slug uniqueness. */
+export declare function loadScenarios(cwd?: string): Scenario[];
+export interface NewScenarioInput {
+    feature: string;
+    name: string;
+    scenario: string;
+    profile?: string;
+    notes?: string;
+    tags?: string[];
+}
+/**
+ * Append a scenario to `.scout/specs/<feature-slug>.scout.md`, creating the
+ * file with frontmatter when it does not exist. Returns the logical slug.
+ */
+export declare function addScenario(input: NewScenarioInput, cwd?: string): Scenario;

package/dist/specs.js

@@ -0,0 +1,198 @@
+import fs from "node:fs";
+import path from "node:path";
+import matter from "gray-matter";
+import { SCOUT_DIR } from "./config.js";
+/**
+ * Scenario specs live as markdown files under `.scout/specs/**\/*.scout.md`.
+ * One file per feature/component; each `## heading` is one scenario. The
+ * markdown is the human-authored source of truth — a *pure input* that is
+ * never written back to by a run (status/last-run derive from `.scout/runs/`).
+ *
+ * The format mirrors the Playwright Agents test-plan layout (feature file with
+ * scenario sections) and adds YAML frontmatter as a superset for scout-specific
+ * config (profile, tags). Per-scenario overrides may follow a heading as
+ * `key: value` lines before the prose.
+ */
+export const SPECS_DIR = "specs";
+const SPEC_EXT = ".scout.md";
+/** Per-scenario override keys allowed under a heading. */
+const OVERRIDE_KEYS = new Set(["profile", "notes", "tags"]);
+export function slugify(name) {
+    return name
+        .toLowerCase()
+        .normalize("NFD")
+        .replace(/[̀-ͯ]/g, "")
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "")
+        .slice(0, 60);
+}
+/** A logical slug `<file>/<scenario>` → a single filesystem-safe token. */
+export function slugToToken(slug) {
+    return slug.replace(/\//g, "__");
+}
+function specsRoot(cwd) {
+    return path.join(cwd, SCOUT_DIR, SPECS_DIR);
+}
+/** All `*.scout.md` under `.scout/specs`, recursively, sorted for stable order. */
+function findSpecFiles(dir) {
+    if (!fs.existsSync(dir))
+        return [];
+    const out = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory())
+            out.push(...findSpecFiles(full));
+        else if (entry.isFile() && entry.name.endsWith(SPEC_EXT))
+            out.push(full);
+    }
+    return out.sort();
+}
+/** `.scout/specs/auth/login.scout.md` → `auth/login` (each segment slugified). */
+function fileSlugFromPath(specFile, root) {
+    const rel = path.relative(root, specFile).replace(new RegExp(`${SPEC_EXT.replace(".", "\\.")}$`), "");
+    return rel
+        .split(path.sep)
+        .map((seg) => slugify(seg))
+        .join("/");
+}
+function parseTags(raw) {
+    if (Array.isArray(raw))
+        return raw.map(String);
+    if (typeof raw === "string") {
+        const inner = raw.trim().replace(/^\[|\]$/g, "");
+        const parts = inner.split(",").map((t) => t.trim()).filter(Boolean);
+        return parts.length ? parts : undefined;
+    }
+    return undefined;
+}
+/**
+ * Split markdown body into `## ` sections (h1/h3+ and preamble are ignored).
+ * Fenced code blocks (``` ... ```) are skipped so a documented `## ` inside a
+ * fence is not mistaken for a real scenario heading.
+ */
+function splitSections(content) {
+    const sections = [];
+    let cur = null;
+    let inFence = false;
+    for (const line of content.split("\n")) {
+        if (/^\s*```/.test(line))
+            inFence = !inFence;
+        const m = inFence ? null : /^##\s+(.+?)\s*$/.exec(line);
+        if (m) {
+            cur = { name: m[1].trim(), bodyLines: [] };
+            sections.push(cur);
+        }
+        else if (cur) {
+            cur.bodyLines.push(line);
+        }
+    }
+    return sections;
+}
+/** Parse a single `.scout.md` file into its scenarios. */
+export function parseSpec(specFile, root, cwd) {
+    const fileSlug = fileSlugFromPath(specFile, root);
+    const raw = fs.readFileSync(specFile, "utf8");
+    const { data, content } = matter(raw);
+    const fileFeature = typeof data.feature === "string" ? data.feature : path.basename(specFile).replace(SPEC_EXT, "");
+    const fileProfile = typeof data.profile === "string" ? data.profile : undefined;
+    const fileTags = parseTags(data.tags);
+    const relFile = path.relative(cwd, specFile);
+    const sections = splitSections(content);
+    const scenarios = [];
+    const seen = new Set();
+    for (const section of sections) {
+        // Consume optional leading `key: value` overrides, then the prose.
+        const lines = section.bodyLines;
+        let i = 0;
+        while (i < lines.length && lines[i].trim() === "")
+            i++;
+        const overrides = {};
+        while (i < lines.length && lines[i].trim() !== "") {
+            const m = /^([a-zA-Z]+):\s*(.+)$/.exec(lines[i].trim());
+            if (!m || !OVERRIDE_KEYS.has(m[1]))
+                break;
+            overrides[m[1]] = m[2].trim();
+            i++;
+        }
+        while (i < lines.length && lines[i].trim() === "")
+            i++;
+        const text = lines.slice(i).join("\n").trim();
+        if (!text) {
+            throw new Error(`Scenario "${section.name}" in ${relFile} has no description text.`);
+        }
+        const scenarioSlug = slugify(section.name);
+        if (seen.has(scenarioSlug)) {
+            throw new Error(`Duplicate scenario "${section.name}" (slug "${scenarioSlug}") in ${relFile}.`);
+        }
+        seen.add(scenarioSlug);
+        const tags = parseTags(overrides.tags) ?? fileTags;
+        scenarios.push({
+            slug: `${fileSlug}/${scenarioSlug}`,
+            name: section.name,
+            scenario: text,
+            feature: fileFeature,
+            profile: overrides.profile ?? fileProfile,
+            notes: overrides.notes,
+            tags,
+            file: relFile,
+        });
+    }
+    return scenarios;
+}
+/** Load every scenario across all spec files, validating slug uniqueness. */
+export function loadScenarios(cwd = process.cwd()) {
+    const root = specsRoot(cwd);
+    const all = [];
+    const bySlug = new Map();
+    for (const file of findSpecFiles(root)) {
+        for (const scenario of parseSpec(file, root, cwd)) {
+            const prev = bySlug.get(scenario.slug);
+            if (prev) {
+                throw new Error(`Duplicate scenario slug "${scenario.slug}" in ${scenario.file} (also in ${prev}).`);
+            }
+            bySlug.set(scenario.slug, scenario.file);
+            all.push(scenario);
+        }
+    }
+    return all;
+}
+/** Render a `## ` section (with optional overrides) for appending to a spec. */
+function renderSection(input) {
+    const overrides = [];
+    if (input.profile)
+        overrides.push(`profile: ${input.profile}`);
+    if (input.notes)
+        overrides.push(`notes: ${input.notes}`);
+    if (input.tags?.length)
+        overrides.push(`tags: [${input.tags.join(", ")}]`);
+    const head = `## ${input.name}\n`;
+    const meta = overrides.length ? overrides.join("\n") + "\n\n" : "";
+    return `${head}${meta}${input.scenario.trim()}\n`;
+}
+/**
+ * Append a scenario to `.scout/specs/<feature-slug>.scout.md`, creating the
+ * file with frontmatter when it does not exist. Returns the logical slug.
+ */
+export function addScenario(input, cwd = process.cwd()) {
+    const root = specsRoot(cwd);
+    const fileSlug = slugify(input.feature);
+    const specFile = path.join(root, `${fileSlug}${SPEC_EXT}`);
+    fs.mkdirSync(path.dirname(specFile), { recursive: true });
+    const section = renderSection(input);
+    if (!fs.existsSync(specFile)) {
+        const frontmatter = `---\nfeature: ${input.feature}\n---\n\n`;
+        fs.writeFileSync(specFile, frontmatter + section);
+    }
+    else {
+        const existing = fs.readFileSync(specFile, "utf8").replace(/\s*$/, "");
+        fs.writeFileSync(specFile, existing + "\n\n" + section);
+    }
+    const scenarioSlug = slugify(input.name);
+    const slug = `${fileSlug}/${scenarioSlug}`;
+    const found = parseSpec(specFile, root, cwd).find((s) => s.slug === slug);
+    if (!found) {
+        throw new Error(`Failed to round-trip scenario "${input.name}" into ${path.relative(cwd, specFile)}.`);
+    }
+    return found;
+}
+//# sourceMappingURL=specs.js.map

package/dist/specs.js.map

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

package/dist/store.d.ts

@@ -1,27 +1,19 @@
 import type { RunResult, Scenario, Step } from "./types.js";
 /**
  * Filesystem store inside the target project:
- *   .scout/scenarios.json        — committed (the suite definition)
- *   .scout/scripts/<slug>.json   — committed (cached deterministic steps)
- *   .scout/runs/<runId>/         — gitignored (artifacts per run)
- *   .scout/state/<profile>.json  — gitignored (auth storageState)
+ *   .scout/specs/<feature>.scout.md  — committed (the suite; markdown source of truth)
+ *   .scout/scripts/<slug>.json       — committed (cached deterministic steps; `<slug>` is `<file>/<scenario>`)
+ *   .scout/runs/<runId>/             — gitignored (artifacts per run)
+ *   .scout/state/<profile>.json      — gitignored (auth storageState)
  */
 export declare class Store {
     readonly root: string;
+    readonly cwd: string;
     constructor(cwd?: string);
     init(): void;
-    get scenariosFile(): string;
     exists(): boolean;
     listScenarios(): Scenario[];
-    saveScenarios(scenarios: Scenario[]): void;
-    addScenario(input: {
-        name: string;
-        scenario: string;
-        profile?: string;
-        notes?: string;
-    }): Scenario;
-    getScenario(idOrSlug: number | string): Scenario | undefined;
-    updateScenario(id: number, patch: Partial<Scenario>): void;
+    getScenario(slug: string): Scenario | undefined;
     scriptPath(slug: string): string;
     loadSteps(slug: string): Step[] | undefined;
     saveSteps(slug: string, steps: Step[]): void;
@@ -30,4 +22,3 @@ export declare class Store {
     /** Latest run result per scenario slug (for `scout report`) */
     latestRuns(): Map<string, RunResult>;
 }
-export declare function slugify(name: string): string;

package/dist/store.js

@@ -1,19 +1,23 @@
 import fs from "node:fs";
 import path from "node:path";
 import { SCOUT_DIR } from "./config.js";
+import { SPECS_DIR, loadScenarios, slugToToken } from "./specs.js";
 /**
  * Filesystem store inside the target project:
- *   .scout/scenarios.json        — committed (the suite definition)
- *   .scout/scripts/<slug>.json   — committed (cached deterministic steps)
- *   .scout/runs/<runId>/         — gitignored (artifacts per run)
- *   .scout/state/<profile>.json  — gitignored (auth storageState)
+ *   .scout/specs/<feature>.scout.md  — committed (the suite; markdown source of truth)
+ *   .scout/scripts/<slug>.json       — committed (cached deterministic steps; `<slug>` is `<file>/<scenario>`)
+ *   .scout/runs/<runId>/             — gitignored (artifacts per run)
+ *   .scout/state/<profile>.json      — gitignored (auth storageState)
  */
 export class Store {
     root;
+    cwd;
     constructor(cwd = process.cwd()) {
+        this.cwd = cwd;
         this.root = path.join(cwd, SCOUT_DIR);
     }
     init() {
+        fs.mkdirSync(path.join(this.root, SPECS_DIR), { recursive: true });
         fs.mkdirSync(path.join(this.root, "scripts"), { recursive: true });
         fs.mkdirSync(path.join(this.root, "runs"), { recursive: true });
         fs.mkdirSync(path.join(this.root, "state"), { recursive: true });
@@ -21,51 +25,19 @@ export class Store {
         if (!fs.existsSync(gitignore)) {
             fs.writeFileSync(gitignore, "runs/\nstate/\n");
         }
-        if (!fs.existsSync(this.scenariosFile)) {
-            fs.writeFileSync(this.scenariosFile, "[]\n");
+        const example = path.join(this.root, SPECS_DIR, "example.scout.md");
+        if (!fs.existsSync(example)) {
+            fs.writeFileSync(example, EXAMPLE_SPEC);
         }
     }
-    get scenariosFile() {
-        return path.join(this.root, "scenarios.json");
-    }
     exists() {
-        return fs.existsSync(this.scenariosFile);
+        return fs.existsSync(this.root);
     }
     listScenarios() {
-        if (!this.exists())
-            return [];
-        return JSON.parse(fs.readFileSync(this.scenariosFile, "utf8"));
-    }
-    saveScenarios(scenarios) {
-        fs.writeFileSync(this.scenariosFile, JSON.stringify(scenarios, null, 2) + "\n");
-    }
-    addScenario(input) {
-        const scenarios = this.listScenarios();
-        const id = scenarios.length ? Math.max(...scenarios.map((s) => s.id)) + 1 : 1;
-        const scenario = {
-            id,
-            slug: slugify(input.name),
-            name: input.name,
-            scenario: input.scenario,
-            profile: input.profile,
-            notes: input.notes,
-            status: "pending",
-            createdAt: new Date().toISOString(),
-        };
-        scenarios.push(scenario);
-        this.saveScenarios(scenarios);
-        return scenario;
+        return loadScenarios(this.cwd);
     }
-    getScenario(idOrSlug) {
-        return this.listScenarios().find((s) => s.id === Number(idOrSlug) || s.slug === idOrSlug);
-    }
-    updateScenario(id, patch) {
-        const scenarios = this.listScenarios();
-        const idx = scenarios.findIndex((s) => s.id === id);
-        if (idx === -1)
-            throw new Error(`Scenario ${id} not found`);
-        scenarios[idx] = { ...scenarios[idx], ...patch };
-        this.saveScenarios(scenarios);
+    getScenario(slug) {
+        return this.listScenarios().find((s) => s.slug === slug);
     }
     // ---- cached deterministic scripts ----
     scriptPath(slug) {
@@ -78,12 +50,14 @@ export class Store {
         return JSON.parse(fs.readFileSync(file, "utf8"));
     }
     saveSteps(slug, steps) {
-        fs.writeFileSync(this.scriptPath(slug), JSON.stringify(steps, null, 2) + "\n");
+        const file = this.scriptPath(slug);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify(steps, null, 2) + "\n");
     }
     // ---- runs ----
     newRunDir(slug) {
         const stamp = new Date().toISOString().replace(/[:.]/g, "-");
-        const dir = path.join(this.root, "runs", `${stamp}-${slug}`);
+        const dir = path.join(this.root, "runs", `${stamp}-${slugToToken(slug)}`);
         fs.mkdirSync(dir, { recursive: true });
         return dir;
     }
@@ -107,13 +81,35 @@ export class Store {
         return map;
     }
 }
-export function slugify(name) {
-    return name
-        .toLowerCase()
-        .normalize("NFD")
-        .replace(/[̀-ͯ]/g, "")
-        .replace(/[^a-z0-9]+/g, "-")
-        .replace(/^-|-$/g, "")
-        .slice(0, 60);
-}
+// The example sits inside a fenced block so it loads as ZERO scenarios — it
+// documents the format without polluting the suite (or the `--check` gate).
+const EXAMPLE_SPEC = `---
+feature: Example
+---
+
+# How to write a scout spec
+
+One file per feature/component. File-level frontmatter sets defaults
+(\`feature\`, \`profile\`, \`tags\`). Each \`##\` heading is one scenario; optional
+\`profile\`/\`notes\`/\`tags\` override lines may follow a heading before the prose.
+Write the flow + expected behavior in plain language — no selectors, no code.
+
+Copy the block below into a new \`*.scout.md\` file (outside the fence) to start:
+
+\`\`\`markdown
+---
+feature: Paywall
+profile: anon
+tags: [monetization]
+---
+
+## Free user hits paywall on ep 3
+Open ep 3 of series X without login; paywall appears with a signup CTA.
+
+## Subscriber bypasses paywall
+profile: qa
+
+Logged-in subscriber opens ep 3; plays with no paywall.
+\`\`\`
+`;
 //# sourceMappingURL=store.js.map