@popoverai/dotrequirements 0.32.1 → 0.34.0

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

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

@@ -0,0 +1,10 @@
+/**
+ * `dotreq solution rehearse <scenario.yaml>` (REHEARSE-4): run a scenario
+ * against the linked project, real parties awaited, and print how it went.
+ * The scenario's earlier runs are removed first, unless `--keep` says to
+ * leave them for comparing (REHEARSE-6).
+ */
+export declare function rehearseCommand(path: string, options?: {
+    keep?: boolean;
+}): Promise<void>;
+//# sourceMappingURL=rehearse.d.ts.map

package/dist/commands/solution/rehearse.js

@@ -0,0 +1,24 @@
+import { checkScenario, rehearse } from "../../rehearsal/driver.js";
+import { removeEarlierRuns } from "../../rehearsal/earlier.js";
+import { liveClient, scenarioFrom } from "../../rehearsal/live.js";
+import { renderReport } from "../../rehearsal/report.js";
+import { solutionClient } from "./client.js";
+/**
+ * `dotreq solution rehearse <scenario.yaml>` (REHEARSE-4): run a scenario
+ * against the linked project, real parties awaited, and print how it went.
+ * The scenario's earlier runs are removed first, unless `--keep` says to
+ * leave them for comparing (REHEARSE-6).
+ */
+export async function rehearseCommand(path, options = {}) {
+    const client = solutionClient();
+    const scenario = await scenarioFrom(path, client);
+    checkScenario(scenario);
+    const earlier = options.keep
+        ? { scenario: scenario.file ?? path, removed: 0, keep: true, kept: [] }
+        : await removeEarlierRuns(path, client);
+    const report = await rehearse(liveClient(), scenario);
+    process.stdout.write(renderReport({ ...report, earlier }));
+    if (!/^nothing ready$/.test(report.ended))
+        process.exitCode = 3;
+}
+//# sourceMappingURL=rehearse.js.map

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

@@ -0,0 +1,3 @@
+/** A decision request from the JSON file an agent wrote. The backend validates it against the contract. */
+export declare function readRequest(file: string): unknown;
+//# sourceMappingURL=request.d.ts.map

package/dist/commands/solution/request.js

