@davidrydberg/proofy 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Rydberg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,65 @@
-# Temporary Holding Version
+# proofy
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`proofy` gives your app end-to-end tests you can trust, written by your coding agent and approved by you.
+You describe what to test in plain words.
+Your agent follows the instructions proofy puts in your repo to write numbered requirements, a Playwright test and fakes for outside services.
+You approve them, and every `proofy run` checks the app in a sealed Docker sandbox, with no AI, and reports per requirement what was asked, what happened and the evidence, with screenshots.
+
+The sandbox has no way out.
+Every outside call goes to a fake the agent wrote from the provider's docs, gets recorded, or is refused and listed in the report.
+
+## Install
+
+proofy is not on npm yet. Install it from source:
+
+```sh
+git clone https://github.com/davidrydberg/proofy && cd proofy && npm ci && npm run build && npm link
+```
+
+Once it is published, `npm i -g @davidrydberg/proofy` will work.
+
+## Requirements
+
+- Node 24 or newer
+- Docker on macOS or Linux (Docker Desktop, OrbStack or Docker Engine)
+- An app that starts with `docker compose`; your agent can draft the compose file
+- The [GitHub CLI](https://cli.github.com), only to test pull requests or post reports on them
+
+## Usage
+
+```sh
+proofy init     # adds e2e/ with agent instructions, templates and a config filled from your repo
+```
+
+Then tell your agent: "set up proofy", and after that what to test: "add a proofy test: a guest can buy a product and gets a confirmation email".
+The agent interviews you, writes `e2e/specs/<flow>.md` and the test, and runs it until three runs agree.
+
+```sh
+proofy                      # setup, every flow's state and the next step; safe for a session-start hook
+proofy approve guest-checkout   # you, after reading the requirements and the agent's notes
+proofy run --all            # every approved flow in a fresh sealed sandbox
+proofy run --all --pr 42 --post   # a pull request's code, report posted on the PR
+```
+
+```
+PASS  every requirement of every approved flow held
+run 20261020-091512  e2e/out/20261020-091512
+
+guest-checkout  passed
+  ✓ R1   After placing the order, the guest sees a confirmation page showing the stored order's number.
+  ✓ R2   The order is stored with status "processing", payment method cash on delivery, ...
+  ✓ R3   Within 30 seconds the guest receives exactly one email, and it shows the order number.
+  ✓ R4   Stock for the coffee goes down by exactly one.
+  ✓ R5   No email that names the guest or the order number goes to anyone but the guest or the shop ...
+```
+
+Exit codes: 0 pass, 1 an approved flow failed, 2 usage or config, 3 the sandbox failed, 4 not approved.
+`examples/woocommerce` is a complete shop with two flows, and [pull request 1](https://github.com/davidrydberg/proofy/pull/1) shows a report posted with `--post`.
+`prd.md` has the full design.
+
+The agent instructions say only you run `proofy approve`.
+That is a rule your agent follows, not a lock.
+
+## License
+
+MIT

package/dist/args.d.ts

@@ -0,0 +1,10 @@
+export interface FlagSpec {
+    values: string[];
+    booleans: string[];
+}
+export interface ParsedArgs {
+    positionals: string[];
+    values: Map<string, string>;
+    booleans: Set<string>;
+}
+export declare function parseArgs(args: string[], spec: FlagSpec, command: string): ParsedArgs;

package/dist/args.js

@@ -0,0 +1,36 @@
+import { CliError } from "./errors.js";
+export function parseArgs(args, spec, command) {
+    const parsed = { positionals: [], values: new Map(), booleans: new Set() };
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i] ?? "";
+        if (!arg.startsWith("--")) {
+            parsed.positionals.push(arg);
+            continue;
+        }
+        const [name = "", inline] = splitFlag(arg.slice(2));
+        if (spec.booleans.includes(name)) {
+            if (inline !== undefined) {
+                throw invalidFlag(`--${name} takes no value`, command);
+            }
+            parsed.booleans.add(name);
+        }
+        else if (spec.values.includes(name)) {
+            const value = inline ?? args[++i];
+            if (value === undefined || value === "") {
+                throw invalidFlag(`--${name} needs a value`, command);
+            }
+            parsed.values.set(name, value);
+        }
+        else {
+            throw invalidFlag(`Unknown flag --${name}`, command);
+        }
+    }
+    return parsed;
+}
+function splitFlag(flag) {
+    const eq = flag.indexOf("=");
+    return eq === -1 ? [flag, undefined] : [flag.slice(0, eq), flag.slice(eq + 1)];
+}
+function invalidFlag(message, command) {
+    return new CliError(message, "VALIDATION_ERROR", [`Run \`proofy ${command} --help\` to see its flags`]);
+}

