@popoverai/dotrequirements 0.33.0 → 0.34.0

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

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

@@ -0,0 +1,81 @@
+/**
+ * What `dotreq solution next` prints. The brief for an outcome is composed
+ * in the backend, entirely from blocks (docs/working/prompt-blocks.md), and
+ * arrives as `text`; the CLI prints it as given and renders nothing of its
+ * own. The shapes mirror what `solutions/mutations:next` and
+ * `solutions/queries:getPlan` return, as far as the CLI reads them (the CLI
+ * doesn't import the backend's types).
+ */
+/**
+ * An outcome to draft (`step`) or to review (`review`): the outcome, the
+ * brief the agent reads, and the outcomes it reviews and works from, whose
+ * images and demo scripts `next` saves in the checkout (SIGHT-9.3, 13.1).
+ */
+export type Brief = {
+    kind: "step" | "review";
+    /** The outcome the agent took; `label` is its name too. */
+    step: {
+        label: string;
+        outcome?: string;
+    };
+    text: string;
+    reviewing?: BriefOutcome[];
+    against?: BriefOutcome[];
+};
+/** An outcome the brief lists, as far as the CLI reads it. */
+export type BriefOutcome = {
+    name: string;
+    things?: Array<{
+        kind: string;
+        storageId?: string;
+        name?: string;
+        script?: string;
+    }>;
+};
+/** An outcome on the plan panel, as far as the CLI reads it. */
+export type PanelOutcome = {
+    name: string;
+    /** The one word it stands in: ready, drafting, reviewing, awaiting decision, stalled, done... */
+    status: string;
+    /** The agent that drafts it, when an agent of ours does. */
+    drafter?: string;
+    /** The agents that review it. */
+    reviewers?: string[];
+    /** Why one of its agents stalled. */
+    reason?: string;
+    /** Who it waits on, when someone outside creates it. */
+    party?: string;
+    /** For an outcome not started: what it can't begin without. */
+    waitingFor?: string[];
+    /** Its drafter's work was set aside and its new draft isn't taken yet: a session at it owes nothing more (CHECKPOINT-6.3.2.3). */
+    setAside?: boolean;
+};
+/** A checkpoint on the plan panel, as far as the CLI reads it. */
+export type PanelCheckpoint = {
+    name: string;
+    /** waiting, deciding (on the owner now), fixing, deferred or approved. */
+    stands: string;
+};
+/** The plan panel (`getPlan`): its outcomes by phase, and its checkpoints. */
+export type Panel = {
+    title: string;
+    phases: Array<{
+        name: string;
+        outcomes: PanelOutcome[];
+    }>;
+    checkpoints?: PanelCheckpoint[];
+};
+export type Standing = {
+    kind: "nothing ready";
+    plan: Panel;
+};
+export type NextResult = Brief | Standing;
+export declare const EXIT: {
+    /** Nothing is ready: a loop of `next` can stop here. */
+    readonly nothingReady: 3;
+};
+/** Every outcome on the panel, in the plan's order. */
+export declare function outcomesOf(panel: Pick<Panel, "phases">): PanelOutcome[];
+/** Nothing ready: every outcome and what it waits on, then any checkpoint the owner is at. */
+export declare function renderStanding({ plan }: Standing): string;
+//# sourceMappingURL=brief.d.ts.map

package/dist/commands/solution/brief.js

