@popoverai/dotrequirements 0.33.0 → 0.34.1

package/dist/commands/solution/look-up.js

@@ -0,0 +1,69 @@
+import { api } from "../../convex.js";
+import { AXES } from "../scores/index.js";
+import { solutionClient } from "./client.js";
+import { requireSolution } from "./run-file.js";
+/**
+ * A thing as the reference the verbs take, then how to read it, as the
+ * brief lists what an outcome works from (`referenceOf` in the backend's
+ * solutions/brief.ts): a document by the command that writes it into the
+ * repository, a board and a mockup by the commands that show them, an image
+ * by where its copy loads from, a video and a demo's script by their
+ * script, and scores as their seven axes.
+ */
+function referenceOf(thing) {
+    const titled = thing.title ? ` (${thing.title})` : "";
+    switch (thing.kind) {
+        case "document":
+            return `document:${thing.documentId}${titled} — \`dotreq sync --cloud-contributes ${thing.documentId}\` writes it into the repository; read that file`;
+        case "board":
+            return `board:${thing.boardId}${titled} — \`dotreq board show ${thing.boardId}\``;
+        case "mockup":
+            return `mockup:${thing.mockupId}${titled} — \`dotreq mockup preview ${thing.mockupId} --out mockup.html\``;
+        case "file":
+            return `file:${thing.path}${thing.branch ? `@${thing.branch}` : ""}${titled}`;
+        case "link":
+            return `link:${thing.url}${titled}`;
+        case "preview":
+            return `"preview:${thing.port}${thing.page ?? ""} ${thing.command}"${titled}`;
+        case "pull request":
+            return `pr:${thing.number}${titled} — ${thing.url}`;
+        case "image":
+            return `image ${thing.name}${titled} — ${thing.url ?? "its copy is gone"}`;
+        case "video":
+        case "demo script":
+            return `${thing.kind} ${thing.name}${titled}, recorded from this script:\n\n${(thing.script ?? "").replace(/^/gm, "  ")}`;
+        case "scores":
+            return AXES.map((axis) => {
+                const score = thing[axis.key];
+                return `${axis.label}: ${score?.score}/5 — ${score?.reason}`;
+            }).join("\n- ");
+        default:
+            return JSON.stringify(thing);
+    }
+}
+/**
+ * `dotreq solution things <name>`: what an outcome, an input, or the
+ * outcomes a checkpoint presents hold now, one reference a line, under
+ * each outcome's name. Where a brief says what else the solution has made,
+ * to look up if it matters, it names this command.
+ */
+export async function thingsCommand(name, options) {
+    const { solutionId } = requireSolution(options);
+    const client = solutionClient();
+    const looked = await client.query(api.solutions.queries.getThings, {
+        solutionId,
+        name,
+    });
+    if (!looked) {
+        throw new Error(`The solution has no outcome, input or checkpoint called "${name}".`);
+    }
+    const sections = looked.made.map(({ outcomes, things }) => [
+        `### ${outcomes.join(", ")}`,
+        "",
+        ...(things.length > 0
+            ? things.map((thing) => `- ${referenceOf(thing)}`)
+            : ["Nothing yet."]),
+    ].join("\n"));
+    process.stdout.write(`${sections.join("\n\n")}\n`);
+}
+//# sourceMappingURL=look-up.js.map

package/dist/commands/solution/next.d.ts

@@ -0,0 +1,12 @@
+import { type WhereOptions } from "./run-file.js";
+/**
+ * `dotreq solution next`: what an agent runs when it is invoked. Which
+ * solution and agent is the run's own (VERB-4); the backend takes the
+ * first part of an outcome's work the agent has due — drafting an outcome
+ * it drafts, or reviewing one it reviews — and composes its brief
+ * (PROMPT-BLOCK-6), which this prints as given.
+ */
+export declare function nextCommand(options: WhereOptions & {
+    json?: boolean;
+}): Promise<void>;
+//# sourceMappingURL=next.d.ts.map

package/dist/commands/solution/next.js