package/dist/bin/proofy.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/proofy.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runCli } from "../cli.js";
+import { spawnProc } from "../sandbox/docker.js";
+process.exitCode = await runCli(process.argv.slice(2), { cwd: process.cwd(), env: process.env, proc: spawnProc, now: () => new Date(), log: (line) => process.stderr.write(`proofy: ${line}\n`) }, { write: (text) => process.stdout.write(text), isTTY: process.stdout.isTTY === true, columns: process.stdout.columns });

package/dist/cli.d.ts

@@ -0,0 +1,9 @@
+import type { Deps } from "./deps.js";
+export declare const DESCRIPTION = "Sealed end-to-end tests that your coding agent writes and you approve";
+export interface Io {
+    write: (text: string) => void;
+    isTTY: boolean;
+    columns?: number | undefined;
+}
+export declare function runCli(argv: string[], deps: Deps, io: Io): Promise<number>;
+export declare function version(): string;

package/dist/cli.js

@@ -0,0 +1,140 @@
+import { readFileSync } from "node:fs";
+import { homeCommand } from "./commands/home.js";
+import { APPROVE_HELP, approveCommand } from "./commands/approve.js";
+import { DEV_HELP, devCommand } from "./commands/dev.js";
+import { INIT_HELP, initCommand } from "./commands/init.js";
+import { REPORT_HELP, reportCommand } from "./commands/report.js";
+import { RUN_HELP, runCommand } from "./commands/run.js";
+import { CliError, exitCodeFor } from "./errors.js";
+import { renderErrorHuman } from "./human.js";
+import { renderError, renderJson, renderResult } from "./output.js";
+import { painter, resolveStyle } from "./style.js";
+export const DESCRIPTION = "Sealed end-to-end tests that your coding agent writes and you approve";
+const FORMAT_FLAGS = { "--toon": "toon", "--json": "json", "--pretty": "pretty" };
+const TOP_HELP = `usage: proofy [command] [args] [flags]
+description: ${DESCRIPTION}
+commands[6]:
+  (none)  Setup progress, flows and their states, last run, next step. Reads files only, safe for a session-start hook
+  init [--no-agents-md]  Write e2e/ with agent instructions, templates and a config filled from what it finds
+  run [flow ...] [--all] [--pr <n>] [--post] [--keep]  One sealed run with a report per requirement
+  dev up|test|down  A sandbox that stays up while tests are written
+  approve <flow>  For the human: trust a flow after 3 identical runs
+  report [run]  Show a past run
+flags[5]:
+  --help  Show help, also after a command
+  -v, --version  Print the version
+  --toon  TOON output (default when not on a terminal)
+  --pretty  Human view (default on a terminal)
+  --json  Full data as JSON
+exit_codes[5]:
+  0  Done; in a run, every requirement of every approved flow held
+  1  A requirement of an approved flow did not hold: a finding about the app
+  2  Usage error, invalid config or not set up
+  3  Environment failure: Docker, the sandbox, a time limit. Says nothing about the app
+  4  Not trusted: the flows asked for are not approved or out of date
+how_it_works:
+  You describe flows in plain words. Your agent follows e2e/AGENTS.md to write requirements, tests and fakes.
+  You approve them, and every run checks the app in a sealed Docker sandbox with no AI.
+requires: Node 24+, Docker on macOS or Linux, git; gh for --pr and --post
+examples:
+  proofy init
+  proofy
+  proofy dev up
+  proofy dev test guest-checkout
+  proofy approve guest-checkout
+  proofy run --all
+`;
+// One help text per command. The human view is derived from it, so the two never disagree.
+function humanHelp(text, style) {
+    const p = painter(style);
+    const out = [];
+    for (const line of text.trimEnd().split("\n")) {
+        const header = /^([a-z_]+)(\[\d+\])?:\s*(.*)$/.exec(line);
+        if (header) {
+            const [, name = "", , rest = ""] = header;
+            if (name === "usage")
+                out.push(`${p.bold("USAGE")}\n  ${rest}`);
+            else if (name === "description")
+                out.unshift(`${p.bold("proofy")} - ${rest}`);
+            else
+                out.push(`\n${p.bold(name.replace(/_/g, " ").toUpperCase())}${rest ? `\n  ${rest}` : ""}`);
+            continue;
+        }
+        const row = /^ {2}(\S.*?) {2,}(.*)$/.exec(line);
+        out.push(row ? `  ${p.cyan(row[1] ?? "")}  ${row[2] ?? ""}` : line);
+    }
+    return out.join("\n");
+}
+const COMMANDS = {
+    init: { run: initCommand, help: INIT_HELP },
+    run: { run: runCommand, help: RUN_HELP },
+    dev: { run: devCommand, help: DEV_HELP },
+    approve: { run: approveCommand, help: APPROVE_HELP },
+    report: { run: reportCommand, help: REPORT_HELP },
+};
+export async function runCli(argv, deps, io) {
+    const style = resolveStyle(deps.env, io.isTTY, io.columns);
+    let format = io.isTTY ? "pretty" : "toon";
+    try {
+        const formats = [...new Set(argv.filter((arg) => arg in FORMAT_FLAGS))];
+        if (formats.length > 1) {
+            throw new CliError("Use only one of --pretty, --toon and --json", "VALIDATION_ERROR", ["Run `proofy --help`"]);
+        }
+        const chosen = formats[0];
+        if (chosen !== undefined) {
+            format = FORMAT_FLAGS[chosen] ?? format;
+        }
+        const [command, ...args] = argv.filter((arg) => !(arg in FORMAT_FLAGS));
+        const pretty = format === "pretty";
+        if (command === undefined) {
+            return emit(await homeCommand(deps), format, style, io);
+        }
+        if (command === "--help" || command === "-h" || command === "help") {
+            io.write(pretty ? `${humanHelp(TOP_HELP, style)}\n` : TOP_HELP);
+            return 0;
+        }
+        if (command === "--version" || command === "-v") {
+            io.write(`${version()}\n`);
+            return 0;
+        }
+        if (command.startsWith("-")) {
+            throw new CliError(`Flags go after the command, got ${command}`, "VALIDATION_ERROR", ["Run `proofy --help`"]);
+        }
+        const entry = COMMANDS[command];
+        if (!entry) {
+            throw new CliError(`Unknown command: ${command}`, "VALIDATION_ERROR", ["Run `proofy --help` to see commands"]);
+        }
+        if (args.includes("--help") || args.includes("-h")) {
+            io.write(pretty ? `${humanHelp(entry.help, style)}\n` : entry.help);
+            return 0;
+        }
+        return emit(await entry.run(args, deps), format, style, io);
+    }
+    catch (error) {
+        const known = error instanceof CliError;
+        const message = error instanceof Error ? error.message : String(error);
+        const code = known ? error.code : "UNEXPECTED";
+        const suggestions = known ? error.suggestions : ["This is a bug in proofy. Run again with the same arguments and report the message"];
+        io.write(`${format === "pretty" ? renderErrorHuman(message, code, suggestions, style) : renderError(message, code, suggestions)}\n`);
+        return exitCodeFor(error);
+    }
+}
+function emit(result, format, style, io) {
+    if (typeof result === "string") {
+        io.write(`${result}\n`);
+    }
+    else if (format === "json") {
+        io.write(`${renderJson(result.json ?? result.data)}\n`);
+    }
+    else if (format === "pretty" && result.pretty) {
+        io.write(`${result.pretty(style)}\n`);
+    }
+    else {
+        io.write(`${renderResult(result)}\n`);
+    }
+    return typeof result === "string" ? 0 : (result.exitCode ?? 0);
+}
+export function version() {
+    const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+    return pkg.version;
+}