@@ -0,0 +1,47 @@
+/**
+ * What `dotreq solution next` prints. The brief for an outcome is composed
+ * in the backend, entirely from blocks (docs/working/prompt-blocks.md), and
+ * arrives as `text`; the CLI prints it as given and renders nothing of its
+ * own. The shapes mirror what `solutions/mutations:next` and
+ * `solutions/queries:getPlan` return, as far as the CLI reads them (the CLI
+ * doesn't import the backend's types).
+ */
+export const EXIT = {
+    /** Nothing is ready: a loop of `next` can stop here. */
+    nothingReady: 3,
+};
+/** Every outcome on the panel, in the plan's order. */
+export function outcomesOf(panel) {
+    return panel.phases.flatMap((phase) => phase.outcomes);
+}
+/** Nothing ready: every outcome and what it waits on, then any checkpoint the owner is at. */
+export function renderStanding({ plan }) {
+    const lines = [`Nothing is ready on "${plan.title}".`, ""];
+    for (const outcome of outcomesOf(plan)) {
+        lines.push(`- ${outcome.name}: ${standing(outcome)}`);
+    }
+    for (const checkpoint of plan.checkpoints ?? []) {
+        const stands = CHECKPOINT_STANDS[checkpoint.stands];
+        if (stands)
+            lines.push(`- The ${checkpoint.name} checkpoint: ${stands}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+/** A checkpoint worth a line when nothing is ready: one that holds the work up. */
+const CHECKPOINT_STANDS = {
+    deciding: "waiting on the owner's decision",
+    fixing: "a fix is running",
+    deferred: "deferred by the owner",
+};
+function standing(outcome) {
+    if (outcome.status === "stalled" && outcome.reason)
+        return `stalled — ${outcome.reason}`;
+    if (outcome.status === "awaiting external" && outcome.party) {
+        return `awaiting ${outcome.party}`;
+    }
+    if (outcome.status === "not started" && outcome.waitingFor?.length) {
+        return `not started — after ${outcome.waitingFor.join(", ")}`;
+    }
+    return outcome.status;
+}
+//# sourceMappingURL=brief.js.map

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

@@ -0,0 +1,27 @@
+import { type WhereOptions } from "./run-file.js";
+/**
+ * `dotreq solution checkout`: what the runner runs in its checkout before
+ * each session (SOLBRANCH-1, 2). Puts the checkout on the branch of the
+ * surface the outcome is kept on (1.5), making it on that surface's first
+ * session, and brings in what other agents pushed to it. Prints the branch and what the agent is to
+ * be told before its brief, if anything; with `--json`, as one line the
+ * runner reads.
+ */
+export declare function checkoutCommand(options: WhereOptions & {
+    json?: boolean;
+    share?: string;
+    branchWins?: boolean;
+}): Promise<void>;
+/**
+ * `dotreq solution push`: what the runner runs when a session ends
+ * (SOLBRANCH-4.0). Pushes the commits the agent made after its last record
+ * to the run's branch, its commits after any other agents pushed since;
+ * never commits what it left uncommitted (SOLBRANCH-6.0). Prints whether
+ * it pushed and, when it couldn't, why; with `--json`, as one line.
+ * Outside a runner there is no branch to push to, and nothing happens.
+ */
+export declare function pushCommand(options: WhereOptions & {
+    json?: boolean;
+    repoWins?: boolean;
+}): Promise<void>;
+//# sourceMappingURL=checkout.d.ts.map

package/dist/commands/solution/checkout.js

@@ -0,0 +1,66 @@
+import { solutionClient } from "./client.js";
+import { checkOutSolution, pushWork } from "./pushing.js";
+import { requireSolution, whereOf } from "./run-file.js";
+import { shareCheckout, sharePush } from "./share.js";
+/**
+ * `dotreq solution checkout`: what the runner runs in its checkout before
+ * each session (SOLBRANCH-1, 2). Puts the checkout on the branch of the
+ * surface the outcome is kept on (1.5), making it on that surface's first
+ * session, and brings in what other agents pushed to it. Prints the branch and what the agent is to
+ * be told before its brief, if anything; with `--json`, as one line the
+ * runner reads.
+ */
+export async function checkoutCommand(options) {
+    // SOLSHARE-2: from any repository, on a solution's share command.
+    if (options.share) {
+        await shareCheckout(options.share, (options.outcome ?? options.step)?.trim() || undefined, options.branchWins);
+        return;
+    }
+    const { solutionId } = requireSolution(options);
+    // SOLBRANCH-1.5: the branch of the surface the outcome is kept on.
+    const outcome = (options.outcome ?? options.step)?.trim() || undefined;
+    const { branch, notice } = await checkOutSolution(solutionClient(), solutionId, process.cwd(), outcome);
+    if (options.json) {
+        process.stdout.write(`${JSON.stringify({ branch, notice })}\n`);
+        return;
+    }
+    console.log(`On ${branch}.`);
+    if (notice)
+        console.log(`\n${notice}`);
+}
+/**
+ * `dotreq solution push`: what the runner runs when a session ends
+ * (SOLBRANCH-4.0). Pushes the commits the agent made after its last record
+ * to the run's branch, its commits after any other agents pushed since;
+ * never commits what it left uncommitted (SOLBRANCH-6.0). Prints whether
+ * it pushed and, when it couldn't, why; with `--json`, as one line.
+ * Outside a runner there is no branch to push to, and nothing happens.
+ */
+export async function pushCommand(options) {
+    const where = whereOf(options);
+    // SOLSHARE-3: a repository a solution was checked out into, with no run.
+    if (!where.branch && (await sharePush(options.solution, options.repoWins)))
+        return;
+    if (!where.branch && !options.json) {
+        throw new Error("No solution is checked out here: run the share command you were given first.");
+    }
+    const outcome = where.solutionId && where.branch
+        ? await pushWork(solutionClient(), {
+            solutionId: where.solutionId,
+            branch: where.branch,
+        })
+        : { ok: true, pushed: false };
+    const result = outcome.ok
+        ? { pushed: outcome.pushed, failure: null }
+        : { pushed: false, failure: outcome.why };
+    if (options.json) {
+        process.stdout.write(`${JSON.stringify(result)}\n`);
+        return;
+    }
+    console.log(result.failure
+        ? `Not pushed: ${result.failure}.`
+        : result.pushed
+            ? `Pushed to ${where.branch}.`
+            : "Nothing to push.");
+}
+//# sourceMappingURL=checkout.js.map

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

@@ -0,0 +1,16 @@
+import type { FunctionReference } from "convex/server";
+/**
+ * Calls against the linked project, for the solution verbs: the project's
+ * credentials on every call, and a refusal from the backend surfaced in its
+ * own words. A call to an endpoint that names the project passes `project`
+ * itself.
+ */
+export declare function solutionClient(): {
+    /** The linked project, by its slug or id. */
+    project: string;
+    mutation: <R>(fn: FunctionReference<"mutation">, args: Record<string, unknown>) => Promise<R>;
+    query: <R>(fn: FunctionReference<"query">, args: Record<string, unknown>) => Promise<R>;
+};
+/** A backend refusal, in the words the backend gave: a plain message, or a plan's broken rules listed. */
+export declare function refusal(data: unknown): string;
+//# sourceMappingURL=client.d.ts.map

package/dist/commands/solution/client.js

@@ -0,0 +1,46 @@
+import { ConvexHttpClient } from "convex/browser";
+import { ConvexError } from "convex/values";
+import { convexUrl } from "../../cloud.js";
+import { getProjectCredentials } from "../../utils/project-settings.js";
+/**
+ * Calls against the linked project, for the solution verbs: the project's
+ * credentials on every call, and a refusal from the backend surfaced in its
+ * own words. A call to an endpoint that names the project passes `project`
+ * itself.
+ */
+export function solutionClient() {
+    const { projectId, projectSecret } = getProjectCredentials();
+    const client = new ConvexHttpClient(convexUrl());
+    const auth = { projectAuth: { projectSlug: projectId, projectSecret } };
+    return {
+        /** The linked project, by its slug or id. */
+        project: projectId,
+        mutation: (fn, args) => inWords(() => client.mutation(fn, { ...auth, ...args })),
+        query: (fn, args) => inWords(() => client.query(fn, { ...auth, ...args })),
+    };
+}
+async function inWords(call) {
+    try {
+        return await call();
+    }
+    catch (error) {
+        if (error instanceof ConvexError)
+            throw new Error(refusal(error.data));
+        throw error;
+    }
+}
+/** A backend refusal, in the words the backend gave: a plain message, or a plan's broken rules listed. */
+export function refusal(data) {
+    if (typeof data === "string")
+        return data;
+    if (data && typeof data === "object") {
+        const { kind, rules, message } = data;
+        if (kind === "invalid plan" && rules?.length) {
+            return `The plan breaks these rules:\n- ${rules.join("\n- ")}`;
+        }
+        if (message)
+            return message;
+    }
+    return JSON.stringify(data);
+}
+//# sourceMappingURL=client.js.map

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

@@ -0,0 +1,9 @@
+/**
+ * The request file `ask` reads, in words: what `dotreq solution ask --help`
+ * prints after its options, the way `author --help` carries the reference
+ * forms. The backend's `describeContract()` renders it from the schema the
+ * request is validated against; the CLI can't import the backend, so this
+ * is that text, and a test keeps the two the same.
+ */
+export declare const REQUEST_CONTRACT = "Ask the person to decide something about the outcome you are drafting. A choice presents options with a recommendation. One decision per request: if two things need deciding, ask twice.\n\nA request is JSON with a \"kind\" and the fields of that kind:\n\nchoice:\n  question (text, up to 200 characters): The question, phrased as a question in the words the person will read it, not as a topic.\n  options (list, at least 2): The live alternatives. More than four makes deciding harder; give more only when each is a genuine choice. Leave out anything you have already ruled out.\n    name (text, up to 200 characters): The option as you would say it to the person: a noun phrase they can repeat back, not a label.\n    benefits (list of text, each up to 200 characters): What is better if this option is taken. One line each, in your own words.\n    costs (list of text, each up to 200 characters): What is worse if this option is taken: what it would take to build, and what the person lives with afterwards. Effort is a cost like any other.\n    note (text, up to 600 characters, optional): Anything you learned or checked about this option that is not a benefit or a cost. Leave it out when there is nothing to add.\n  recommendation (object): Which option you would take, and the one reason why.\n    option (text, up to 200 characters): The name of the option you recommend, exactly as it appears in options.\n    because (text, up to 200 characters): The one reason that carries it, in one line. The full reasoning belongs in background.\n  background (text, up to 4000 characters): What the person needs to know to decide well that the options do not already say. Include only context that would substantially change the quality of the decision. The person reads this after the options, so do not reiterate them.";
+//# sourceMappingURL=contract.d.ts.map

package/dist/commands/solution/contract.js

@@ -0,0 +1,23 @@
+/**
+ * The request file `ask` reads, in words: what `dotreq solution ask --help`
+ * prints after its options, the way `author --help` carries the reference
+ * forms. The backend's `describeContract()` renders it from the schema the
+ * request is validated against; the CLI can't import the backend, so this
+ * is that text, and a test keeps the two the same.
+ */
+export const REQUEST_CONTRACT = `Ask the person to decide something about the outcome you are drafting. A choice presents options with a recommendation. One decision per request: if two things need deciding, ask twice.
+
+A request is JSON with a "kind" and the fields of that kind:
+
+choice:
+  question (text, up to 200 characters): The question, phrased as a question in the words the person will read it, not as a topic.
+  options (list, at least 2): The live alternatives. More than four makes deciding harder; give more only when each is a genuine choice. Leave out anything you have already ruled out.
+    name (text, up to 200 characters): The option as you would say it to the person: a noun phrase they can repeat back, not a label.
+    benefits (list of text, each up to 200 characters): What is better if this option is taken. One line each, in your own words.
+    costs (list of text, each up to 200 characters): What is worse if this option is taken: what it would take to build, and what the person lives with afterwards. Effort is a cost like any other.
+    note (text, up to 600 characters, optional): Anything you learned or checked about this option that is not a benefit or a cost. Leave it out when there is nothing to add.
+  recommendation (object): Which option you would take, and the one reason why.
+    option (text, up to 200 characters): The name of the option you recommend, exactly as it appears in options.
+    because (text, up to 200 characters): The one reason that carries it, in one line. The full reasoning belongs in background.
+  background (text, up to 4000 characters): What the person needs to know to decide well that the options do not already say. Include only context that would substantially change the quality of the decision. The person reads this after the options, so do not reiterate them.`;
+//# sourceMappingURL=contract.js.map