@@ -0,0 +1,48 @@
+import { api } from "../../convex.js";
+import { EXIT, renderStanding } from "./brief.js";
+import { solutionClient } from "./client.js";
+import { saveDemoScriptCopies } from "./demo-script.js";
+import { saveImageCopies } from "./image.js";
+import { requireWhere } from "./run-file.js";
+import { layOut } from "./working-folder.js";
+/**
+ * `dotreq solution next`: what an agent runs when it is invoked. Which
+ * solution and agent is the run's own (VERB-4); the backend takes the
+ * first part of an outcome's work the agent has due — drafting an outcome
+ * it drafts, or reviewing one it reviews — and composes its brief
+ * (PROMPT-BLOCK-6), which this prints as given.
+ */
+export async function nextCommand(options) {
+    const { solutionId, agent } = requireWhere(options);
+    const client = solutionClient();
+    const result = await client.mutation(api.solutions.mutations.next, { solutionId, agent });
+    // With --json: the kind, the outcome, and the same text, for a workflow
+    // to parse; `step` repeats the outcome for a reader that knows it by that name.
+    const emit = (outcome, text) => {
+        process.stdout.write(options.json
+            ? `${JSON.stringify({ kind: result.kind, outcome, step: outcome, text })}\n`
+            : text);
+    };
+    if (result.kind === "nothing ready") {
+        emit(null, renderStanding(result));
+        process.exitCode = EXIT.nothingReady;
+        return;
+    }
+    // BRANCH-4.0: on a project with no repository connected, the documents the
+    // outcome works from are written into the working folder before it starts.
+    const folder = result
+        .workingFolder;
+    if (folder?.length)
+        layOut(folder);
+    emit(result.step.outcome ?? result.step.label, result.text.endsWith("\n") ? result.text : `${result.text}\n`);
+    // SIGHT-13.1: a demo's script the reviewer reads is saved in its
+    // checkout, where its brief says it is, to record the video from.
+    saveDemoScriptCopies(result.reviewing ?? []);
+    // SIGHT-9.3: the images the outcome works on are saved in the checkout,
+    // where its brief says they are.
+    await saveImageCopies(client, solutionId, [
+        ...(result.reviewing ?? []),
+        ...(result.against ?? []),
+    ]);
+}
+//# sourceMappingURL=next.js.map

package/dist/commands/solution/plan-file.d.ts

@@ -0,0 +1,22 @@
+/** A plan or scenario file, read as YAML (or JSON, which YAML reads too). */
+export declare function readPlanFile(text: string, _file: string): unknown;
+/**
+ * A plan file's plan as the backend takes it (docs/working/plan-surfaces.md):
+ * its surfaces, its phases of outcomes under `plan`, its approvals, agents,
+ * loops, inputs, `orient to` and hooks, as the file writes them; the backend reads them
+ * (`readOutcomePlan`). A file whose `plan` isn't a list of phases, as a
+ * scenario's `{ from: default, ... }`, goes as it is.
+ */
+export declare function planPayload(spec: {
+    surfaces?: unknown;
+    plan?: unknown;
+    approvals?: unknown;
+    checkpoints?: unknown;
+    agents?: unknown;
+    inputs?: unknown;
+    loops?: unknown;
+    "orient to"?: unknown;
+    conversations?: unknown;
+    hooks?: unknown;
+}): unknown;
+//# sourceMappingURL=plan-file.d.ts.map

package/dist/commands/solution/plan-file.js

@@ -0,0 +1,33 @@
+import { parse } from "yaml";
+/** A plan or scenario file, read as YAML (or JSON, which YAML reads too). */
+export function readPlanFile(text, _file) {
+    return parse(text);
+}
+/**
+ * A plan file's plan as the backend takes it (docs/working/plan-surfaces.md):
+ * its surfaces, its phases of outcomes under `plan`, its approvals, agents,
+ * loops, inputs, `orient to` and hooks, as the file writes them; the backend reads them
+ * (`readOutcomePlan`). A file whose `plan` isn't a list of phases, as a
+ * scenario's `{ from: default, ... }`, goes as it is.
+ */
+export function planPayload(spec) {
+    if (!Array.isArray(spec.plan))
+        return spec.plan;
+    const payload = { plan: spec.plan };
+    for (const key of [
+        "surfaces",
+        "approvals",
+        "checkpoints",
+        "agents",
+        "inputs",
+        "loops",
+        "orient to",
+        "conversations",
+        "hooks",
+    ]) {
+        if (spec[key] !== undefined)
+            payload[key] = spec[key];
+    }
+    return payload;
+}
+//# sourceMappingURL=plan-file.js.map