package/dist/commands/approve.d.ts

@@ -0,0 +1,4 @@
+import type { Deps } from "../deps.js";
+import type { CommandResult } from "./types.js";
+export declare const APPROVE_HELP = "usage: proofy approve <flow>\ndescription: For the human, never the agent. Records fingerprints of the flow's requirements, test and fakes, after 3 runs with identical results\nexamples:\n  proofy approve guest-checkout\n";
+export declare function approveCommand(args: string[], deps: Deps): Promise<CommandResult>;

package/dist/commands/approve.js

@@ -0,0 +1,48 @@
+import { join } from "node:path";
+import { parseArgs } from "../args.js";
+import { CliError } from "../errors.js";
+import { exists, flowNames } from "../project.js";
+import { writeApprovals } from "../run/approvals.js";
+import { flowStatuses, readReport, recentReports } from "../run/history.js";
+import { loadProject } from "./context.js";
+export const APPROVE_HELP = `usage: proofy approve <flow>
+description: For the human, never the agent. Records fingerprints of the flow's requirements, test and fakes, after 3 runs with identical results
+examples:
+  proofy approve guest-checkout
+`;
+export async function approveCommand(args, deps) {
+    const { positionals } = parseArgs(args, { values: [], booleans: [] }, "approve");
+    const [name] = positionals;
+    if (!name || positionals.length > 1)
+        throw new CliError("Name one flow to approve", "VALIDATION_ERROR", ["Example: proofy approve guest-checkout"]);
+    const project = await loadProject(deps);
+    const { paths, config, approvals } = project;
+    if (!(await flowNames(paths)).includes(name))
+        throw new CliError(`No flow named ${name}`, "VALIDATION_ERROR", ["Run `proofy` to see flows"]);
+    if (!(await exists(join(paths.tests, `${name}.spec.ts`))))
+        throw new CliError(`${name} has no test yet`, "NOT_APPROVED", ["Ask your agent to write it"]);
+    const [status] = await flowStatuses(paths, config, [name], approvals, await recentReports(paths));
+    if (!status)
+        throw new CliError(`No flow named ${name}`, "VALIDATION_ERROR");
+    if (status.state === "approved") {
+        return { data: { flow: name, state: "already approved" }, help: [`Run \`proofy run ${name}\` to check it`] };
+    }
+    if (status.state !== "ready" && !(status.state === "out-of-date" && status.runs.length === 3 && !status.reason)) {
+        throw new CliError(`${name} cannot be approved yet: ${status.reason ?? status.state}`, "NOT_APPROVED", [
+            "Approval needs 3 runs with the current files and identical results per requirement",
+            `Run \`proofy run ${name}\` or \`proofy dev test ${name}\` until then`,
+        ]);
+    }
+    const latest = status.runs[0] ? await readReport(paths, status.runs[0]) : undefined;
+    const flow = latest?.flows.find((candidate) => candidate.name === name);
+    const failing = flow?.requirements.filter((requirement) => requirement.result === "fail" || requirement.result === "not-reached").map((requirement) => requirement.id) ?? [];
+    approvals.flows[name] = { ...status.fingerprint, approvedAt: deps.now().toISOString(), runs: status.runs, requirements: flow?.requirements.length ?? 0 };
+    await writeApprovals(paths, approvals);
+    const help = [`Commit e2e/proofy.lock.json with the flow's files`, `Run \`proofy run --all\` to check every approved flow`];
+    if (failing.length > 0)
+        help.unshift(`${failing.join(", ")} fail on purpose as findings: runs stay red until the app is fixed`);
+    return {
+        data: { flow: name, state: "approved", requirements: flow?.requirements.map((requirement) => `${requirement.id} ${requirement.result}`) ?? [], based_on_runs: status.runs },
+        help,
+    };
+}

