@popoverai/dotrequirements 0.32.1 → 0.34.0

package/dist/commands/solution/author.js

@@ -0,0 +1,202 @@
+import { realpathSync } from "node:fs";
+import { isAbsolute, relative, resolve } from "node:path";
+import { api } from "../../convex.js";
+import { currentBranch, headCommit, repositoryRoot } from "./branch.js";
+import { solutionClient } from "./client.js";
+import { readImage, uploadImage } from "./image.js";
+import { screenshotPreview } from "./preview-screenshot.js";
+import { checkPullRequest } from "./pull-request.js";
+import { pushBeforeRecord, refuseUncommitted } from "./pushing.js";
+import { onOutcome, requireWhere } from "./run-file.js";
+import { summaryGiven } from "./summary.js";
+import { parseThing, REFERENCE_FORMS } from "./things.js";
+import { readDemoScript, readRecording, submittedRecording, } from "./video.js";
+import { readSubmittedFiles, recordSavedIds, } from "./working-folder.js";
+/**
+ * `dotreq solution author <reference>... --comment "<what changed and why>"`:
+ * the drafter's submission of the outcome it is drafting, or of the one
+ * `--outcome` names. The references say where what it made is; the comment
+ * is what the next reader of the thread sees first, so nothing is recorded
+ * without it (VERB-1.2). On an outcome no agent reviews, the work goes to
+ * the owner with the executive summary, `--executive-summary "..."`, which
+ * the backend asks for there (VERB-1.6).
+ */
+export async function authorCommand(references, options) {
+    if (references.length === 0) {
+        throw new Error("Name where what you made is: dotreq solution author <reference>... — `dotreq solution author --help` gives the forms.");
+    }
+    const comment = options.comment?.trim();
+    if (!comment) {
+        throw new Error("Say what changed and why: your comment is what the next reader sees first.");
+    }
+    const where = requireWhere(options);
+    const made = references.map(parseThing);
+    // SIGHT-12.3, 12.3.0: each reference's title, matched to it by order
+    // before anything is read, pushed, uploaded or recorded.
+    const titles = titleReferences(made, options.title ?? []);
+    // SIGHT-7.0.0, 7.0.1, 9.0.0, 13.0: a video and its script, a demo's
+    // script, and an image, are read first, so one a browser can't show, or
+    // a script that isn't one, is refused before anything is pushed,
+    // uploaded or recorded.
+    const videos = new Map();
+    const demoScripts = new Map();
+    const images = new Map();
+    for (const thing of made) {
+        if (thing.kind === "video") {
+            videos.set(thing, readRecording(thing.path, thing.scriptPath));
+        }
+        if (thing.kind === "demo script") {
+            demoScripts.set(thing, readDemoScript(thing.path));
+        }
+        if (thing.kind === "image")
+            images.set(thing, readImage(thing.path));
+    }
+    // VERB-1.4, 1.5: a file named without its branch is on the branch the
+    // checkout is on, or on none.
+    const cwd = process.cwd();
+    refuseOutsideCheckout(made, cwd);
+    const checkout = currentBranch(cwd);
+    const fromCheckout = (thing) => thing.kind === "file" &&
+        (thing.branch === undefined || thing.branch === checkout);
+    // PULL-3.0, 3.2: the pull request named is the solution's, open from its
+    // branch, checked before anything is pushed or recorded.
+    const pullRequests = new Map();
+    for (const thing of made) {
+        if (thing.kind === "pull request") {
+            pullRequests.set(thing, await checkPullRequest(where, thing.number));
+        }
+    }
+    const client = solutionClient();
+    if (where.branch) {
+        // Inside a runner: only what is committed is submitted (SOLBRANCH-5),
+        // and it reaches the solution's branch before the record is kept (3.0).
+        refuseUncommitted({ ...where, branch: where.branch }, made.flatMap((thing) => fromCheckout(thing) && thing.kind === "file" ? [thing.path] : []));
+        await pushBeforeRecord(client, where);
+    }
+    // SOLDOC-12.2.0: a file from the checkout's own branch keeps the commit
+    // it was submitted at, so the page can tell when it changes after.
+    const commit = checkout ? headCommit(cwd) : null;
+    /** A reference as it is submitted: where the thing is, as the backend keeps it. */
+    const submissionOf = async (thing) => {
+        const recording = videos.get(thing);
+        if (recording) {
+            // SIGHT-7.0, 7.4: the app keeps a copy of the video, the script's
+            // text and where each of its steps begins; nothing goes on the
+            // branch.
+            return submittedRecording(client, where.solutionId, recording);
+        }
+        const demoScript = demoScripts.get(thing);
+        if (demoScript) {
+            // SIGHT-13.0: the app keeps the script's text for the agent
+            // reviewing it to record; nothing goes on the branch.
+            return { kind: "demo script", ...demoScript };
+        }
+        const image = images.get(thing);
+        if (image) {
+            // SIGHT-9.0: the app keeps a copy of the image; nothing goes on the
+            // branch.
+            const storageId = await uploadImage(client, where.solutionId, image);
+            return { kind: "image", storageId, name: image.name };
+        }
+        const pullRequest = pullRequests.get(thing);
+        if (pullRequest)
+            return { kind: "pull request", ...pullRequest };
+        if (thing.kind === "preview") {
+            // SIGHT-12.0, 12.2: a screenshot of the page it opens on, kept as an
+            // image is; without one, it is submitted all the same.
+            const shot = await screenshotPreview(thing);
+            if ("image" in shot) {
+                const screenshot = await uploadImage(client, where.solutionId, shot.image);
+                return { ...thing, screenshot };
+            }
+            console.error(`No screenshot of preview:${thing.port}${thing.page ?? ""} was taken (${shot.missed}); its tab says so. Submit it again once it answers to add one.`);
+            return thing;
+        }
+        return checkout && fromCheckout(thing)
+            ? { ...thing, branch: checkout, ...(commit ? { commit } : {}) }
+            : thing;
+    };
+    const submitted = [];
+    for (const thing of made) {
+        // SIGHT-12.3: the title given for it goes with it, whatever its kind.
+        const title = titles.get(thing);
+        submitted.push({
+            ...(await submissionOf(thing)),
+            ...(title ? { title } : {}),
+        });
+    }
+    // A document submitted by its file goes with its text when there is no
+    // git checkout: on a project with no repository connected, the backend
+    // saves it on the solution's branch (BRANCH-1.0).
+    const files = checkout ? [] : readSubmittedFiles(made);
+    // VERB-1.6: on an outcome no agent reviews, the owner reads the executive
+    // summary first. Only the backend knows whether one does, so it is the
+    // backend that refuses the work without one.
+    const summary = summaryGiven(options);
+    const args = {
+        solutionId: where.solutionId,
+        agent: where.agent,
+        ...(where.outcome ? { outcome: where.outcome } : {}),
+        made: submitted,
+        comment,
+        ...(summary ? { summary } : {}),
+        ...(files.length ? { files } : {}),
+    };
+    const result = await client.mutation(api.solutions.mutations.complete, args);
+    const saved = result?.saved ?? [];
+    recordSavedIds(files, saved);
+    for (const entry of saved) {
+        console.log(`Saved ${entry.path} on the solution's branch as version ${entry.version}.`);
+    }
+    // CHECKPOINT-6.3.2.3: work begun before the outcome was set to be
+    // drafted again is kept, but isn't its new draft; the agent is told so.
+    if (result?.setAside) {
+        console.log(result.setAside);
+        return;
+    }
+    console.log(`Recorded your work${onOutcome(where.outcome)}.`);
+}
+/**
+ * SOLBRANCH-5.3: a file is submitted by where it is in the repository, so
+ * one from outside the checkout, such as a video written under /tmp, would
+ * be recorded at a path nobody can open. Refused, with the other forms, so
+ * the agent finds the one it meant.
+ */
+function refuseOutsideCheckout(made, cwd) {
+    const root = repositoryRoot(cwd);
+    if (!root)
+        return;
+    const top = realpathSync(root);
+    const here = realpathSync(cwd);
+    const outside = made.flatMap((thing) => {
+        if (thing.kind !== "file")
+            return [];
+        const within = relative(top, resolve(here, thing.path));
+        return within.startsWith("..") || isAbsolute(within) ? [thing.path] : [];
+    });
+    if (outside.length === 0)
+        return;
+    throw new Error(`Nothing was recorded: ${outside.join(", ")} ${outside.length === 1 ? "is" : "are"} outside your checkout, and only files in the repository are submitted as files. ${REFERENCE_FORMS}`);
+}
+/**
+ * SIGHT-12.3, 12.3.0, 12.3.1: the title each reference is submitted with,
+ * its name on the outcome's tab, given as one `--title` per reference in the
+ * order the references are named, as `git commit -m` takes one per
+ * paragraph. None given, each keeps the name the tab gives it; a count that
+ * doesn't match submits nothing. A blank title is none, for that reference
+ * alone.
+ */
+function titleReferences(made, given) {
+    if (given.length > 0 && given.length !== made.length) {
+        const count = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+        throw new Error(`You named ${count(made.length, "reference", "references")} and gave ${count(given.length, "--title", "--titles")}, so nothing was submitted. Give one --title per reference, in the order you name them, or none.`);
+    }
+    const titles = new Map();
+    given.forEach((text, at) => {
+        const title = text.trim();
+        if (title)
+            titles.set(made[at], title);
+    });
+    return titles;
+}
+//# sourceMappingURL=author.js.map

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

