@pcamarajr/scout 0.1.0

package/dist/mcp/server.d.ts

@@ -0,0 +1,8 @@
+/**
+ * MCP interface so coding agents (Claude Code local or cloud sessions) can
+ * create scenarios and run verifications as tool calls. Mirrors the CLI.
+ *
+ * Register in the target project's .mcp.json:
+ *   { "mcpServers": { "scout": { "command": "npx", "args": ["scout", "mcp"] } } }
+ */
+export declare function startMcpServer(): Promise<void>;

package/dist/mcp/server.js

@@ -0,0 +1,106 @@
+import fs from "node:fs";
+import path from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { loadConfig } from "../config.js";
+import { runScenario } from "../engine.js";
+import { renderSummary } from "../report.js";
+import { Store } from "../store.js";
+/**
+ * MCP interface so coding agents (Claude Code local or cloud sessions) can
+ * create scenarios and run verifications as tool calls. Mirrors the CLI.
+ *
+ * Register in the target project's .mcp.json:
+ *   { "mcpServers": { "scout": { "command": "npx", "args": ["scout", "mcp"] } } }
+ */
+export async function startMcpServer() {
+    const server = new McpServer({ name: "scout", version: "0.1.0" });
+    const store = new Store();
+    server.registerTool("scout_list_scenarios", {
+        description: "Lista os cenários de QA do projeto com status e se há script cacheado.",
+        inputSchema: {},
+    }, async () => {
+        const scenarios = store.listScenarios().map((s) => ({
+            ...s,
+            hasCachedScript: Boolean(store.loadSteps(s.slug)),
+        }));
+        return { content: [{ type: "text", text: JSON.stringify(scenarios, null, 2) }] };
+    });
+    server.registerTool("scout_create_scenario", {
+        description: "Cria um cenário de verificação em linguagem natural. Descreva o FLUXO (passos do usuário) e o COMPORTAMENTO ESPERADO (o que deve/não deve acontecer). Não escreva seletores nem código — o runner descobre sozinho no browser.",
+        inputSchema: {
+            name: z.string().describe("Nome curto do cenário"),
+            scenario: z.string().describe("Fluxo + expectativas em linguagem natural"),
+            profile: z.string().optional().describe("Profile de auth de scout.config.json (omitir = anônimo)"),
+            notes: z.string().optional().describe("Contexto extra para o runner"),
+        },
+    }, async ({ name, scenario, profile, notes }) => {
+        store.init();
+        const created = store.addScenario({ name, scenario, profile, notes });
+        return {
+            content: [
+                { type: "text", text: `Cenário #${created.id} (${created.slug}) criado. Rode com scout_run.` },
+            ],
+        };
+    });
+    server.registerTool("scout_run", {
+        description: "Roda a verificação de um cenário (ou todos). Usa o script determinístico cacheado quando existe; cai pro agente AI no primeiro run ou quando o script quebra (self-healing). Retorna veredito + evidências.",
+        inputSchema: {
+            scenario: z.string().optional().describe("id ou slug; omitir = todos"),
+            forceAi: z.boolean().optional().describe("Ignora o cache e re-grava o script via AI"),
+        },
+    }, async ({ scenario, forceAi }) => {
+        const config = loadConfig();
+        const all = store.listScenarios();
+        const targets = scenario
+            ? all.filter((s) => s.id === Number(scenario) || s.slug === scenario)
+            : all;
+        if (!targets.length) {
+            return { content: [{ type: "text", text: `Nenhum cenário encontrado para "${scenario}".` }], isError: true };
+        }
+        const results = [];
+        for (const s of targets) {
+            try {
+                const r = await runScenario(store, s, config, { forceAi });
+                results.push({
+                    scenario: s.name,
+                    verdict: r.verdict,
+                    mode: r.mode,
+                    healed: r.healed ?? false,
+                    reason: r.reason,
+                    runDir: r.runDir,
+                    screenshots: r.screenshots,
+                    trace: r.trace,
+                });
+            }
+            catch (error) {
+                results.push({
+                    scenario: s.name,
+                    verdict: "blocked",
+                    reason: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
+    });
+    server.registerTool("scout_report", {
+        description: "Resumo markdown da suíte (embedável em corpo de PR) — status por cenário + falhas.",
+        inputSchema: {},
+    }, async () => ({
+        content: [{ type: "text", text: renderSummary(store.listScenarios(), store.latestRuns()) }],
+    }));
+    server.registerTool("scout_get_run_report", {
+        description: "Lê o report.md de um run específico (passe o runDir retornado por scout_run).",
+        inputSchema: { runDir: z.string() },
+    }, async ({ runDir }) => {
+        const file = path.join(runDir, "report.md");
+        if (!fs.existsSync(file)) {
+            return { content: [{ type: "text", text: `Sem report em ${runDir}` }], isError: true };
+        }
+        return { content: [{ type: "text", text: fs.readFileSync(file, "utf8") }] };
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+//# sourceMappingURL=server.js.map

package/dist/mcp/server.js.map

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

package/dist/report.d.ts

@@ -0,0 +1,5 @@
+import type { RunResult, Scenario, Step } from "./types.js";
+/** Per-run report saved at .scout/runs/<id>/report.md */
+export declare function renderRunReport(result: RunResult, scenario: Scenario, steps?: Step[]): string;
+/** Suite summary — PR-embeddable (the \`scout report\` output). */
+export declare function renderSummary(scenarios: Scenario[], latest: Map<string, RunResult>): string;

package/dist/report.js

@@ -0,0 +1,68 @@
+import path from "node:path";
+import { describeStep } from "./runner/script-runner.js";
+const ICON = {
+    verified: "✅",
+    failed: "❌",
+    partial: "⚠️",
+    blocked: "🚫",
+    pending: "⏳",
+};
+/** Per-run report saved at .scout/runs/<id>/report.md */
+export function renderRunReport(result, scenario, steps) {
+    const lines = [
+        `# ${ICON[result.verdict]} ${scenario.name}`,
+        ``,
+        `| | |`,
+        `|---|---|`,
+        `| Verdict | **${result.verdict}** |`,
+        `| Mode | ${result.mode === "replay" ? "deterministic replay" : "AI-driven"}${result.healed ? " (healed)" : ""} |`,
+        `| Profile | ${scenario.profile ?? "anonymous"} |`,
+        `| Duration | ${(result.durationMs / 1000).toFixed(1)}s |`,
+        `| Started | ${result.startedAt} |`,
+        ``,
+        `**Scenario:** ${scenario.scenario}`,
+        ``,
+        `**Resultado:** ${result.reason}`,
+    ];
+    if (steps?.length) {
+        lines.push(``, `## Recorded script (${steps.length} steps)`, ``);
+        steps.forEach((s, i) => lines.push(`${i + 1}. ${describeStep(s)}`));
+    }
+    if (result.screenshots.length) {
+        lines.push(``, `## Evidence`, ``);
+        for (const shot of result.screenshots) {
+            const name = path.basename(shot);
+            lines.push(`![${name}](./${name})`);
+        }
+    }
+    if (result.trace) {
+        lines.push(``, `## Trace`, ``, `\`npx playwright show-trace ${result.trace}\` — screenshots, DOM snapshots, network and console for the entire session.`);
+    }
+    return lines.join("\n") + "\n";
+}
+/** Suite summary — PR-embeddable (the \`scout report\` output). */
+export function renderSummary(scenarios, latest) {
+    const lines = [
+        `## 🔭 Scout — browser verification`,
+        ``,
+        `| # | Scenario | Profile | Status | Mode | Last run |`,
+        `|---|---------|---------|--------|------|------------|`,
+    ];
+    for (const s of scenarios) {
+        const run = latest.get(s.slug);
+        const mode = run ? (run.mode === "replay" ? "replay" : run.healed ? "AI (healed)" : "AI") : "—";
+        lines.push(`| ${s.id} | ${s.name} | ${s.profile ?? "anonymous"} | ${ICON[s.status]} ${s.status} | ${mode} | ${s.lastRun ? s.lastRun.slice(0, 16).replace("T", " ") : "never"} |`);
+    }
+    const failing = scenarios.filter((s) => s.status === "failed" || s.status === "blocked");
+    if (failing.length) {
+        lines.push(``, `### Failures`, ``);
+        for (const s of failing) {
+            const run = latest.get(s.slug);
+            lines.push(`- **${s.name}**: ${run?.reason ?? "no run recorded"}`);
+        }
+    }
+    const verified = scenarios.filter((s) => s.status === "verified").length;
+    lines.push(``, `**${verified}/${scenarios.length} verified.**`);
+    return lines.join("\n") + "\n";
+}
+//# sourceMappingURL=report.js.map

package/dist/report.js.map

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

package/dist/runner/ai-runner.d.ts

@@ -0,0 +1,15 @@
+import type { ScoutConfig } from "../config.js";
+import type { Scenario, Step, Verdict } from "../types.js";
+import { BrowserSession } from "./browser.js";
+export interface AiRunOutcome {
+    verdict: Verdict;
+    reason: string;
+    steps: Step[];
+    transcript: string[];
+}
+/**
+ * AI-driven run: a Claude agent navigates the real browser to verify the
+ * scenario. Every successful action is recorded as a deterministic Step so
+ * subsequent runs can replay without the LLM.
+ */
+export declare function runWithAgent(session: BrowserSession, scenario: Scenario, config: ScoutConfig): Promise<AiRunOutcome>;

package/dist/runner/ai-runner.js

@@ -0,0 +1,214 @@
+import { createSdkMcpServer, query, tool } from "@anthropic-ai/claude-agent-sdk";
+import { z } from "zod";
+import { resolveEnvValue } from "./browser.js";
+/**
+ * AI-driven run: a Claude agent navigates the real browser to verify the
+ * scenario. Every successful action is recorded as a deterministic Step so
+ * subsequent runs can replay without the LLM.
+ */
+export async function runWithAgent(session, scenario, config) {
+    const steps = [];
+    const transcript = [];
+    let verdict;
+    const record = (step) => steps.push(step);
+    const afterAction = async () => {
+        const snap = await session.snapshot();
+        return session.formatSnapshot(snap);
+    };
+    const ok = (text) => ({ content: [{ type: "text", text }] });
+    const fail = (error) => ({
+        content: [{ type: "text", text: `ERRO: ${error instanceof Error ? error.message : String(error)}` }],
+        isError: true,
+    });
+    const browserServer = createSdkMcpServer({
+        name: "browser",
+        version: "1.0.0",
+        tools: [
+            tool("browser_navigate", "Navega para uma URL (absoluta ou relativa ao baseUrl do app).", { url: z.string().describe("Ex: /login ou https://...") }, async ({ url }) => {
+                try {
+                    await session.navigate(url);
+                    // Grava relativo quando a URL está sob o baseUrl — o script
+                    // precisa sobreviver a SCOUT_BASE_URL apontando pra outro ambiente.
+                    const base = config.baseUrl.replace(/\/+$/, "");
+                    const recorded = url.startsWith(base) ? url.slice(base.length) || "/" : url;
+                    record({ kind: "navigate", url: recorded });
+                    return ok(await afterAction());
+                }
+                catch (e) {
+                    return fail(e);
+                }
+            }),
+            tool("browser_snapshot", "Retorna o estado atual da página: URL, título, elementos interativos numerados [ref] e texto visível. Use sempre que precisar decidir a próxima ação.", {}, async () => {
+                try {
+                    return ok(await afterAction());
+                }
+                catch (e) {
+                    return fail(e);
+                }
+            }),
+            tool("browser_click", "Clica no elemento identificado pelo [ref] do último snapshot.", { ref: z.number().int().describe("Ref numérico do snapshot") }, async ({ ref }) => {
+                try {
+                    const target = await session.click(ref);
+                    record({ kind: "click", target });
+                    return ok(`Cliquei em ${target.description}.\n\n${await afterAction()}`);
+                }
+                catch (e) {
+                    return fail(e);
+                }
+            }),
+            tool("browser_fill", "Preenche um campo. Para credenciais/segredos use placeholder $ENV:VAR_NAME — o valor real vem do ambiente e nunca passa por você.", {
+                ref: z.number().int(),
+                value: z.string().describe("Texto literal ou $ENV:VAR_NAME"),
+            }, async ({ ref, value }) => {
+                try {
+                    const target = await session.fill(ref, resolveEnvValue(value));
+                    record({ kind: "fill", target, value });
+                    return ok(`Preenchi ${target.description}.`);
+                }
+                catch (e) {
+                    return fail(e);
+                }
+            }),
+            tool("browser_select", "Seleciona uma opção em um <select> pelo value ou label.", { ref: z.number().int(), value: z.string() }, async ({ ref, value }) => {
+                try {
+                    const target = await session.select(ref, resolveEnvValue(value));
+                    record({ kind: "select", target, value });
+                    return ok(`Selecionei "${value}" em ${target.description}.\n\n${await afterAction()}`);
+                }
+                catch (e) {
+                    return fail(e);
+                }
+            }),
+            tool("browser_press", "Pressiona uma tecla (Enter, Escape, Tab, ArrowDown...).", { key: z.string() }, async ({ key }) => {
+                try {
+                    await session.press(key);
+                    record({ kind: "press", key });
+                    return ok(await afterAction());
+                }
+                catch (e) {
+                    return fail(e);
+                }
+            }),
+            tool("browser_wait_for", "Espera texto aparecer na página OU a URL conter um trecho. Use após ações que disparam carregamento.", {
+                text: z.string().optional().describe("Texto que deve ficar visível"),
+                urlContains: z.string().optional().describe("Trecho esperado na URL"),
+            }, async ({ text, urlContains }) => {
+                try {
+                    if (text) {
+                        await session.waitForText(text);
+                        record({ kind: "waitForText", text });
+                    }
+                    if (urlContains) {
+                        await session.waitForUrl(urlContains);
+                        record({ kind: "waitForUrl", pattern: urlContains });
+                    }
+                    return ok(await afterAction());
+                }
+                catch (e) {
+                    return fail(e);
+                }
+            }),
+            tool("browser_assert", "Registra uma verificação do comportamento esperado. Use para CADA expectativa do cenário — essas asserções viram o teste determinístico.", {
+                visibleText: z.string().optional().describe("Texto que DEVE estar visível"),
+                notVisibleText: z.string().optional().describe("Texto que NÃO deve estar visível"),
+                urlContains: z.string().optional().describe("Trecho que a URL deve conter"),
+            }, async ({ visibleText, notVisibleText, urlContains }) => {
+                try {
+                    if (visibleText) {
+                        await session.assertVisible(visibleText);
+                        record({ kind: "assertVisible", text: visibleText });
+                    }
+                    if (notVisibleText) {
+                        await session.assertNotVisible(notVisibleText);
+                        record({ kind: "assertNotVisible", text: notVisibleText });
+                    }
+                    if (urlContains) {
+                        await session.assertUrl(urlContains);
+                        record({ kind: "assertUrl", pattern: urlContains });
+                    }
+                    return ok("Asserção passou.");
+                }
+                catch (e) {
+                    return fail(e);
+                }
+            }),
+            tool("browser_screenshot", "Captura screenshot como evidência. Use em momentos-chave (estado final, paywall, erro encontrado).", { label: z.string().describe("Rótulo curto, ex: 'paywall-exibido'") }, async ({ label }) => {
+                try {
+                    await session.screenshot(label);
+                    record({ kind: "screenshot", label });
+                    return ok(`Screenshot "${label}" salvo.`);
+                }
+                catch (e) {
+                    return fail(e);
+                }
+            }),
+            tool("scout_verdict", "OBRIGATÓRIO ao final: registra o veredito da verificação. Após chamar, encerre.", {
+                verdict: z.enum(["verified", "failed", "partial", "blocked"]),
+                reason: z.string().describe("Justificativa objetiva, citando o que foi observado"),
+            }, async (args) => {
+                verdict = args;
+                return ok("Veredito registrado. Encerre agora.");
+            }),
+        ],
+    });
+    const profileInfo = scenario.profile
+        ? `Sessão autenticada com o profile "${scenario.profile}"${config.profiles[scenario.profile]?.description ? ` (${config.profiles[scenario.profile].description})` : ""}. Você JÁ está logado — não faça login de novo a menos que o cenário peça.`
+        : "Sessão anônima (logged-out).";
+    const envVars = scenario.profile ? (config.profiles[scenario.profile]?.env ?? []) : [];
+    const envInfo = envVars.length
+        ? `Env vars disponíveis para browser_fill via placeholder: ${envVars.map((v) => `$ENV:${v}`).join(", ")}.`
+        : "";
+    const systemPrompt = `Você é Scout, um agente de QA que verifica cenários em um browser real.
+
+App alvo: ${config.baseUrl}
+${profileInfo}
+${envInfo}
+
+Método de trabalho:
+1. Comece com browser_navigate para a página inicial do fluxo (ou browser_snapshot se já estiver lá).
+2. Execute o fluxo descrito no cenário, passo a passo, sempre lendo o snapshot antes de agir.
+3. Para CADA expectativa do cenário, use browser_assert — as asserções gravadas viram o teste determinístico que rodará em CI sem você.
+4. Capture browser_screenshot como evidência nos momentos-chave.
+5. Termine SEMPRE com scout_verdict:
+   - verified: todo o comportamento esperado foi confirmado por asserções
+   - failed: comportamento esperado está quebrado (descreva exatamente o quê)
+   - partial: parte funciona, parte não, ou não foi possível verificar tudo
+   - blocked: não conseguiu nem chegar ao fluxo (app fora do ar, login quebrado, etc.)
+
+Regras:
+- Aja como um usuário real: um passo de cada vez, espere carregamentos com browser_wait_for.
+- Se um elemento não está no snapshot, tire novo snapshot ou role o fluxo de outro jeito — não invente refs.
+- Nunca digite segredos literais: use $ENV:VAR_NAME.
+- Seja econômico: não explore além do cenário.`;
+    const result = query({
+        prompt: `Verifique este cenário de QA:\n\n## ${scenario.name}\n\n${scenario.scenario}${scenario.notes ? `\n\nNotas: ${scenario.notes}` : ""}`,
+        options: {
+            model: config.model,
+            maxTurns: config.maxTurns,
+            systemPrompt,
+            mcpServers: { browser: browserServer },
+            allowedTools: ["mcp__browser__*"],
+            tools: [],
+            settingSources: [],
+            permissionMode: "bypassPermissions",
+        },
+    });
+    for await (const message of result) {
+        if (message.type === "assistant") {
+            for (const block of message.message.content) {
+                if (block.type === "text" && block.text.trim())
+                    transcript.push(block.text.trim());
+            }
+        }
+        if (message.type === "result")
+            break;
+    }
+    if (!verdict) {
+        verdict = {
+            verdict: "blocked",
+            reason: "Agente encerrou sem registrar veredito (scout_verdict não foi chamado).",
+        };
+    }
+    return { ...verdict, steps, transcript };
+}
+//# sourceMappingURL=ai-runner.js.map

package/dist/runner/ai-runner.js.map

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

package/dist/runner/browser.d.ts

@@ -0,0 +1,68 @@
+import { type Page } from "playwright";
+import type { Step, Target } from "../types.js";
+export interface ElementInfo {
+    ref: number;
+    role: string;
+    name: string;
+    css: string;
+    tag: string;
+    value?: string;
+    href?: string;
+}
+export interface PageSnapshot {
+    url: string;
+    title: string;
+    text: string;
+    elements: ElementInfo[];
+}
+export interface LaunchOptions {
+    baseUrl: string;
+    headless: boolean;
+    storageState?: string;
+    locale?: string;
+    runDir: string;
+}
+/**
+ * Thin Playwright wrapper shared by the AI runner and the replay runner.
+ * Owns ref→element resolution, tracing and screenshots.
+ */
+export declare class BrowserSession {
+    private browser;
+    private context;
+    readonly page: Page;
+    private opts;
+    private refs;
+    private screenshotCount;
+    readonly screenshots: string[];
+    private constructor();
+    static launch(opts: LaunchOptions): Promise<BrowserSession>;
+    resolveUrl(url: string): string;
+    navigate(url: string): Promise<void>;
+    /**
+     * Builds a numbered map of visible interactive elements (role + accessible
+     * name + CSS path) plus a text excerpt. Refs are valid until the next snapshot.
+     */
+    snapshot(): Promise<PageSnapshot>;
+    formatSnapshot(snap: PageSnapshot): string;
+    /**
+     * Resolves a snapshot ref to a locator AND the durable Target recorded for
+     * replay: role+name when unique on the page, CSS path otherwise.
+     */
+    private resolveRef;
+    click(ref: number): Promise<Target>;
+    fill(ref: number, value: string): Promise<Target>;
+    select(ref: number, value: string): Promise<Target>;
+    press(key: string): Promise<void>;
+    waitForText(text: string): Promise<void>;
+    waitForUrl(pattern: string): Promise<void>;
+    assertVisible(text: string): Promise<void>;
+    assertNotVisible(text: string): Promise<void>;
+    assertUrl(pattern: string): Promise<void>;
+    screenshot(label: string): Promise<string>;
+    /** Replays one recorded step (used by the deterministic runner). */
+    executeStep(step: Step): Promise<void>;
+    private targetLocator;
+    close(): Promise<string | undefined>;
+}
+/** Replaces $ENV:VAR_NAME placeholders so secrets never live in committed scripts. */
+export declare function resolveEnvValue(value: string): string;