package/dist/commands/context.d.ts

@@ -0,0 +1,16 @@
+import { type Config } from "../config.js";
+import type { Deps } from "../deps.js";
+import { type Paths } from "../project.js";
+import { type Approvals } from "../run/approvals.js";
+import type { RunReport } from "../run/results.js";
+export interface Project {
+    root: string;
+    paths: Paths;
+    config: Config;
+    approvals: Approvals;
+    cacheDir: string;
+}
+export declare function loadProject(deps: Deps): Promise<Project>;
+export declare function workingTreeInfo(deps: Deps, root: string): Promise<RunReport["source"]>;
+/** Project name for docker compose: lowercase letters, digits and dashes. */
+export declare function projectName(root: string, suffix: string): string;

package/dist/commands/context.js

@@ -0,0 +1,27 @@
+import { loadConfig } from "../config.js";
+import { CliError } from "../errors.js";
+import { exists, findRoot, pathsFor } from "../project.js";
+import { readApprovals } from "../run/approvals.js";
+import { cacheDirFor } from "../sandbox/sandbox.js";
+export async function loadProject(deps) {
+    const root = await findRoot(deps.cwd);
+    const paths = pathsFor(root);
+    if (!(await exists(paths.config))) {
+        throw new CliError("proofy is not set up in this repository", "NOT_SET_UP", ["Run `proofy init`"]);
+    }
+    const config = await loadConfig(paths.config, "e2e/proofy.json");
+    return { root, paths, config, approvals: await readApprovals(paths), cacheDir: cacheDirFor(deps.env, root) };
+}
+export async function workingTreeInfo(deps, root) {
+    const head = await deps.proc("git", ["-C", root, "rev-parse", "HEAD"]);
+    const status = await deps.proc("git", ["-C", root, "status", "--porcelain", "--untracked-files=no"]);
+    return {
+        ...(head.code === 0 ? { commit: head.stdout.trim() } : {}),
+        ...(status.code === 0 ? { dirty: status.stdout.trim().length > 0 } : {}),
+    };
+}
+/** Project name for docker compose: lowercase letters, digits and dashes. */
+export function projectName(root, suffix) {
+    const base = root.split("/").filter(Boolean).at(-1) ?? "app";
+    return `proofy-${base}-${suffix}`.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-").slice(0, 60);
+}