package/dist/commands/solution/preview-screenshot.d.ts

@@ -0,0 +1,21 @@
+import { type Image } from "./image.js";
+/**
+ * A screenshot of the page a preview opens on (SIGHT-12.0), taken where
+ * the drafter submits it, with the preview running on this machine:
+ * `agent-browser`, which the runner installs, opens the page in a session
+ * of its own, so the agent's own browser is left as it was, and the image
+ * is read as an image submitted is. When it can't be taken — nothing
+ * answers on the port, or there is no `agent-browser` here — the preview is
+ * submitted without one and the tab says so (12.2); `missed` says why, for
+ * the agent. The page is asked for at 127.0.0.1, as the preview's gate
+ * asks for it.
+ */
+export declare function screenshotPreview(preview: {
+    port: number;
+    page?: string;
+}): Promise<{
+    image: Image;
+} | {
+    missed: string;
+}>;
+//# sourceMappingURL=preview-screenshot.d.ts.map

package/dist/commands/solution/preview-screenshot.js

@@ -0,0 +1,56 @@
+import { execFile } from "node:child_process";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { readImage } from "./image.js";
+const run = promisify(execFile);
+/** How long the page has to answer, a first compile included, before no screenshot is taken. */
+const ANSWER_MS = 60_000;
+/**
+ * A screenshot of the page a preview opens on (SIGHT-12.0), taken where
+ * the drafter submits it, with the preview running on this machine:
+ * `agent-browser`, which the runner installs, opens the page in a session
+ * of its own, so the agent's own browser is left as it was, and the image
+ * is read as an image submitted is. When it can't be taken — nothing
+ * answers on the port, or there is no `agent-browser` here — the preview is
+ * submitted without one and the tab says so (12.2); `missed` says why, for
+ * the agent. The page is asked for at 127.0.0.1, as the preview's gate
+ * asks for it.
+ */
+export async function screenshotPreview(preview) {
+    const url = `http://127.0.0.1:${preview.port}${preview.page ?? "/"}`;
+    try {
+        const answer = await fetch(url, {
+            signal: AbortSignal.timeout(ANSWER_MS),
+        });
+        await answer.body?.cancel();
+    }
+    catch {
+        return { missed: `nothing answered at ${url}` };
+    }
+    const dir = mkdtempSync(join(tmpdir(), "dotreq-preview-"));
+    const session = `dotreq-preview-${preview.port}`;
+    const browse = (...args) => run("agent-browser", ["--session", session, ...args], {
+        timeout: ANSWER_MS,
+    });
+    try {
+        const path = join(dir, `preview-${preview.port}.png`);
+        await browse("open", url);
+        await browse("screenshot", path);
+        return { image: readImage(path) };
+    }
+    catch (error) {
+        const code = error.code;
+        return {
+            missed: code === "ENOENT"
+                ? "agent-browser isn't installed here"
+                : `agent-browser couldn't take it: ${error instanceof Error ? error.message.split("\n")[0] : String(error)}`,
+        };
+    }
+    finally {
+        await browse("close").catch(() => undefined);
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=preview-screenshot.js.map

package/dist/commands/solution/pull-request.d.ts

@@ -0,0 +1,25 @@
+import { type Where, type WhereOptions } from "./run-file.js";
+/** The solution's pull request: its number and where it opens. */
+export type PullRequest = {
+    url: string;
+    number: number;
+};
+/** The command that opens the solution's pull request and prints its reference. */
+export declare const OPEN_IT = "dotreq solution pull-request";
+/**
+ * `dotreq solution pull-request`: the solution's pull request, opened or
+ * found (PULL-2). Inside a runner the branch is pushed first, as a submission
+ * pushes it (2.0, SOLBRANCH-3); then the app opens a pull request from it
+ * into the branch it was made from, or finds the one already open (2.3,
+ * 2.4), and Ari is given its reference and its address (2.1). Nothing is
+ * recorded: Ari submits it with its work, by the reference (PULL-3.0).
+ */
+export declare function pullRequestCommand(options: WhereOptions): Promise<void>;
+/**
+ * The pull request Ari submitted as `pr:<number>`, checked against the
+ * repository: the one open from the solution's branch, with its address
+ * (PULL-3.0). Any other is refused, naming the open one by its reference,
+ * or, when none is open, the command that opens it (3.2).
+ */
+export declare function checkPullRequest(where: Pick<Where, "solutionId" | "agent" | "outcome">, number: number): Promise<PullRequest>;
+//# sourceMappingURL=pull-request.d.ts.map

package/dist/commands/solution/pull-request.js

@@ -0,0 +1,117 @@
+import { webApiUrl } from "../../cloud.js";
+import { getProjectCredentials } from "../../utils/project-settings.js";
+import { solutionClient } from "./client.js";
+import { pushWork } from "./pushing.js";
+import { requireWhere } from "./run-file.js";
+import { outcomeFor } from "./status.js";
+/** The command that opens the solution's pull request and prints its reference. */
+export const OPEN_IT = "dotreq solution pull-request";
+/**
+ * `dotreq solution pull-request`: the solution's pull request, opened or
+ * found (PULL-2). Inside a runner the branch is pushed first, as a submission
+ * pushes it (2.0, SOLBRANCH-3); then the app opens a pull request from it
+ * into the branch it was made from, or finds the one already open (2.3,
+ * 2.4), and Ari is given its reference and its address (2.1). Nothing is
+ * recorded: Ari submits it with its work, by the reference (PULL-3.0).
+ */
+export async function pullRequestCommand(options) {
+    const where = requireWhere(options);
+    if (where.branch) {
+        const pushed = await pushWork(solutionClient(), {
+            solutionId: where.solutionId,
+            branch: where.branch,
+        });
+        if (!pushed.ok) {
+            throw new Error(pushed.tell
+                .replace(/^Nothing was recorded:/, "No pull request was opened:")
+                .replace(/record again\.$/, "ask for the pull request again."));
+        }
+    }
+    // The outcome the pull request is for: the one the agent is drafting.
+    const outcome = await outcomeFor(solutionClient(), where, "outcome the pull request is for");
+    const said = await ask({
+        solutionId: where.solutionId,
+        agent: where.agent,
+        outcome,
+    });
+    const unopened = "No pull request was opened";
+    if (said.noRepository) {
+        throw new Error(`${unopened}: a pull request needs a repository, and this project has none connected. Connect one to the project, then ask again.`);
+    }
+    if (said.noBranch) {
+        throw new Error(`${unopened}: the solution has no branch yet. Its first session in a runner makes it.`);
+    }
+    if (said.notMade) {
+        throw new Error(`${unopened}: "${outcome}" isn't kept on a pull request, so it makes none.`);
+    }
+    if (said.refused) {
+        throw new Error(`${unopened}: the repository refused it: ${said.refused}`);
+    }
+    const pullRequest = pullRequestIn(said);
+    if (!pullRequest) {
+        throw new Error(`${unopened}: the app gave no pull request.`);
+    }
+    console.log([
+        `The solution's pull request is pr:${pullRequest.number}: ${pullRequest.url}`,
+        `Submit it with the rest of your work: dotreq solution author pr:${pullRequest.number} <reference>... --comment "..."`,
+    ].join("\n"));
+}
+/**
+ * The pull request Ari submitted as `pr:<number>`, checked against the
+ * repository: the one open from the solution's branch, with its address
+ * (PULL-3.0). Any other is refused, naming the open one by its reference,
+ * or, when none is open, the command that opens it (3.2).
+ */
+export async function checkPullRequest(where, number) {
+    const said = await ask({
+        solutionId: where.solutionId,
+        agent: where.agent,
+        ...(where.outcome ? { outcome: where.outcome } : {}),
+        number,
+    });
+    const unrecorded = "Nothing was recorded";
+    if (said.noRepository) {
+        throw new Error(`${unrecorded}: a pull request needs a repository, and this project has none connected.`);
+    }
+    if (said.noBranch) {
+        throw new Error(`${unrecorded}: pr:${number} isn't the solution's pull request: the solution has no branch yet.`);
+    }
+    if (said.refused) {
+        throw new Error(`${unrecorded}: couldn't read the solution's pull request from the repository: ${said.refused}`);
+    }
+    if (said.notOpen !== undefined) {
+        throw new Error(said.notOpen
+            ? `${unrecorded}: pr:${number} isn't the solution's pull request. The one open from its branch is pr:${said.notOpen.number} (${said.notOpen.url}); submit that one.`
+            : `${unrecorded}: pr:${number} isn't the solution's pull request, and none is open from its branch. Open it with \`${OPEN_IT}\`, which prints its reference, and submit it.`);
+    }
+    const pullRequest = pullRequestIn(said);
+    if (!pullRequest) {
+        throw new Error(`${unrecorded}: the app gave no pull request.`);
+    }
+    return pullRequest;
+}
+function pullRequestIn(said) {
+    return said.url && typeof said.number === "number"
+        ? { url: said.url, number: said.number }
+        : null;
+}
+/**
+ * Ask the app's pull-request route, on the project's credentials: with the
+ * outcome, to open the pull request it is kept on; with a number, to check
+ * that one is the solution's open pull request, which needs no outcome.
+ */
+async function ask(body) {
+    const { projectId, projectSecret } = getProjectCredentials();
+    const base = webApiUrl();
+    const response = await fetch(`${base}/api/solutions/pull-request`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ projectId, projectSecret, ...body }),
+    });
+    const said = (await response.json().catch(() => ({})));
+    if (!response.ok) {
+        throw new Error(`Couldn't ask the app for the solution's pull request: ${said.error ?? `the app answered ${response.status}`}.`);
+    }
+    return said;
+}
+//# sourceMappingURL=pull-request.js.map

