@itmetsam/samurai-framework 0.22.3 → 0.22.5

package/AGENT-GUIDE.md

@@ -0,0 +1,50 @@
+# SAMURAI for coding agents
+
+A short guide for an AI coding agent that writes or runs tests with `@itmetsam/samurai-framework`. It describes what the package does today; the full guides are in the [wiki](https://github.com/degrootsam/samurai-framework/wiki).
+
+## The project
+
+- A project has `samurai.config.ts` (environments, base URL, groups), specs under its `srcDir` (`*.spec.ts`), and `.env.<environment>` files for secrets. Run every command in the project folder.
+- A spec is a normal TypeScript file:
+
+```ts
+import { expect, test } from "@itmetsam/samurai-framework";
+
+test("signs in", async ({ page, secrets }) => {
+  await page.goto("/login");
+  await page.getByLabel("Email").fill("ann@example.com");
+  await page.getByLabel("Password").fill(secrets.PASSWORD);
+  await page.getByRole("button", { name: "Sign in" }).click();
+  await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible();
+});
+```
+
+- Fixtures are `page`, `browser`, `browserName`, `env` (variables of the environment) and `secrets` (names are `UPPER_SNAKE_CASE`; set as `SAMURAI_SECRET_<NAME>` or in `.env.<environment>`). Never write a secret value into a spec.
+
+## Writing steps the editor can read
+
+A spec made of these statements can be read and edited by SAMURAI's step codec (anything else is kept as a `custom` step): `page.goto`, `click`, `fill`, `press`, `check`, `uncheck`, `selectOption`, `hover`, `dblclick`, `clear`, `setInputFiles`, `dropFiles`, `expect(...)` with the common matchers, `expect(page).toHaveURL` / `toHaveTitle`, `outputs.save`, `waitForNetworkIdle`, `waitForTimeout`, `page.screenshot({ name })`. Locators are chains of `getByRole`, `getByLabel`, `getByText`, `getByPlaceholder`, `getByAltText`, `getByTitle`, `getByTestId`, `getByCss` and `locator(xpath)`, with `nth`, `first`, `last` and `filter`. Prefer, in this order: test id, role and name, label, text, then CSS. Wiki: Steps and the recorder, Locators, Assertions.
+
+## Commands
+
+| Command                                                     | Does                                                                                |
+| ----------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `samurai list --json`                                       | An array of `{ "name", "file" }` (plus `"modifier"`, `"reason"`); no browser starts |
+| `samurai run --json`                                        | JSON lines, one event per line, while the tests run                                 |
+| `samurai run --file tests/login.spec.ts --env staging`      | Run one spec in one environment (`--grep`, `--group`, `--browser` also select)      |
+| `samurai record <spec> --new "title" --json`                | Open a browser and record into a spec; one JSON event per step                      |
+| `samurai flow list` / `check` / `run <flow>` (all `--json`) | Flows: graphs of tests                                                              |
+| `samurai browsers install all`                              | Download the pinned Firefox and Chrome                                              |
+
+Exit codes: `0` everything passed, `1` a test failed (or a run ended early), `2` a usage or configuration error. A failing run prints what failed; fix the cause, then run that one spec again.
+
+## Reading results
+
+`samurai run` writes `result/report.json` and prints the same events with `--json` (`run-start`, `test-start`, `test-end` with a `result`, `run-end` with a `summary`). A test result has a `status` (`success`, `failed` or `skipped`), a `duration` and, for a failure, a flat `type` (`error`, `assertion` or `timeout`), `message` and `stack`; a test that passed on a retry is marked `flaky`. Secrets are masked in everything written.
+
+## Rules of thumb
+
+- Open pages with a path (`page.goto("/login")`); the base URL comes from the environment.
+- Assertions retry on their own; do not add fixed waits. Use `waitForNetworkIdle` only when nothing on the page can be asserted.
+- Keep tests short and independent; share setup with fixtures, not with the order of tests.
+- Run `samurai list` after writing a spec to see that it was read, then run it.

package/bin/samurai.mjs

@@ -40,6 +40,7 @@ try {
 }
 
 const { main } = await import("../dist/cli/main.js");
+const { terminalPrompt } = await import("../dist/cli/prompt.js");
 // Ctrl+C (or a termination signal) ends a recording or a flow run cleanly (the browser is closed, the file is complete); a second one stops at once
 const interrupt = new AbortController();
 for (const signal of ["SIGINT", "SIGTERM"]) {
@@ -54,5 +55,6 @@ const code = await main(process.argv.slice(2), {
   color: Boolean(process.stdout.isTTY) && !process.env.NO_COLOR,
   env: process.env,
   signal: interrupt.signal,
+  ...(terminalPrompt() && { prompt: terminalPrompt() }),
 });
 process.exit(code);

package/dist/agent/generate-kind.d.ts

@@ -0,0 +1,5 @@
+import { StepRecorder } from "./recording.js";
+import type { RunKind } from "./run-kind.js";
+import type { AgentOptions } from "./types.js";
+/** The run of `runAgent`: typed steps go into a spec file */
+export declare const generateKind: RunKind<AgentOptions, StepRecorder>;

package/dist/agent/generate-kind.js

@@ -0,0 +1,40 @@
+import { resultSecrets } from "../recorder/session-secrets.js";
+import { buildSystemPrompt } from "./prompt.js";
+import { StepRecorder } from "./recording.js";
+import { personRecording } from "./take-over.js";
+import { createTools } from "./tools/index.js";
+/** The run of `runAgent`: typed steps go into a spec file */
+export const generateKind = {
+    file: (options) => options.file,
+    sink: (options, { baseURL, emit }) => new StepRecorder({
+        file: options.file,
+        create: options.create,
+        test: options.test,
+        baseURL,
+        onStep: (event, code, source) => emit({
+            type: "step",
+            event,
+            ...(code !== undefined && { code }),
+            source,
+        }),
+    }),
+    opened: (steps, url) => {
+        if (steps.count === 0)
+            steps.observe({ type: "goto", url });
+    },
+    tools: (context) => createTools(context),
+    prompt: (input, options) => buildSystemPrompt({
+        ...input,
+        ...(options.plan !== undefined && { hasPlan: true }),
+    }),
+    opening: (options, first) => options.plan !== undefined
+        ? `Goal: ${options.goal}\n\nPlan (written earlier by another agent; follow it, but check each step on the live page):\n${options.plan.trim()}\n\n${first}`
+        : `Goal: ${options.goal}\n\n${first}`,
+    secrets: (steps) => resultSecrets(steps.events, []),
+    person: ({ page, sink, snapshots, baseURL }) => personRecording({
+        page,
+        steps: sink,
+        snapshots,
+        ...(baseURL !== undefined && { baseURL }),
+    }),
+};

package/dist/agent/index.d.ts

@@ -0,0 +1,19 @@
+import type { AgentOptions, AgentSession, PlanOptions, PlanSession } from "./types.js";
+export { DEFAULT_LIMITS, resolveLimits, type AgentLimits } from "./limits.js";
+export { assertModelObject, type AgentModel } from "./model.js";
+export { readPlan } from "./plan/read-plan.js";
+export { defaultModelSpec, ModelSetupError, modelFromSpec, } from "./providers.js";
+export type { AgentEndReason, AgentEvent, AgentOptions, AgentResult, AgentSession, PlanOptions, PlanResult, PlanSession, } from "./types.js";
+/**
+ * Starts the agent on a goal. The model is an AI SDK model object; the run opens a browser, writes typed steps
+ * into the spec file as they succeed, and ends with an `ended` event whatever happens. Throws at once for a model
+ * that is a string. Needs the optional packages `ai` and `zod`. With `plan` (the text of a plan from `runPlan`)
+ * the agent follows that plan, checking each step on the live page.
+ */
+export declare function runAgent(options: AgentOptions): AgentSession;
+/**
+ * Starts the planning agent on a goal: it explores the page and writes a Markdown plan into `out`, a step at a
+ * time, for `runAgent`'s `plan` option. The page is read-only: every request that is not a GET is stopped. Same
+ * events and `ended` event as `runAgent`, plus `plan-step`. Needs the optional packages `ai` and `zod`.
+ */
+export declare function runPlan(options: PlanOptions): PlanSession;

package/dist/agent/index.js

@@ -0,0 +1,23 @@
+import { startPlan } from "./plan/run.js";
+import { startAgent } from "./run.js";
+export { DEFAULT_LIMITS, resolveLimits } from "./limits.js";
+export { assertModelObject } from "./model.js";
+export { readPlan } from "./plan/read-plan.js";
+export { defaultModelSpec, ModelSetupError, modelFromSpec, } from "./providers.js";
+/**
+ * Starts the agent on a goal. The model is an AI SDK model object; the run opens a browser, writes typed steps
+ * into the spec file as they succeed, and ends with an `ended` event whatever happens. Throws at once for a model
+ * that is a string. Needs the optional packages `ai` and `zod`. With `plan` (the text of a plan from `runPlan`)
+ * the agent follows that plan, checking each step on the live page.
+ */
+export function runAgent(options) {
+    return startAgent(options);
+}
+/**
+ * Starts the planning agent on a goal: it explores the page and writes a Markdown plan into `out`, a step at a
+ * time, for `runAgent`'s `plan` option. The page is read-only: every request that is not a GET is stopped. Same
+ * events and `ended` event as `runAgent`, plus `plan-step`. Needs the optional packages `ai` and `zod`.
+ */
+export function runPlan(options) {
+    return startPlan(options);
+}

package/dist/agent/instructions.d.ts

@@ -0,0 +1,13 @@
+/** The two instruction files together may not be larger than this (bytes) */
+export declare const MAX_INSTRUCTIONS_BYTES: number;
+export interface Instructions {
+    /** The files that were read, relative to the project folder */
+    files: string[];
+    /** Their text as it goes into the prompt; empty without files */
+    text: string;
+}
+/**
+ * Reads `AGENTS.md` and `.samurai/agent.md` from the project folder (both are optional). A file that is a link
+ * to somewhere outside the folder is an error, never read. Together they may hold at most 32 KB.
+ */
+export declare function loadInstructions(projectDir: string): Instructions;

package/dist/agent/instructions.js

@@ -0,0 +1,44 @@
+import { lstatSync, readFileSync, realpathSync } from "node:fs";
+import path from "node:path";
+/** The two instruction files together may not be larger than this (bytes) */
+export const MAX_INSTRUCTIONS_BYTES = 32 * 1024;
+/** The shared agent file first, the more specific SAMURAI one last: it wins where they disagree */
+const FILES = ["AGENTS.md", path.join(".samurai", "agent.md")];
+function readInside(root, name) {
+    const file = path.join(root, name);
+    try {
+        lstatSync(file);
+    }
+    catch {
+        return undefined;
+    }
+    const real = realpathSync(file);
+    const relative = path.relative(root, real);
+    if (relative.startsWith("..") || path.isAbsolute(relative))
+        throw new Error(`agent(): ${name} points outside the project folder, so it is not read`);
+    return readFileSync(real, "utf8");
+}
+/**
+ * Reads `AGENTS.md` and `.samurai/agent.md` from the project folder (both are optional). A file that is a link
+ * to somewhere outside the folder is an error, never read. Together they may hold at most 32 KB.
+ */
+export function loadInstructions(projectDir) {
+    const root = realpathSync(projectDir);
+    const parts = [];
+    for (const name of FILES) {
+        const text = readInside(root, name);
+        if (text !== undefined)
+            parts.push({ name, text });
+    }
+    const bytes = parts.reduce((sum, p) => sum + Buffer.byteLength(p.text), 0);
+    if (bytes > MAX_INSTRUCTIONS_BYTES)
+        throw new Error(`agent(): the instruction files hold ${Math.ceil(bytes / 1024)} KB, over the ${MAX_INSTRUCTIONS_BYTES / 1024} KB limit (${parts
+            .map((p) => `${p.name} ${Math.ceil(Buffer.byteLength(p.text) / 1024)} KB`)
+            .join(", ")}); shorten them`);
+    return {
+        files: parts.map((p) => p.name),
+        text: parts
+            .map((p) => `### From ${p.name.replace(/\\/g, "/")}\n\n${p.text.trim()}`)
+            .join("\n\n"),
+    };
+}

package/dist/agent/limits.d.ts

@@ -0,0 +1,12 @@
+/** Hard limits of one agent run; reaching one ends the run cleanly with the steps written so far */
+export interface AgentLimits {
+    /** Model calls (loop turns). A tool call is not a turn */
+    maxSteps: number;
+    /** Input plus output tokens, summed over the run */
+    maxTokens: number;
+    /** Wall-clock time of the run in ms */
+    timeoutMs: number;
+}
+export declare const DEFAULT_LIMITS: Readonly<AgentLimits>;
+/** The defaults with `overrides` on top; a limit that is not a positive finite number throws */
+export declare function resolveLimits(overrides?: Partial<AgentLimits>): AgentLimits;

package/dist/agent/limits.js

@@ -0,0 +1,18 @@
+export const DEFAULT_LIMITS = {
+    maxSteps: 40,
+    maxTokens: 400_000,
+    timeoutMs: 10 * 60_000,
+};
+/** The defaults with `overrides` on top; a limit that is not a positive finite number throws */
+export function resolveLimits(overrides = {}) {
+    const limits = { ...DEFAULT_LIMITS };
+    for (const key of Object.keys(DEFAULT_LIMITS)) {
+        const value = overrides[key];
+        if (value === undefined)
+            continue;
+        if (!Number.isFinite(value) || value <= 0)
+            throw new RangeError(`agent(): limits.${key} must be a positive number, got ${String(value)}`);
+        limits[key] = value;
+    }
+    return limits;
+}

package/dist/agent/loop.d.ts

@@ -0,0 +1,32 @@
+import type { AgentLimits } from "./limits.js";
+import type { AgentModel } from "./model.js";
+import type { AiModule } from "./sdk-tools.js";
+import type { AgentController } from "./session.js";
+/** What the loop counts, shared with the run that reports it */
+export interface RunTally {
+    modelCalls: number;
+    tokens: number;
+    finished: boolean;
+}
+export interface LoopInput {
+    ai: AiModule;
+    model: AgentModel;
+    system: string;
+    prompt: string;
+    tools: Record<string, unknown>;
+    controller: AgentController;
+    limits: AgentLimits;
+    tally: RunTally;
+}
+export interface LoopOutcome {
+    /** The model's last words when it ended without calling finish */
+    text: string;
+    /** The loop stopped because of a limit while the model still had work to do */
+    limit?: "step-limit" | "token-limit";
+}
+/**
+ * The AI SDK's tool loop with SAMURAI's guards: model calls and tokens are counted after every step (and a
+ * `usage` event sent), a paused or taken-over run makes no new model call, and `finish` ends the loop. Time and
+ * `stop` abort through the controller's signal.
+ */
+export declare function runLoop(input: LoopInput): Promise<LoopOutcome>;

package/dist/agent/loop.js

@@ -0,0 +1,46 @@
+/**
+ * The AI SDK's tool loop with SAMURAI's guards: model calls and tokens are counted after every step (and a
+ * `usage` event sent), a paused or taken-over run makes no new model call, and `finish` ends the loop. Time and
+ * `stop` abort through the controller's signal.
+ */
+export async function runLoop(input) {
+    const { ai, controller, limits, tally } = input;
+    const result = await ai.generateText({
+        model: input.model,
+        system: input.system,
+        prompt: input.prompt,
+        tools: input.tools,
+        abortSignal: controller.signal,
+        stopWhen: [
+            ai.isStepCount(limits.maxSteps),
+            ai.hasToolCall("finish"),
+            () => tally.tokens >= limits.maxTokens,
+        ],
+        prepareStep: async () => {
+            await controller.gate();
+            return undefined;
+        },
+        onStepFinish: (step) => {
+            tally.modelCalls++;
+            const inputTokens = step.usage.inputTokens ?? 0;
+            const outputTokens = step.usage.outputTokens ?? 0;
+            tally.tokens += step.usage.totalTokens ?? inputTokens + outputTokens;
+            if (step.text.trim() !== "")
+                controller.emit({ type: "plan", text: step.text.trim() });
+            controller.emit({
+                type: "usage",
+                inputTokens,
+                outputTokens,
+                totalTokens: step.usage.totalTokens ?? inputTokens + outputTokens,
+            });
+        },
+    });
+    const last = result.steps[result.steps.length - 1];
+    const unfinished = last !== undefined && last.toolCalls.length > 0;
+    if (tally.finished || !unfinished)
+        return { text: result.text };
+    return {
+        text: result.text,
+        limit: tally.tokens >= limits.maxTokens ? "token-limit" : "step-limit",
+    };
+}

package/dist/agent/model.d.ts

@@ -0,0 +1,9 @@
+import type { LanguageModel } from "ai";
+/**
+ * A model object from an AI SDK provider package (`anthropic("...")`, `openai("...")`, an OpenAI-compatible
+ * endpoint). Never a string: the SDK resolves a bare string through the Vercel AI Gateway, a third party the
+ * user did not choose, which would receive the page content.
+ */
+export type AgentModel = Exclude<LanguageModel, string>;
+/** `model` as an `AgentModel`; throws for a string id or anything that is not a model object */
+export declare function assertModelObject(model: unknown): AgentModel;

package/dist/agent/model.js

@@ -0,0 +1,14 @@
+const VERSIONS = ["v2", "v3", "v4"];
+/** `model` as an `AgentModel`; throws for a string id or anything that is not a model object */
+export function assertModelObject(model) {
+    if (typeof model === "string")
+        throw new Error(`agent(): model must be a model object from a provider package, not the string "${model}" ` +
+            "(a string id would send the page through the Vercel AI Gateway). " +
+            'Install the provider (for example @ai-sdk/anthropic) and pass anthropic("model-name")');
+    const version = typeof model === "object" && model !== null
+        ? model.specificationVersion
+        : undefined;
+    if (typeof version !== "string" || !VERSIONS.includes(version))
+        throw new Error("agent(): model must be an AI SDK language model object (it has no specificationVersion v2, v3 or v4)");
+    return model;
+}

package/dist/agent/plan/guard.d.ts

@@ -0,0 +1,7 @@
+import type Page from "../../browser/page.js";
+/**
+ * Makes the page read-only for the planner: every request that is not a `GET`, `HEAD` or `OPTIONS` is aborted
+ * before it leaves the browser (form submits, `fetch`, XHR, beacons), and `onBlocked` hears what it was. A `GET`
+ * that changes data and a WebSocket message are not covered. Other origins are the origin policy's business.
+ */
+export declare function installPlanGuard(page: Pick<Page, "route">, onBlocked: (what: string) => void): Promise<void>;

package/dist/agent/plan/guard.js

@@ -0,0 +1,32 @@
+/** Methods that read: they pass. `OPTIONS` is the CORS preflight, which carries no data of the page */
+const READS = new Set(["GET", "HEAD", "OPTIONS"]);
+/** "POST /api/feedback": the method and the path, without the query (it can hold values) */
+function describeRequest(method, url) {
+    try {
+        return `${method} ${new URL(url).pathname}`;
+    }
+    catch {
+        return method;
+    }
+}
+/**
+ * Makes the page read-only for the planner: every request that is not a `GET`, `HEAD` or `OPTIONS` is aborted
+ * before it leaves the browser (form submits, `fetch`, XHR, beacons), and `onBlocked` hears what it was. A `GET`
+ * that changes data and a WebSocket message are not covered. Other origins are the origin policy's business.
+ */
+export async function installPlanGuard(page, onBlocked) {
+    await page.route("**/*", async (route) => {
+        const request = route.request();
+        const { method, url } = request;
+        if (READS.has(method.toUpperCase())) {
+            await route.continue();
+            return;
+        }
+        onBlocked(describeRequest(method.toUpperCase(), url));
+        // An aborted form submit leaves Chrome on its error page; an empty 204 answer to a navigation keeps the page
+        if (request.resourceType === "document" || request.navigation !== null)
+            await route.fulfill({ status: 204 });
+        else
+            await route.abort();
+    });
+}

package/dist/agent/plan/plan-file.d.ts

@@ -0,0 +1,59 @@
+/** A plan file may not be larger than this (bytes), for the planner and for `generate --plan` */
+export declare const MAX_PLAN_BYTES: number;
+interface PlanStep {
+    text: string;
+    expect?: string;
+}
+/** A plan as `parsePlan` reads it; every part but the steps may be missing in a hand-written file */
+interface ParsedPlan {
+    title: string;
+    goal: string;
+    start: string;
+    steps: PlanStep[];
+    seen: string[];
+    notDone: string[];
+    questions: string[];
+}
+/**
+ * A plan file being written. The whole file is written again after every call, so it is valid Markdown with its
+ * four headings whenever the run stops. Texts are masked and made one line long.
+ */
+declare class PlanFile {
+    readonly file: string;
+    private readonly goal;
+    private start;
+    private readonly steps;
+    private readonly seenItems;
+    private readonly notDoneItems;
+    private readonly questionItems;
+    constructor(file: string, goal: string, start: string);
+    /** The title, which is also what the run reports as the name of the test */
+    get title(): string;
+    get count(): number;
+    private render;
+    /** Writes the file; refuses, and keeps the file as it was, when it would pass the size limit */
+    private save;
+    private add;
+    /** Appends a step and returns its number */
+    addStep(text: string, expect?: string): number;
+    /** Names the page the plan starts on, once the browser is there */
+    setStart(url: string): void;
+    seen(text: string): void;
+    notDone(text: string): void;
+    question(text: string): void;
+    /** Writes the first version of the file */
+    create(): void;
+}
+export type { PlanFile };
+/** Starts a plan file: the headings are written at once. An existing file is an error unless `force` is set */
+export declare function createPlan(input: {
+    goal: string;
+    start: string;
+    out: string;
+    force?: boolean;
+}): PlanFile;
+/**
+ * Reads a plan, the one `createPlan` wrote or one a person edited: blank lines, a missing title, missing sections
+ * and `None.` placeholders are fine. Only the `## Steps` heading is needed.
+ */
+export declare function parsePlan(text: string): ParsedPlan;

package/dist/agent/plan/plan-file.js

@@ -0,0 +1,201 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { projectDir } from "../../config/config.js";
+import { maskText } from "../../config/mask.js";
+/** A plan file may not be larger than this (bytes), for the planner and for `generate --plan` */
+export const MAX_PLAN_BYTES = 32 * 1024;
+const NONE = "None.";
+const TITLE_LENGTH = 80;
+/** One line, masked: a new line in a text must not be able to start a heading or a step */
+function oneLine(text) {
+    return maskText(text).replace(/\s+/g, " ").trim();
+}
+function bullets(items) {
+    return items.length > 0
+        ? items.map((item) => `- ${item}`).join("\n")
+        : `- ${NONE}`;
+}
+/**
+ * A plan file being written. The whole file is written again after every call, so it is valid Markdown with its
+ * four headings whenever the run stops. Texts are masked and made one line long.
+ */
+class PlanFile {
+    constructor(file, goal, start) {
+        this.file = file;
+        this.goal = goal;
+        this.start = start;
+        this.steps = [];
+        this.seenItems = [];
+        this.notDoneItems = [];
+        this.questionItems = [];
+    }
+    /** The title, which is also what the run reports as the name of the test */
+    get title() {
+        const first = this.goal.slice(0, TITLE_LENGTH).trim();
+        return first.length < this.goal.length ? `${first}…` : first;
+    }
+    get count() {
+        return this.steps.length;
+    }
+    render() {
+        const steps = this.steps.map((step, i) => `${i + 1}. ${step.text}${step.expect !== undefined ? `\n   Expect: ${step.expect}` : ""}`);
+        return [
+            `# Plan: ${this.title}`,
+            "",
+            `Goal: ${this.goal}`,
+            `Start: ${this.start}`,
+            "",
+            "## Steps",
+            "",
+            steps.length > 0 ? steps.join("\n") : `- ${NONE}`,
+            "",
+            "## Seen on the page",
+            "",
+            bullets(this.seenItems),
+            "",
+            "## Not done",
+            "",
+            bullets(this.notDoneItems),
+            "",
+            "## Open questions",
+            "",
+            bullets(this.questionItems),
+            "",
+        ].join("\n");
+    }
+    /** Writes the file; refuses, and keeps the file as it was, when it would pass the size limit */
+    save() {
+        const text = this.render();
+        if (Buffer.byteLength(text) > MAX_PLAN_BYTES)
+            throw new Error(`the plan file is full (${MAX_PLAN_BYTES / 1024} KB); finish with what it holds, or shorten the next entry`);
+        mkdirSync(path.dirname(this.file), { recursive: true });
+        writeFileSync(this.file, text);
+    }
+    add(list, text) {
+        list.push(oneLine(text));
+        try {
+            this.save();
+        }
+        catch (error) {
+            list.pop();
+            throw error;
+        }
+    }
+    /** Appends a step and returns its number */
+    addStep(text, expect) {
+        const step = { text: oneLine(text) };
+        const wanted = expect === undefined ? "" : oneLine(expect);
+        if (wanted !== "")
+            step.expect = wanted;
+        this.steps.push(step);
+        try {
+            this.save();
+        }
+        catch (error) {
+            this.steps.pop();
+            throw error;
+        }
+        return this.steps.length;
+    }
+    /** Names the page the plan starts on, once the browser is there */
+    setStart(url) {
+        this.start = oneLine(url);
+        this.save();
+    }
+    seen(text) {
+        this.add(this.seenItems, text);
+    }
+    notDone(text) {
+        this.add(this.notDoneItems, text);
+    }
+    question(text) {
+        this.add(this.questionItems, text);
+    }
+    /** Writes the first version of the file */
+    create() {
+        this.save();
+    }
+}
+/** Starts a plan file: the headings are written at once. An existing file is an error unless `force` is set */
+export function createPlan(input) {
+    const file = path.resolve(projectDir(), input.out);
+    if (existsSync(file) && input.force !== true)
+        throw new Error(`createPlan(): ${file} already exists; pass force (--force) to replace it`);
+    const plan = new PlanFile(file, oneLine(input.goal), oneLine(input.start));
+    plan.create();
+    return plan;
+}
+const HEADING = /^##\s+(.*?)\s*$/;
+const STEP = /^\s*\d+\.\s+(.*)$/;
+const BULLET = /^\s*[-*]\s+(.*)$/;
+const EXPECT = /^\s+Expect:\s*(.*)$/i;
+const FIELD = /^(Goal|Start):\s*(.*)$/i;
+function sectionOf(heading) {
+    const name = heading.toLowerCase();
+    if (name === "steps")
+        return "steps";
+    if (name.startsWith("seen"))
+        return "seen";
+    if (name === "not done")
+        return "notDone";
+    if (name.startsWith("open question"))
+        return "questions";
+    return "other";
+}
+/**
+ * Reads a plan, the one `createPlan` wrote or one a person edited: blank lines, a missing title, missing sections
+ * and `None.` placeholders are fine. Only the `## Steps` heading is needed.
+ */
+export function parsePlan(text) {
+    const plan = {
+        title: "",
+        goal: "",
+        start: "",
+        steps: [],
+        seen: [],
+        notDone: [],
+        questions: [],
+    };
+    let section;
+    let hasSteps = false;
+    for (const line of text.split(/\r?\n/)) {
+        const heading = HEADING.exec(line);
+        if (heading) {
+            section = sectionOf(heading[1]);
+            if (section === "steps")
+                hasSteps = true;
+            continue;
+        }
+        if (line.trim() === "")
+            continue;
+        if (section === undefined) {
+            const title = /^#\s+(?:Plan:\s*)?(.*)$/i.exec(line);
+            const field = FIELD.exec(line);
+            if (title && plan.title === "")
+                plan.title = title[1].trim();
+            else if (field)
+                plan[field[1].toLowerCase()] = field[2].trim();
+            continue;
+        }
+        if (section === "other")
+            continue;
+        if (section === "steps") {
+            const last = plan.steps[plan.steps.length - 1];
+            const step = STEP.exec(line);
+            const expect = EXPECT.exec(line);
+            if (step)
+                plan.steps.push({ text: step[1].trim() });
+            else if (last && expect)
+                last.expect = expect[1].trim();
+            else if (last && !BULLET.test(line) && /^\s/.test(line))
+                last.text = `${last.text} ${line.trim()}`;
+            continue;
+        }
+        const item = BULLET.exec(line)?.[1]?.trim();
+        if (item !== undefined && item !== NONE)
+            plan[section].push(item);
+    }
+    if (!hasSteps)
+        throw new Error('parsePlan(): the plan has no "## Steps" heading');
+    return plan;
+}