@@ -0,0 +1,13 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+/** A decision request from the JSON file an agent wrote. The backend validates it against the contract. */
+export function readRequest(file) {
+    const text = readFileSync(resolve(process.cwd(), file), "utf8");
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        throw new Error(`${file} isn't JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+//# sourceMappingURL=request.js.map

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

@@ -0,0 +1,27 @@
+import { type WhereOptions } from "./run-file.js";
+import { type SummaryOptions } from "./summary.js";
+export type ReviewOptions = WhereOptions & SummaryOptions & {
+    /** What should change, what was checked, or what the owner is to decide: required for every result (VERB-2.0, 2.1, 2.4). */
+    comment?: string;
+    /**
+     * With an approval of a demo's script: the video recorded from it and
+     * the script as the reviewer left it, each `"video:<video> <steps
+     * file>"`, given after the result on the command line (SIGHT-13.2).
+     */
+    videos?: string[];
+};
+/**
+ * `dotreq solution review <result> --comment "..."`: the reviewer's
+ * result on the outcome it is reviewing, or on the one `--outcome` names.
+ * The comment is what the next reader of the thread sees first — the
+ * drafter works from it, and on an escalation it is the note the owner
+ * reads — so every result is refused without one before anything is
+ * recorded (VERB-2.0, 2.1, 2.4). An approval also carries an executive
+ * summary, `--executive-summary "..."`, which is what the owner reads with
+ * the work (VERB-2.5); the outcome's own rules decide what follows. An
+ * approval of a demo's script carries the video the reviewer recorded from
+ * it, `"video:<video> <steps file>"`, which takes the script's place
+ * (SIGHT-13.2); no other result carries one (13.4.0).
+ */
+export declare function reviewCommand(result: string, options: ReviewOptions): Promise<void>;
+//# sourceMappingURL=review.d.ts.map

package/dist/commands/solution/review.js

@@ -0,0 +1,104 @@
+import { api } from "../../convex.js";
+import { solutionClient } from "./client.js";
+import { pushBeforeRecord } from "./pushing.js";
+import { onOutcome, requireWhere } from "./run-file.js";
+import { summaryGiven } from "./summary.js";
+import { parseThing } from "./things.js";
+import { readRecording, submittedRecording } from "./video.js";
+/** What an agent types, and the result in the words the outcome keeps. */
+const RESULTS = {
+    approved: "approved",
+    "approved-with-revisions": "approved with revisions",
+    "needs-revision": "needs revision",
+    escalate: "escalate",
+};
+/**
+ * `dotreq solution review <result> --comment "..."`: the reviewer's
+ * result on the outcome it is reviewing, or on the one `--outcome` names.
+ * The comment is what the next reader of the thread sees first — the
+ * drafter works from it, and on an escalation it is the note the owner
+ * reads — so every result is refused without one before anything is
+ * recorded (VERB-2.0, 2.1, 2.4). An approval also carries an executive
+ * summary, `--executive-summary "..."`, which is what the owner reads with
+ * the work (VERB-2.5); the outcome's own rules decide what follows. An
+ * approval of a demo's script carries the video the reviewer recorded from
+ * it, `"video:<video> <steps file>"`, which takes the script's place
+ * (SIGHT-13.2); no other result carries one (13.4.0).
+ */
+export async function reviewCommand(result, options) {
+    const outcome = RESULTS[result];
+    if (!outcome) {
+        throw new Error(`A review result is approved, approved-with-revisions, needs-revision or escalate, not "${result}".`);
+    }
+    const comment = options.comment?.trim();
+    if (!comment) {
+        throw new Error(outcome === "approved"
+            ? "Say what you checked: your comment is what the next reader sees first."
+            : outcome === "escalate"
+                ? "Say what the owner is to decide: your comment is the note they read with the work."
+                : "Say what should change: the drafter works from your comment.");
+    }
+    // VERB-2.5, 2.5.0: an approval carries an executive summary for the
+    // owner, and nothing else does; refused before anything is recorded, in
+    // the backend's words.
+    const summary = summaryGiven(options);
+    const approving = outcome === "approved" || outcome === "approved with revisions";
+    if (approving && !summary) {
+        throw new Error("Write an executive summary for the owner with --executive-summary: it's what they read first. Say what this is and what most needs their eye, as the work will stand once any fixes you asked for are made.");
+    }
+    if (!approving && summary) {
+        throw new Error(`Only an approval carries an executive summary, so nothing was recorded. Leave --executive-summary off: ${outcome === "escalate" ? "your comment is the note the owner reads." : "the drafter works from your comment."}`);
+    }
+    // SIGHT-13.2, 13.4.0: a video goes only with a plain approval, and is
+    // read before anything is pushed, uploaded or recorded.
+    const recordings = readVideos(options.videos ?? []);
+    if (recordings.length > 0 && outcome !== "approved") {
+        throw new Error(outcome === "approved with revisions"
+            ? "Nothing was recorded: a demo's script isn't approved with revisions, because its drafter can't change the script without the video going out of step. Fix anything small yourself, record the video, and approve with it, saying in your comment what you changed; or give needs-revision."
+            : `Nothing was recorded: only an approval carries a video. Give your result without it: ${outcome === "escalate" ? "your comment is the note the owner reads" : "the drafter works from your comment"}, and no video is kept.`);
+    }
+    const where = requireWhere(options);
+    const { solutionId, agent } = where;
+    const client = solutionClient();
+    // SOLBRANCH-3.0: what the reviewer committed reaches the branch first.
+    await pushBeforeRecord(client, where);
+    const videos = [];
+    for (const recording of recordings) {
+        videos.push(await submittedRecording(client, solutionId, recording));
+    }
+    const args = {
+        solutionId,
+        agent,
+        ...(where.outcome ? { outcome: where.outcome } : {}),
+        review: {
+            outcome,
+            comment,
+            ...(summary ? { summary } : {}),
+            ...(videos.length ? { videos } : {}),
+        },
+    };
+    const said = await client.mutation(api.solutions.mutations.complete, args);
+    // STEP-REVIEW-18.7.0: the drafter submitted again after this review began.
+    // Nothing was recorded; the words say what changed and to give the result
+    // again once the reviewer has looked.
+    if (said?.refused)
+        throw new Error(said.refused);
+    console.log(outcome === "escalate"
+        ? `Escalated${onOutcome(where.outcome)}. It waits on the owner's decision.`
+        : `Recorded your review${onOutcome(where.outcome)}: ${outcome}.`);
+}
+/**
+ * The videos a review carries (SIGHT-13.2): each recorded from a demo's
+ * script, named as the drafter names one, `"video:<video> <steps file>"`.
+ * Nothing else goes with a review.
+ */
+function readVideos(references) {
+    return references.map((reference) => {
+        const thing = parseThing(reference);
+        if (thing.kind !== "video") {
+            throw new Error(`Nothing was recorded: a review carries no "${reference}". The one thing it carries is the video you recorded from a demo's script, with your approval: "video:<video> <steps file>".`);
+        }
+        return readRecording(thing.path, thing.scriptPath);
+    });
+}
+//# sourceMappingURL=review.js.map