package/dist/commands/solution/pushing.d.ts

@@ -0,0 +1,66 @@
+import type { solutionClient } from "./client.js";
+import type { Where } from "./run-file.js";
+/**
+ * A solution's branch as the verbs work it inside a runner (SOLBRANCH):
+ * the checkout the runner starts each session with, the push before a
+ * record is kept, the push when a session ends, and what a submission is
+ * refused for. Outside a runner the run names no branch and none of this
+ * happens: a person pushes their own branches.
+ */
+type Client = ReturnType<typeof solutionClient>;
+/**
+ * Whether the agent's work reached the solution's branch. When it didn't,
+ * `why` fits after "the work could not be pushed:", for a stall's reason
+ * (SOLBRANCH-3.4, 4.1), and `tell` is what the agent is told when its
+ * record is refused (3.2, 3.3).
+ */
+export type PushOutcome = {
+    ok: true;
+    pushed: boolean;
+} | {
+    ok: false;
+    why: string;
+    tell: string;
+};
+/**
+ * Push what the agent committed to the solution's branch, its commits
+ * after any other agents pushed since, and keep the push on the solution
+ * (SOLBRANCH-3.0, 3.1, 4.0; REHEARSE-6.8). Nothing is committed here: what
+ * the agent left uncommitted stays so (SOLBRANCH-6.0).
+ *
+ * A checkout on another branch than the solution's has nothing it may
+ * push: its commits are refused until they are on the solution's branch,
+ * and a checkout with none of its own passes.
+ */
+export declare function pushWork(client: Client, where: {
+    solutionId: string;
+    branch: string;
+}, cwd?: string): Promise<PushOutcome>;
+/** Push before a record, or refuse it with what the agent is to do (SOLBRANCH-3). */
+export declare function pushBeforeRecord(client: Client, where: Where): Promise<void>;
+/**
+ * What a submission is refused for inside a runner (SOLBRANCH-5): a file it
+ * submits that has changes not committed, or is new and not committed
+ * (5.0), and other files git tracks with changes not committed (5.1). New
+ * files it neither commits nor submits, such as a screenshot, pass (5.2).
+ * And a checkout on another branch than the solution's, since a file is
+ * recorded on the branch the checkout is on (VERB-1.4).
+ */
+export declare function refuseUncommitted(where: Where & {
+    branch: string;
+}, submitted: string[], cwd?: string): void;
+/**
+ * The checkout a session starts with (SOLBRANCH-1, 2): on the solution's
+ * branch — made now, on its first session, from the default branch, or
+ * from the branch a rehearsal's scenario named (REHEARSE-4.5) — with what
+ * other agents pushed to it brought in. Returns the branch, and what the
+ * agent is to be told before its brief, if anything.
+ */
+export declare function checkOutSolution(client: Client, solutionId: string, cwd?: string, 
+/** The outcome the session works, whose surface's branch it is on (SOLBRANCH-1.5). */
+outcome?: string): Promise<{
+    branch: string;
+    notice: string | null;
+}>;
+export {};
+//# sourceMappingURL=pushing.d.ts.map