@@ -0,0 +1,103 @@
+/**
+ * The git a solution's branch needs (SOLBRANCH): which branch a checkout
+ * is on, what it has not committed, bringing the branch's new commits in
+ * under the agent's own, and pushing. Every function runs git in the
+ * directory it is given and never commits: what an agent has not committed
+ * stays uncommitted, in its checkout (SOLBRANCH-6).
+ */
+type Ran = {
+    code: number;
+    stdout: string;
+    stderr: string;
+};
+export declare function git(cwd: string, args: string[]): Ran;
+/** Git's name for no commit: a push's `before` when the branch wasn't in the repository. */
+export declare const NO_COMMIT = "0000000000000000000000000000000000000000";
+/**
+ * The branch the checkout is on, or null when it is on no branch — a
+ * single commit checked out, or no git repository at all (VERB-1.4, 1.5).
+ */
+export declare function currentBranch(cwd: string): string | null;
+/** The top of the repository the checkout is in, or null outside one. */
+export declare function repositoryRoot(cwd: string): string | null;
+/** The commit the checkout is at, or null outside a git repository. */
+export declare function headCommit(cwd: string): string | null;
+/**
+ * What the checkout has not committed: files git tracks with changes,
+ * staged or not, and new files it does not ignore, one by one.
+ */
+export declare function uncommitted(cwd: string): {
+    changed: string[];
+    untracked: string[];
+};
+export type BroughtIn = {
+    ok: true;
+} | {
+    ok: false;
+    conflicts: string[];
+} | {
+    ok: false;
+    problem: string;
+};
+/**
+ * Bring the branch's new commits into the checkout, the agent's own
+ * commits placed after them (SOLBRANCH-2, 3.1). When they conflict — with
+ * a commit of the agent's, or with a change it has not committed — the
+ * checkout is left exactly as it was, and the files that conflict are
+ * named (SOLBRANCH-2.3, 3.2). What it has not committed stays uncommitted.
+ */
+export declare function bringIn(cwd: string, branch: string): BroughtIn;
+export type Pushed = {
+    kind: "pushed";
+    before: string;
+    after: string;
+} | {
+    kind: "nothing to push";
+} | {
+    kind: "conflict";
+    files: string[];
+} | {
+    kind: "refused";
+    reason: string;
+};
+/**
+ * Push the checkout's commits to the solution's branch, after bringing in
+ * what other agents pushed since (SOLBRANCH-3.1). A push that loses a race
+ * with another agent's tries again; one the repository refuses comes back
+ * with the reason it gave (3.3).
+ */
+export declare function pushTo(cwd: string, branch: string): Pushed;
+/** The names of the repository's branches, as it has them now. */
+export declare function remoteBranches(cwd: string): Set<string>;
+/**
+ * The name for a solution's new branch: `dotreq/<directory>`, or, when a
+ * branch already has that name, the lowest suffix from -2 up that none has
+ * (SOLBRANCH-1.0, 1.1).
+ */
+export declare function freeName(directory: string, taken: Set<string>): string;
+/** The default branch's commit, as the repository has it now, fetched into the checkout. */
+export declare function defaultBranchCommit(cwd: string): string;
+/**
+ * The commit a named branch is at, as the repository has it now, fetched
+ * into the checkout: what a solution's branch is made from when a
+ * rehearsal's scenario names the branch to start from (REHEARSE-4.5).
+ */
+export declare function branchCommit(cwd: string, branch: string): string;
+/**
+ * The commit the repository's branch `name` is at, making the branch at
+ * `base` first when the repository has none of that name (SOLBRANCH-1.0,
+ * 1.3). A branch of that name that appears first — another of the
+ * solution's first sessions making it a moment before, or anyone's — is
+ * never moved: its commit is read and returned, for the caller to judge
+ * whose it is.
+ */
+export declare function branchHead(cwd: string, name: string, base: string): string;
+/**
+ * Put the checkout on the solution's branch, and bring in what other steps
+ * pushed to it (SOLBRANCH-1.2, 2). Returns what the agent should be told,
+ * or null when there is nothing to tell: its checkout is on the branch and
+ * holds everything pushed to it.
+ */
+export declare function checkOut(cwd: string, branch: string): string | null;
+export {};
+//# sourceMappingURL=branch.d.ts.map