package/dist/commands/dev.d.ts

@@ -0,0 +1,4 @@
+import type { Deps } from "../deps.js";
+import type { CommandResult } from "./types.js";
+export declare const DEV_HELP = "usage: proofy dev up|test|down\ndescription: A sealed sandbox that stays up while tests are written. Every dev test counts toward the 3 identical runs approval needs\ncommands[3]:\n  up  Start the sandbox and print where to open the app and Mailpit\n  test [flow ...] [-- playwright args]  Run flows in it; with no flows, every flow that has a test\n  down  Stop it and delete its data\nexamples:\n  proofy dev up\n  proofy dev test guest-checkout\n  proofy dev test guest-checkout -- --grep \"declined card\"\n  proofy dev down\n";
+export declare function devCommand(args: string[], deps: Deps): Promise<CommandResult>;

package/dist/commands/dev.js

@@ -0,0 +1,161 @@
+import { readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parseArgs } from "../args.js";
+import { CliError } from "../errors.js";
+import { exists, flowNames } from "../project.js";
+import { finishRun, logOffsets, planFlows, reserveRunId, sandboxOptions, testsInSandbox } from "../run/engine.js";
+import { outDir } from "../run/history.js";
+import { compose, forwardedPorts, installImages, prepare, saveLogs, start, stop } from "../sandbox/sandbox.js";
+import { loadProject, projectName, workingTreeInfo } from "./context.js";
+import { runResult } from "./run.js";
+export const DEV_HELP = `usage: proofy dev up|test|down
+description: A sealed sandbox that stays up while tests are written. Every dev test counts toward the 3 identical runs approval needs
+commands[3]:
+  up  Start the sandbox and print where to open the app and Mailpit
+  test [flow ...] [-- playwright args]  Run flows in it; with no flows, every flow that has a test
+  down  Stop it and delete its data
+examples:
+  proofy dev up
+  proofy dev test guest-checkout
+  proofy dev test guest-checkout -- --grep "declined card"
+  proofy dev down
+`;
+export async function devCommand(args, deps) {
+    const split = args.indexOf("--");
+    const own = split === -1 ? args : args.slice(0, split);
+    const extra = split === -1 ? [] : args.slice(split + 1);
+    const [sub, ...rest] = own;
+    const project = await loadProject(deps);
+    switch (sub) {
+        case "up":
+            parseArgs(rest, { values: [], booleans: [] }, "dev");
+            return devUp(deps, project);
+        case "test":
+            return devTest(deps, project, parseArgs(rest, { values: [], booleans: [] }, "dev").positionals, extra);
+        case "down":
+            parseArgs(rest, { values: [], booleans: [] }, "dev");
+            return devDown(deps, project);
+        default:
+            throw new CliError(sub ? `Unknown dev command: ${sub}` : "dev needs up, test or down", "VALIDATION_ERROR", ["Run `proofy dev --help`"]);
+    }
+}
+function stateFile(project) {
+    return join(outDir(project.paths), "dev.json");
+}
+async function readState(project) {
+    try {
+        return JSON.parse(await readFile(stateFile(project), "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+async function running(deps, state) {
+    const result = await deps.proc("docker", [...compose(state), "ps", "--status", "running", "-q"]);
+    return result.code === 0 && result.stdout.trim().length > 0;
+}
+function context(deps, project, sourceInfo) {
+    return {
+        proc: deps.proc,
+        env: deps.env,
+        now: deps.now,
+        log: deps.log,
+        base: project.paths,
+        source: project.paths,
+        config: project.config,
+        approvals: project.approvals,
+        cacheDir: project.cacheDir,
+        sourceInfo,
+    };
+}
+async function devUp(deps, project) {
+    const existing = await readState(project);
+    if (existing && (await running(deps, existing))) {
+        return upResult(existing, true);
+    }
+    const ctx = context(deps, project, {});
+    const options = sandboxOptions(ctx, "dev", projectName(project.root, "dev"), outDir(project.paths));
+    let sandbox = await prepare(deps.proc, options);
+    try {
+        await installImages(deps.proc, options, sandbox);
+        sandbox = await start(deps.proc, options, sandbox);
+    }
+    catch (error) {
+        await saveLogs(deps.proc, sandbox, outDir(project.paths));
+        await stop(deps.proc, sandbox);
+        throw error;
+    }
+    const state = { ...sandbox, startedAt: deps.now().toISOString(), urls: await forwardedPorts(deps.proc, sandbox) };
+    await writeFile(stateFile(project), `${JSON.stringify(state, null, 2)}\n`);
+    return upResult(state, false);
+}
+function upResult(state, already) {
+    const help = [
+        "Run `proofy dev test <flow>` to run a flow in it; three identical runs make it ready to approve",
+        "Run `proofy dev down` when done",
+    ];
+    const data = { sandbox: state.project, status: already ? "already running" : "started", app: state.urls.app ?? "not forwarded", mailpit: state.urls.mail ?? "not forwarded" };
+    if (state.notes.length > 0)
+        data.notes = state.notes;
+    return {
+        data,
+        help,
+        pretty: () => [
+            `dev sandbox ${state.project} ${already ? "already running" : "started"}, sealed`,
+            `  app      ${state.urls.app ?? "not forwarded"}  (links inside the app may use its in-sandbox name)`,
+            `  mailpit  ${state.urls.mail ?? "not forwarded"}`,
+            ...state.notes.map((note) => `  note: ${note}`),
+            "",
+            "NEXT",
+            "  proofy dev test <flow>  run a flow; three identical runs make it ready to approve",
+            "  proofy dev down         stop it and delete its data",
+        ].join("\n"),
+    };
+}
+async function devTest(deps, project, names, extra) {
+    const state = await readState(project);
+    if (!state || !(await running(deps, state))) {
+        throw new CliError("The dev sandbox is not running", "VALIDATION_ERROR", ["Run `proofy dev up` first"]);
+    }
+    const available = await flowNames(project.paths);
+    const withTests = [];
+    for (const name of available)
+        if (await exists(join(project.paths.tests, `${name}.spec.ts`)))
+            withTests.push(name);
+    const chosen = names.length > 0 ? names : withTests;
+    for (const name of chosen) {
+        if (!withTests.includes(name)) {
+            throw new CliError(available.includes(name) ? `${name} has no test yet` : `No flow named ${name}`, "VALIDATION_ERROR", [`Flows with tests: ${withTests.join(", ") || "none"}`]);
+        }
+    }
+    if (chosen.length === 0)
+        throw new CliError("No flow has a test yet", "VALIDATION_ERROR", ["Ask your agent to write one (step 4 in e2e/AGENTS.md)"]);
+    const ctx = context(deps, project, await workingTreeInfo(deps, project.root));
+    const planned = await planFlows(ctx, chosen);
+    const id = await reserveRunId(ctx);
+    const startedAt = deps.now().toISOString();
+    const offsets = await logOffsets(state);
+    let environmentError;
+    try {
+        await testsInSandbox(ctx, state, planned, extra);
+    }
+    catch (error) {
+        if (!(error instanceof CliError) || error.code !== "ENVIRONMENT_ERROR")
+            throw error;
+        environmentError = [error.message, ...error.suggestions].join("\n");
+    }
+    const notes = extra.length > 0 ? [`Playwright arguments: ${extra.join(" ")}. A filtered run can leave requirements unchecked`] : [];
+    const runDir = join(outDir(project.paths), id);
+    const report = await finishRun(ctx, { id, kind: "dev", startedAt, runDir, planned, notes, sandbox: state, offsets, ...(environmentError ? { environmentError } : {}) });
+    return runResult(report, runDir, project.root);
+}
+async function devDown(deps, project) {
+    const state = await readState(project);
+    if (!state) {
+        return { data: { sandbox: "none running" }, help: ["Run `proofy dev up` to start one"] };
+    }
+    await saveLogs(deps.proc, state, outDir(project.paths));
+    await stop(deps.proc, state);
+    await rm(stateFile(project), { force: true });
+    return { data: { sandbox: state.project, status: "stopped, data deleted" }, help: ["Run `proofy` to see each flow's state"] };
+}

package/dist/commands/home.d.ts

@@ -0,0 +1,3 @@
+import type { Deps } from "../deps.js";
+import type { CommandResult } from "./types.js";
+export declare function homeCommand(deps: Deps): Promise<CommandResult | string>;