package/dist/commands/solution/pushing.js

@@ -0,0 +1,185 @@
+import { api } from "../../convex.js";
+import { branchCommit, branchHead, checkOut, currentBranch, defaultBranchCommit, freeName, git, pushTo, remoteBranches, uncommitted, } from "./branch.js";
+/**
+ * Push what the agent committed to the solution's branch, its commits
+ * after any other agents pushed since, and keep the push on the solution
+ * (SOLBRANCH-3.0, 3.1, 4.0; REHEARSE-6.8). Nothing is committed here: what
+ * the agent left uncommitted stays so (SOLBRANCH-6.0).
+ *
+ * A checkout on another branch than the solution's has nothing it may
+ * push: its commits are refused until they are on the solution's branch,
+ * and a checkout with none of its own passes.
+ */
+export async function pushWork(client, where, cwd = process.cwd()) {
+    const { branch } = where;
+    const on = currentBranch(cwd);
+    if (on !== branch) {
+        if (!hasOwnCommits(cwd, branch))
+            return { ok: true, pushed: false };
+        return offBranch(on, branch);
+    }
+    const pushed = pushTo(cwd, branch);
+    switch (pushed.kind) {
+        case "pushed":
+            await client.mutation(api.solutions.branches.recordPush, {
+                solutionId: where.solutionId,
+                branch,
+                before: pushed.before,
+                after: pushed.after,
+            });
+            return { ok: true, pushed: true };
+        case "nothing to push":
+            return { ok: true, pushed: false };
+        case "conflict": {
+            const files = pushed.files.join(", ");
+            return {
+                ok: false,
+                why: `commits other agents pushed to ${branch} conflict with it in ${files}`,
+                tell: [
+                    `Nothing was recorded: commits other agents pushed to ${branch} conflict with yours in ${files}.`,
+                    `Bring the branch's commits in (git pull --rebase --autostash origin ${branch}), resolve the conflicts, and record again.`,
+                ].join("\n"),
+            };
+        }
+        case "refused":
+            return {
+                ok: false,
+                why: `the repository refused it: ${pushed.reason}`,
+                tell: `Nothing was recorded: the repository refused the push to ${branch}: ${pushed.reason}`,
+            };
+    }
+}
+/** Whether the checkout has commits the solution's branch doesn't. */
+function hasOwnCommits(cwd, branch) {
+    fetchQuietly(cwd, branch);
+    const upstream = `refs/remotes/origin/${branch}`;
+    const ran = git(cwd, ["rev-list", "--count", `${upstream}..HEAD`]);
+    return ran.code !== 0 || Number(ran.stdout.trim()) > 0;
+}
+/** Fetch the branch without touching the checkout. */
+function fetchQuietly(cwd, branch) {
+    git(cwd, [
+        "fetch",
+        "--quiet",
+        "origin",
+        `+refs/heads/${branch}:refs/remotes/origin/${branch}`,
+    ]);
+}
+function offBranch(on, branch) {
+    const where = on ? `on ${on}` : "on no branch";
+    return {
+        ok: false,
+        why: `the checkout is ${where}, not the solution's branch ${branch}`,
+        tell: [
+            `Nothing was recorded: your checkout is ${where}, not the solution's branch ${branch}, which is where your work is pushed and read from.`,
+            `Switch back to ${branch} and bring your commits there (git checkout ${branch} && git merge ${on ?? "<your commit>"}), then record again.`,
+        ].join("\n"),
+    };
+}
+/** Push before a record, or refuse it with what the agent is to do (SOLBRANCH-3). */
+export async function pushBeforeRecord(client, where) {
+    if (!where.branch)
+        return;
+    const outcome = await pushWork(client, {
+        solutionId: where.solutionId,
+        branch: where.branch,
+    });
+    if (!outcome.ok)
+        throw new Error(outcome.tell);
+}
+/**
+ * What a submission is refused for inside a runner (SOLBRANCH-5): a file it
+ * submits that has changes not committed, or is new and not committed
+ * (5.0), and other files git tracks with changes not committed (5.1). New
+ * files it neither commits nor submits, such as a screenshot, pass (5.2).
+ * And a checkout on another branch than the solution's, since a file is
+ * recorded on the branch the checkout is on (VERB-1.4).
+ */
+export function refuseUncommitted(where, submitted, cwd = process.cwd()) {
+    const on = currentBranch(cwd);
+    if (on !== where.branch) {
+        throw new Error(offBranch(on, where.branch).tell);
+    }
+    const { changed, untracked } = uncommitted(cwd);
+    const within = (file, path) => file === path || file.startsWith(`${path.replace(/\/+$/, "")}/`);
+    const paths = submitted.map((path) => path.replace(/^\.\//, ""));
+    const submittedFile = (file) => paths.some((path) => within(file, path));
+    const notCommitted = [...changed, ...untracked].filter(submittedFile);
+    if (notCommitted.length > 0) {
+        throw new Error(`Nothing was recorded: commit ${listed(notCommitted)} first. Your work is read from ${where.branch}, where only what you commit is pushed.`);
+    }
+    const others = changed.filter((file) => !submittedFile(file));
+    if (others.length > 0) {
+        throw new Error(`Nothing was recorded: ${listed(others)} ${others.length === 1 ? "has changes" : "have changes"} you haven't committed. Commit them or undo them first, then submit again.`);
+    }
+}
+/**
+ * The checkout a session starts with (SOLBRANCH-1, 2): on the solution's
+ * branch — made now, on its first session, from the default branch, or
+ * from the branch a rehearsal's scenario named (REHEARSE-4.5) — with what
+ * other agents pushed to it brought in. Returns the branch, and what the
+ * agent is to be told before its brief, if anything.
+ */
+export async function checkOutSolution(client, solutionId, cwd = process.cwd(), 
+/** The outcome the session works, whose surface's branch it is on (SOLBRANCH-1.5). */
+outcome) {
+    const recorded = await client.query(api.solutions.branches.branchOf, { solutionId, ...(outcome ? { outcome } : {}) });
+    const branch = recorded.branch;
+    if (!branch) {
+        const made = await makeSolutionBranch(client, solutionId, recorded, cwd, outcome);
+        return { branch: made, notice: checkOut(cwd, made) };
+    }
+    // Claimed, and nothing pushed to it yet: another first session claimed it
+    // a moment ago and may still be making it (SOLBRANCH-1.3). Whatever the
+    // repository has by that name now is the solution's, by its record.
+    if (recorded.commits?.length === 1) {
+        branchHead(cwd, branch, recorded.commits[0]);
+    }
+    return { branch, notice: checkOut(cwd, branch) };
+}
+/**
+ * Make the solution's branch from the default branch as it stands now, or
+ * from `baseBranch` when a rehearsal's scenario named one (REHEARSE-4.5),
+ * named for its directory, suffixed past any name a branch already has
+ * (SOLBRANCH-1.0, 1.1). The name is claimed on the solution before the
+ * branch is made, so two first sessions arriving together are given the
+ * one name and the one commit, and both work on the one branch (1.3):
+ * whichever pushes second finds it already made, by the solution.
+ */
+async function makeSolutionBranch(client, solutionId, recorded, cwd, outcome) {
+    const { directory } = recorded;
+    const claim = (args) => client.mutation(api.solutions.branches.claim, {
+        solutionId,
+        ...(outcome ? { outcome } : {}),
+        ...args,
+    });
+    const base = recorded.baseBranch
+        ? branchCommit(cwd, recorded.baseBranch)
+        : defaultBranchCommit(cwd);
+    let claimed = await claim({
+        name: freeName(directory, remoteBranches(cwd)),
+        base,
+    });
+    for (let attempt = 0; attempt < 5; attempt++) {
+        // The solution's when it is at a commit its agents left it at: made
+        // now, or by the other first session that claimed it.
+        const head = branchHead(cwd, claimed.name, claimed.base);
+        if (claimed.commits.includes(head))
+            return claimed.name;
+        // A branch the solution didn't make took the name after it was found
+        // free: the claim moves to the next name no branch has (1.1).
+        const taken = remoteBranches(cwd).add(claimed.name);
+        claimed = await claim({
+            name: freeName(directory, taken),
+            base: claimed.base,
+            replacing: claimed.name,
+        });
+    }
+    throw new Error(`Couldn't make a branch for the solution: other branches named dotreq/${directory} kept appearing.`);
+}
+function listed(names) {
+    return names.length <= 1
+        ? (names[0] ?? "")
+        : `${names.slice(0, -1).join(", ")} and ${names.at(-1)}`;
+}
+//# sourceMappingURL=pushing.js.map