package/dist/commands/solution/branch.js

@@ -0,0 +1,341 @@
+import { spawnSync } from "node:child_process";
+export function git(cwd, args) {
+    const ran = spawnSync("git", args, {
+        cwd,
+        encoding: "utf8",
+        // A push that wants a password fails rather than waiting for one.
+        env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+    });
+    return {
+        code: ran.status ?? 1,
+        stdout: ran.stdout ?? "",
+        stderr: ran.stderr ?? "",
+    };
+}
+/** Git's name for no commit: a push's `before` when the branch wasn't in the repository. */
+export const NO_COMMIT = "0000000000000000000000000000000000000000";
+/**
+ * The branch the checkout is on, or null when it is on no branch — a
+ * single commit checked out, or no git repository at all (VERB-1.4, 1.5).
+ */
+export function currentBranch(cwd) {
+    const ran = git(cwd, ["symbolic-ref", "--quiet", "--short", "HEAD"]);
+    return ran.code === 0 ? ran.stdout.trim() || null : null;
+}
+/** The top of the repository the checkout is in, or null outside one. */
+export function repositoryRoot(cwd) {
+    const ran = git(cwd, ["rev-parse", "--show-toplevel"]);
+    return ran.code === 0 ? ran.stdout.trim() || null : null;
+}
+/** The commit the checkout is at, or null outside a git repository. */
+export function headCommit(cwd) {
+    const ran = git(cwd, ["rev-parse", "--verify", "--quiet", "HEAD"]);
+    return ran.code === 0 ? ran.stdout.trim() || null : null;
+}
+function commitOf(cwd, ref) {
+    const ran = git(cwd, ["rev-parse", "--verify", "--quiet", ref]);
+    return ran.code === 0 ? ran.stdout.trim() || null : null;
+}
+function isAncestor(cwd, a, b) {
+    return git(cwd, ["merge-base", "--is-ancestor", a, b]).code === 0;
+}
+/**
+ * What the checkout has not committed: files git tracks with changes,
+ * staged or not, and new files it does not ignore, one by one.
+ */
+export function uncommitted(cwd) {
+    const ran = git(cwd, [
+        "status",
+        "--porcelain=v1",
+        "-z",
+        "--untracked-files=all",
+    ]);
+    const changed = [];
+    const untracked = [];
+    const entries = ran.stdout.split("\0");
+    for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i];
+        if (entry.length < 4)
+            continue;
+        const status = entry.slice(0, 2);
+        const path = entry.slice(3);
+        if (status === "??") {
+            untracked.push(path);
+            continue;
+        }
+        changed.push(path);
+        // A rename or copy names where it came from next; that path changed too.
+        if (status[0] === "R" || status[0] === "C") {
+            const from = entries[++i];
+            if (from)
+                changed.push(from);
+        }
+    }
+    return { changed, untracked };
+}
+/** The remote-tracking ref a solution's branch is fetched into. */
+function upstreamOf(branch) {
+    return `refs/remotes/origin/${branch}`;
+}
+/** Fetch the branch as the repository has it now; false when the repository has no such branch. */
+function fetchBranch(cwd, branch) {
+    const ran = git(cwd, [
+        "fetch",
+        "--quiet",
+        "origin",
+        `+refs/heads/${branch}:${upstreamOf(branch)}`,
+    ]);
+    if (ran.code === 0)
+        return { ok: true, there: true };
+    if (/couldn't find remote ref/i.test(ran.stderr)) {
+        // Gone from the repository: so is what the checkout remembered of it.
+        git(cwd, ["update-ref", "-d", upstreamOf(branch)]);
+        return { ok: true, there: false };
+    }
+    return { ok: false, problem: lastLines(ran.stderr || ran.stdout) };
+}
+/**
+ * Bring the branch's new commits into the checkout, the agent's own
+ * commits placed after them (SOLBRANCH-2, 3.1). When they conflict — with
+ * a commit of the agent's, or with a change it has not committed — the
+ * checkout is left exactly as it was, and the files that conflict are
+ * named (SOLBRANCH-2.3, 3.2). What it has not committed stays uncommitted.
+ */
+export function bringIn(cwd, branch) {
+    const fetched = fetchBranch(cwd, branch);
+    if (!fetched.ok)
+        return fetched;
+    if (!fetched.there)
+        return { ok: true };
+    const upstream = upstreamOf(branch);
+    if (isAncestor(cwd, upstream, "HEAD"))
+        return { ok: true };
+    // A change not committed can't be carried over a commit that touches the
+    // same file without conflicting, so that is a conflict before anything
+    // moves; nor can a new file the branch now adds.
+    const incoming = new Set(git(cwd, ["diff", "--name-only", "-z", `HEAD...${upstream}`])
+        .stdout.split("\0")
+        .filter(Boolean));
+    const { changed, untracked } = uncommitted(cwd);
+    const clashing = [...changed, ...untracked].filter((path) => incoming.has(path));
+    if (clashing.length > 0)
+        return { ok: false, conflicts: clashing.sort() };
+    if (isAncestor(cwd, "HEAD", upstream)) {
+        const merged = git(cwd, ["merge", "--ff-only", "--quiet", upstream]);
+        return merged.code === 0
+            ? { ok: true }
+            : { ok: false, problem: lastLines(merged.stderr || merged.stdout) };
+    }
+    const rebased = git(cwd, ["rebase", "--autostash", "--quiet", upstream]);
+    if (rebased.code === 0)
+        return { ok: true };
+    const conflicts = git(cwd, ["diff", "--name-only", "--diff-filter=U", "-z"])
+        .stdout.split("\0")
+        .filter(Boolean)
+        .sort();
+    // Undoing the rebase puts back the agent's commits and, from the
+    // autostash, what it had not committed.
+    git(cwd, ["rebase", "--abort"]);
+    return conflicts.length > 0
+        ? { ok: false, conflicts }
+        : { ok: false, problem: lastLines(rebased.stderr || rebased.stdout) };
+}
+/**
+ * Push the checkout's commits to the solution's branch, after bringing in
+ * what other agents pushed since (SOLBRANCH-3.1). A push that loses a race
+ * with another agent's tries again; one the repository refuses comes back
+ * with the reason it gave (3.3).
+ */
+export function pushTo(cwd, branch) {
+    for (let attempt = 0; attempt < 3; attempt++) {
+        const brought = bringIn(cwd, branch);
+        if (!brought.ok) {
+            return "conflicts" in brought
+                ? { kind: "conflict", files: brought.conflicts }
+                : { kind: "refused", reason: brought.problem };
+        }
+        const before = commitOf(cwd, upstreamOf(branch));
+        const after = headCommit(cwd);
+        if (!after)
+            return { kind: "nothing to push" };
+        if (before && isAncestor(cwd, "HEAD", before)) {
+            return { kind: "nothing to push" };
+        }
+        const pushed = git(cwd, [
+            "push",
+            "--porcelain",
+            "origin",
+            `HEAD:refs/heads/${branch}`,
+        ]);
+        if (pushed.code === 0) {
+            return { kind: "pushed", before: before ?? NO_COMMIT, after };
+        }
+        if (/\[rejected\].*\((fetch first|non-fast-forward)\)/.test(pushed.stdout)) {
+            continue;
+        }
+        return { kind: "refused", reason: refusalOf(pushed) };
+    }
+    return {
+        kind: "refused",
+        reason: `other agents kept pushing to ${branch} while this one tried to`,
+    };
+}
+/** What the repository said when it refused a push: its own lines, else git's reason. */
+function refusalOf(ran) {
+    const said = ran.stderr
+        .split("\n")
+        .filter((line) => line.startsWith("remote:"))
+        .map((line) => line
+        .replace(/^remote:\s*/, "")
+        // biome-ignore lint/suspicious/noControlCharactersInRegex: the escape starts colour codes a remote sends
+        .replace(/\u001b\[[0-9;]*m/g, "")
+        .trim())
+        .filter(Boolean);
+    if (said.length > 0)
+        return said.join(" ");
+    const reason = ran.stdout.match(/\[(?:remote )?rejected\]\s*\(([^)]+)\)/);
+    return reason ? reason[1] : lastLines(ran.stderr || ran.stdout);
+}
+function lastLines(text) {
+    return text.trim().split("\n").slice(-3).join(" ").trim();
+}
+/** The names of the repository's branches, as it has them now. */
+export function remoteBranches(cwd) {
+    const ran = git(cwd, ["ls-remote", "--heads", "origin"]);
+    if (ran.code !== 0) {
+        throw new Error(`Couldn't list the repository's branches: ${lastLines(ran.stderr)}`);
+    }
+    return new Set(ran.stdout
+        .split("\n")
+        .map((line) => line.split("\t")[1]?.replace(/^refs\/heads\//, ""))
+        .filter((name) => !!name));
+}
+/**
+ * The name for a solution's new branch: `dotreq/<directory>`, or, when a
+ * branch already has that name, the lowest suffix from -2 up that none has
+ * (SOLBRANCH-1.0, 1.1).
+ */
+export function freeName(directory, taken) {
+    const base = `dotreq/${directory}`;
+    if (!taken.has(base))
+        return base;
+    for (let n = 2;; n++) {
+        if (!taken.has(`${base}-${n}`))
+            return `${base}-${n}`;
+    }
+}
+/** The default branch's commit, as the repository has it now, fetched into the checkout. */
+export function defaultBranchCommit(cwd) {
+    const fetched = git(cwd, ["fetch", "--quiet", "origin", "HEAD"]);
+    const commit = fetched.code === 0 ? commitOf(cwd, "FETCH_HEAD") : null;
+    if (!commit) {
+        throw new Error(`Couldn't read the repository's default branch: ${lastLines(fetched.stderr)}`);
+    }
+    return commit;
+}
+/**
+ * The commit a named branch is at, as the repository has it now, fetched
+ * into the checkout: what a solution's branch is made from when a
+ * rehearsal's scenario names the branch to start from (REHEARSE-4.5).
+ */
+export function branchCommit(cwd, branch) {
+    const fetched = fetchBranch(cwd, branch);
+    if (!fetched.ok) {
+        throw new Error(`Couldn't fetch ${branch}: ${fetched.problem}`);
+    }
+    const commit = fetched.there ? commitOf(cwd, upstreamOf(branch)) : null;
+    if (!commit) {
+        throw new Error(`The branch ${branch}, which the solution's branch is to be made from, isn't in the repository.`);
+    }
+    return commit;
+}
+/**
+ * The commit the repository's branch `name` is at, making the branch at
+ * `base` first when the repository has none of that name (SOLBRANCH-1.0,
+ * 1.3). A branch of that name that appears first — another of the
+ * solution's first sessions making it a moment before, or anyone's — is
+ * never moved: its commit is read and returned, for the caller to judge
+ * whose it is.
+ */
+export function branchHead(cwd, name, base) {
+    for (let attempt = 0; attempt < 3; attempt++) {
+        const fetched = fetchBranch(cwd, name);
+        if (!fetched.ok) {
+            throw new Error(`Couldn't fetch ${name}: ${fetched.problem}`);
+        }
+        if (fetched.there) {
+            const head = commitOf(cwd, upstreamOf(name));
+            if (head)
+                return head;
+        }
+        // Another session may have fetched a newer default branch and claimed
+        // first; its commit is the one to make the branch from.
+        if (commitOf(cwd, `${base}^{commit}`) === null) {
+            const got = git(cwd, ["fetch", "--quiet", "origin", base]);
+            if (got.code !== 0) {
+                throw new Error(`Couldn't fetch ${base}, which the solution's branch is made from: ${lastLines(got.stderr)}`);
+            }
+        }
+        // Made only if no branch has the name; one that got there first is
+        // read on the next pass.
+        const pushed = git(cwd, [
+            "push",
+            "--porcelain",
+            `--force-with-lease=refs/heads/${name}:`,
+            "origin",
+            `${base}:refs/heads/${name}`,
+        ]);
+        if (pushed.code === 0)
+            return base;
+        if (!/\[rejected\]|already exists/.test(pushed.stdout + pushed.stderr)) {
+            throw new Error(`The repository refused to make the branch ${name}: ${refusalOf(pushed)}`);
+        }
+    }
+    throw new Error(`Couldn't make the branch ${name}: it kept changing while this session read it.`);
+}
+/**
+ * Put the checkout on the solution's branch, and bring in what other steps
+ * pushed to it (SOLBRANCH-1.2, 2). Returns what the agent should be told,
+ * or null when there is nothing to tell: its checkout is on the branch and
+ * holds everything pushed to it.
+ */
+export function checkOut(cwd, branch) {
+    const fetched = fetchBranch(cwd, branch);
+    if (!fetched.ok) {
+        throw new Error(`Couldn't fetch ${branch}: ${fetched.problem}`);
+    }
+    if (!fetched.there) {
+        throw new Error(`The solution's branch ${branch} is no longer in the repository.`);
+    }
+    const current = currentBranch(cwd);
+    if (current !== branch) {
+        const local = commitOf(cwd, `refs/heads/${branch}`) !== null;
+        const switched = local
+            ? git(cwd, ["checkout", "--quiet", branch])
+            : git(cwd, [
+                "checkout",
+                "--quiet",
+                "-b",
+                branch,
+                "--no-track",
+                upstreamOf(branch),
+            ]);
+        if (switched.code !== 0) {
+            return [
+                `Your checkout is on ${current ?? "no branch"}, not the solution's branch ${branch}, and switching to it would overwrite changes you haven't committed: ${lastLines(switched.stderr)}`,
+                `Switch to ${branch} before you record anything: what you record is pushed to ${branch}.`,
+            ].join("\n");
+        }
+    }
+    const brought = bringIn(cwd, branch);
+    if (brought.ok)
+        return null;
+    if ("problem" in brought) {
+        throw new Error(`Couldn't bring in ${branch}'s new commits: ${brought.problem}`);
+    }
+    return [
+        `Other agents pushed commits to ${branch} that conflict with work you left in your checkout, in ${brought.conflicts.join(", ")}.`,
+        `Your checkout is as you left it. Bring the branch's commits in before you record anything (git pull --rebase --autostash origin ${branch}), and resolve the conflicts.`,
+    ].join("\n");
+}
+//# sourceMappingURL=branch.js.map