@popoverai/dotrequirements 0.32.1 → 0.34.0

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

@@ -0,0 +1,42 @@
+/**
+ * Which solution and agent a verb is for (VERB-4). Inside a runner the run
+ * itself says — the runner writes a run file and names it in
+ * `DOTREQ_RUN_FILE`: `{ solutionId, agent, branch }` — so an agent types no
+ * ids. Outside one, the agent names them with `--solution` and `--agent`,
+ * which win wherever they are given. The outcome is the backend's to work
+ * out — the one the agent is at — unless `--outcome` names it, as an agent
+ * at more than one does.
+ */
+/** The options every solution verb an agent runs carries. */
+export type WhereOptions = {
+    solution?: string;
+    agent?: string;
+    outcome?: string;
+    /** The outcome under its old name: a hidden alias of `--outcome`. */
+    step?: string;
+};
+export type Where = {
+    solutionId: string;
+    /** The agent working: a plan's named agent, or one dedicated to an outcome ("Pitch/drafter"). */
+    agent: string;
+    /** The outcome, when the agent named it; otherwise the one the agent is at. */
+    outcome?: string;
+    /**
+     * The solution's branch, which the runner has checked out (SOLBRANCH-1):
+     * only a run says it, and a verb that has it pushes to it before its
+     * record is kept (SOLBRANCH-3). Absent outside a runner, where a person
+     * pushes their own branches.
+     */
+    branch?: string;
+};
+/** The run's own, with anything the agent named winning over it. */
+export declare function whereOf(options: WhereOptions): Partial<Where>;
+/** For a verb an agent runs: both the solution and the agent, or a refusal saying how to give them. */
+export declare function requireWhere(options: WhereOptions): Where;
+/** For a verb that needs only the solution, as `checkout`: the solution, or a refusal saying how to give it. */
+export declare function requireSolution(options: WhereOptions): Partial<Where> & {
+    solutionId: string;
+};
+/** `"Pitch"` when the outcome is known, for what a verb prints; empty when it isn't. */
+export declare function onOutcome(outcome: string | undefined): string;
+//# sourceMappingURL=run-file.d.ts.map

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

@@ -0,0 +1,63 @@
+import { readFileSync } from "node:fs";
+const SAY_BOTH = 'Nothing says which solution and which agent this is for. Name them: --solution <id> --agent "<agent>". Inside a runner they come from the run itself.';
+const SAY_SOLUTION = "Nothing says which solution this is for. Name it: --solution <id>. Inside a runner it comes from the run itself.";
+/** What the runner wrote for this run, or nothing when there is no run file to read. */
+function fromRun() {
+    const path = process.env.DOTREQ_RUN_FILE;
+    if (!path)
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        // A run file that cannot be read is no worse than none: the options,
+        // or the refusal, decide.
+        return {};
+    }
+    if (!parsed || typeof parsed !== "object")
+        return {};
+    const { solutionId, agent, branch } = parsed;
+    return {
+        solutionId: typeof solutionId === "string" ? solutionId : undefined,
+        agent: typeof agent === "string" && agent ? agent : undefined,
+        branch: typeof branch === "string" && branch ? branch : undefined,
+    };
+}
+/** The outcome named, by `--outcome` or its old name `--step`; blank is none. */
+function outcomeNamed(options) {
+    return (options.outcome ?? options.step)?.trim() || undefined;
+}
+/** The run's own, with anything the agent named winning over it. */
+export function whereOf(options) {
+    const run = fromRun();
+    return {
+        solutionId: options.solution ?? run.solutionId,
+        agent: options.agent?.trim() || run.agent,
+        outcome: outcomeNamed(options),
+        // The run's branch is the run's solution's: naming another solution
+        // is working outside the run.
+        branch: options.solution === undefined || options.solution === run.solutionId
+            ? run.branch
+            : undefined,
+    };
+}
+/** For a verb an agent runs: both the solution and the agent, or a refusal saying how to give them. */
+export function requireWhere(options) {
+    const where = whereOf(options);
+    if (!where.solutionId || !where.agent)
+        throw new Error(SAY_BOTH);
+    return { ...where, solutionId: where.solutionId, agent: where.agent };
+}
+/** For a verb that needs only the solution, as `checkout`: the solution, or a refusal saying how to give it. */
+export function requireSolution(options) {
+    const where = whereOf(options);
+    if (!where.solutionId)
+        throw new Error(SAY_SOLUTION);
+    return { ...where, solutionId: where.solutionId };
+}
+/** `"Pitch"` when the outcome is known, for what a verb prints; empty when it isn't. */
+export function onOutcome(outcome) {
+    return outcome ? ` on "${outcome}"` : "";
+}
+//# sourceMappingURL=run-file.js.map

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

@@ -0,0 +1,62 @@
+/**
+ * The verbs as the share command runs them, with no install: a developer
+ * who ran `npx` has no `dotreq` on their path.
+ */
+export declare const SHARE_CLI = "npx @popoverai/dotrequirements@latest solution";
+type RecordedFile = {
+    documentId: string;
+    path: string;
+    version: number;
+    onBranch: boolean;
+    hash: string;
+};
+/** What a checkout leaves in the repository, for push and done to act on. */
+export type ShareRecord = {
+    token: string;
+    /** The outcome checked out: one someone outside the product creates. */
+    outcome: string;
+    round: number | null;
+    solution: {
+        id: string;
+        title: string;
+        directory: string;
+    };
+    files: RecordedFile[];
+};
+/** Every solution checked out into this repository, by its folder. */
+export declare function checkedOut(): ShareRecord[];
+/**
+ * `dotreq solution checkout --share <token> --outcome "<name>"`
+ * (SOLSHARE-2): every document of the project into `.requirements/`, the
+ * solution's branch's versions where it has them, each at the file this
+ * repository already has for it or where the project's sync would put it;
+ * the solution's mockups as pages to open; the record push and done act
+ * on; and the outcome's prompt, printed for whoever or whatever reads the
+ * output.
+ */
+export declare function shareCheckout(token: string, 
+/** The outcome handed over: one someone outside the product creates. */
+outcome: string | undefined, 
+/** SOLSHARE-2.10: the branch's version replaces an edit it has a newer version than. */
+branchWins?: boolean): Promise<void>;
+/**
+ * `dotreq solution push`, in a repository a solution was checked out into
+ * (SOLSHARE-3): each document changed since the checkout, and each one
+ * added under `.requirements/`, to the solution's branch. False when no
+ * solution is checked out here, for the runner's push to take over.
+ */
+export declare function sharePush(solution?: string, 
+/** SOLSHARE-3.8: the repository's version wins over a newer one on the branch. */
+repoWins?: boolean): Promise<boolean>;
+export type DoneOptions = {
+    comment?: string;
+    solution?: string;
+};
+/**
+ * `dotreq solution done [<where it is>...] [--comment "..."]` (SOLSHARE-4):
+ * close the round of the outcome the repository was checked out for, with
+ * nothing to paste.
+ */
+export declare function doneCommand(made: string[], options: DoneOptions): Promise<void>;
+export {};
+//# sourceMappingURL=share.d.ts.map

package/dist/commands/solution/share.js

@@ -0,0 +1,346 @@
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { ConvexHttpClient } from "convex/browser";
+import { ConvexError } from "convex/values";
+import { parse } from "yaml";
+import { convexUrl, webApiUrl } from "../../cloud.js";
+import { api } from "../../convex.js";
+import { extractFrontmatterBlock, stripFrontmatterBlock, } from "../../schema/parser-core.js";
+import { refusal } from "./client.js";
+import { layOut, recordSavedIds, } from "./working-folder.js";
+/**
+ * A solution's share command, from any repository (SOLSHARE; design in
+ * docs/working/solution-branches.md, "Handing the build to the people who
+ * do it"): `dotreq solution checkout --share <token> --outcome "<name>"`
+ * lays the solution's work out and records, under the solution's folder,
+ * which solution, outcome and round it was for; `dotreq solution push` sends the
+ * changed documents to the solution's branch; `dotreq solution done` closes
+ * the round it was checked out for. The token is the only credential, and
+ * the record stays out of git.
+ */
+const RECORD = ".checkout.json";
+const SOLUTIONS = path.join(".requirements", "solutions");
+/** What stays out of git in a solution's folder: the record, which holds the token, and the rendered mockups. */
+const IGNORED = [RECORD, "mockups/"];
+/**
+ * The verbs as the share command runs them, with no install: a developer
+ * who ran `npx` has no `dotreq` on their path.
+ */
+export const SHARE_CLI = "npx @popoverai/dotrequirements@latest solution";
+/**
+ * Work from the repository's root, whichever folder the command was run
+ * in, so that a checkout from a subfolder and a push from the root see the
+ * same record. Outside a git repository, where it was run.
+ */
+function atRepositoryRoot() {
+    try {
+        const root = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        if (root)
+            process.chdir(root);
+    }
+    catch {
+        // Not a git repository: the folder it was run in is the repository.
+    }
+}
+/** Calls on the share command's token alone: no project is linked, and none is needed. */
+function shareClient() {
+    const client = new ConvexHttpClient(convexUrl());
+    const inWords = async (call) => {
+        try {
+            return await call();
+        }
+        catch (error) {
+            if (error instanceof ConvexError)
+                throw new Error(refusal(error.data));
+            throw error;
+        }
+    };
+    return {
+        query: (fn, args) => inWords(() => client.query(fn, args)),
+        mutation: (fn, args) => inWords(() => client.mutation(fn, args)),
+    };
+}
+function hashOf(file) {
+    return createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+}
+function recordPath(directory) {
+    return path.join(SOLUTIONS, directory, RECORD);
+}
+/** Every solution checked out into this repository, by its folder. */
+export function checkedOut() {
+    if (!fs.existsSync(SOLUTIONS))
+        return [];
+    return fs
+        .readdirSync(SOLUTIONS)
+        .map((directory) => recordPath(directory))
+        .filter((file) => fs.existsSync(file))
+        .map((file) => JSON.parse(fs.readFileSync(file, "utf-8")));
+}
+/** The one solution a push or done is for, or why it can't tell (SOLSHARE-3.7, 4.6, 4.7). */
+function oneCheckedOut(solution) {
+    const records = checkedOut();
+    if (records.length === 0) {
+        throw new Error("No solution is checked out here: run the share command you were given first.");
+    }
+    if (solution) {
+        const found = records.find((record) => record.solution.id === solution ||
+            record.solution.directory === solution);
+        if (!found) {
+            throw new Error(`"${solution}" isn't checked out here. Checked out: ${records.map((record) => record.solution.directory).join(", ")}.`);
+        }
+        return found;
+    }
+    if (records.length > 1) {
+        throw new Error(`More than one solution is checked out here; say which with --solution: ${records.map((record) => record.solution.directory).join(", ")}.`);
+    }
+    return records[0];
+}
+function writeRecord(record) {
+    const directory = path.join(SOLUTIONS, record.solution.directory);
+    fs.mkdirSync(directory, { recursive: true });
+    fs.writeFileSync(recordPath(record.solution.directory), `${JSON.stringify(record, null, 2)}\n`);
+    // The record holds the token, and the mockups are renders: both stay out
+    // of the repository's history. Lines the developer added are kept.
+    const ignore = path.join(directory, ".gitignore");
+    const lines = fs.existsSync(ignore)
+        ? fs.readFileSync(ignore, "utf-8").split("\n").filter(Boolean)
+        : [];
+    const missing = IGNORED.filter((line) => !lines.includes(line));
+    if (missing.length > 0) {
+        fs.writeFileSync(ignore, `${[...lines, ...missing].join("\n")}\n`);
+    }
+}
+/**
+ * Markdown files under `.requirements/`, with the document id each one's
+ * frontmatter names. A file whose frontmatter can't be read is set aside,
+ * with a warning, rather than stopping the command.
+ */
+function requirementsFiles() {
+    const found = [];
+    const walk = (directory) => {
+        if (!fs.existsSync(directory))
+            return;
+        for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+            const full = path.join(directory, entry.name);
+            if (entry.isDirectory())
+                walk(full);
+            else if (entry.name.endsWith(".md")) {
+                let id;
+                try {
+                    const yaml = extractFrontmatterBlock(fs.readFileSync(full, "utf-8"));
+                    id = (yaml ? parse(yaml) : null)?.document?.id;
+                }
+                catch {
+                    console.warn(`Left ${full} alone: its frontmatter isn't YAML the command can read.`);
+                    continue;
+                }
+                found.push({
+                    file: full,
+                    ...(typeof id === "string" ? { documentId: id } : {}),
+                });
+            }
+        }
+    };
+    walk(".requirements");
+    return found;
+}
+/** A file as a push submits it: its text without frontmatter, and what the frontmatter says of its document. */
+function submitted(file) {
+    const content = fs.readFileSync(file, "utf-8");
+    const yaml = extractFrontmatterBlock(content);
+    const document = (yaml ? parse(yaml) : null)?.document;
+    return {
+        path: file,
+        markdownContent: stripFrontmatterBlock(content),
+        ...(typeof document?.id === "string" ? { documentId: document.id } : {}),
+        ...(typeof document?.defaultPrefix === "string"
+            ? { defaultPrefix: document.defaultPrefix }
+            : {}),
+    };
+}
+/** The app the share command renders mockups through. */
+function appUrl() {
+    return webApiUrl().replace(/\/+$/, "");
+}
+/**
+ * `dotreq solution checkout --share <token> --outcome "<name>"`
+ * (SOLSHARE-2): every document of the project into `.requirements/`, the
+ * solution's branch's versions where it has them, each at the file this
+ * repository already has for it or where the project's sync would put it;
+ * the solution's mockups as pages to open; the record push and done act
+ * on; and the outcome's prompt, printed for whoever or whatever reads the
+ * output.
+ */
+export async function shareCheckout(token, 
+/** The outcome handed over: one someone outside the product creates. */
+outcome, 
+/** SOLSHARE-2.10: the branch's version replaces an edit it has a newer version than. */
+branchWins = false) {
+    if (!outcome)
+        throw new Error('Say which outcome: --outcome "<name>", as the command you were given does.');
+    atRepositoryRoot();
+    const client = shareClient();
+    const got = await client.query(api.solutions.shares.forCheckout, {
+        token,
+        outcome,
+    });
+    // SOLSHARE-2.6, 2.10, 2.11: an edit that wasn't pushed is left as it is,
+    // unless the branch has saved a newer version of its document since the
+    // checkout: then the checkout stops, or with --branch-wins takes the
+    // branch's version.
+    const earlier = checkedOut().find((record) => record.solution.id === got.solution.id);
+    const unpushed = (earlier?.files ?? []).filter((file) => fs.existsSync(file.path) && hashOf(file.path) !== file.hash);
+    const current = new Map(got.files.map((file) => [file.documentId, file]));
+    const newer = (file) => {
+        const now = current.get(file.documentId);
+        return !!now?.onBranch && (!file.onBranch || now.version > file.version);
+    };
+    const conflicting = unpushed.filter(newer);
+    const kept = unpushed.filter((file) => !newer(file));
+    if (conflicting.length > 0 && !branchWins) {
+        throw new Error(`Nothing was written: the solution's branch has saved a newer version of ${conflicting.map((file) => file.path).join(", ")} since you checked ${conflicting.length === 1 ? "it" : "them"} out, and your changes to ${conflicting.length === 1 ? "it" : "them"} weren't pushed. Push them first with \`${SHARE_CLI} push --repo-wins\` to keep yours, or run this again with --branch-wins to take the branch's.`);
+    }
+    const keptIds = new Set(kept.map((file) => file.documentId));
+    // Each document goes where this repository already keeps it, when it does.
+    const here = new Map(requirementsFiles()
+        .filter((found) => found.documentId)
+        .map((found) => [found.documentId, found.file]));
+    const files = got.files.map((file) => ({
+        ...file,
+        path: here.get(file.documentId) ?? file.path,
+    }));
+    layOut(files.filter((file) => !keptIds.has(file.documentId)));
+    const mockupDirectory = path.join(SOLUTIONS, got.solution.directory, "mockups");
+    const rendered = [];
+    const failed = [];
+    for (const mockupId of got.mockups) {
+        const response = await fetch(`${appUrl()}/api/solutions/share/mockup`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ token, mockupId }),
+        }).catch(() => null);
+        if (!response?.ok) {
+            failed.push(mockupId);
+            continue;
+        }
+        fs.mkdirSync(mockupDirectory, { recursive: true });
+        fs.writeFileSync(path.join(mockupDirectory, `${mockupId}.html`), await response.text());
+        rendered.push(mockupId);
+    }
+    writeRecord({
+        token,
+        outcome: got.outcome,
+        round: got.round,
+        solution: got.solution,
+        // An edit left as it is keeps the version it was made from, so a push
+        // still sends it.
+        files: files.map((file) => kept.find((left) => left.documentId === file.documentId) ?? {
+            documentId: file.documentId,
+            path: file.path,
+            version: file.version,
+            onBranch: file.onBranch,
+            hash: hashOf(file.path),
+        }),
+    });
+    console.log(`Checked out ${got.solution.title}: ${files.length} ${files.length === 1 ? "document" : "documents"} under .requirements/${rendered.length ? `, and ${rendered.length} ${rendered.length === 1 ? "mockup" : "mockups"} under ${mockupDirectory}/` : ""}.`);
+    if (kept.length > 0) {
+        console.log(`Left your changes to ${kept.map((file) => file.path).join(", ")} as they are: the branch hasn't changed ${kept.length === 1 ? "that document" : "those documents"} since.`);
+    }
+    if (conflicting.length > 0) {
+        console.log(`Replaced your changes to ${conflicting.map((file) => file.path).join(", ")} with the branch's newer ${conflicting.length === 1 ? "version" : "versions"}.`);
+    }
+    if (failed.length > 0) {
+        console.log(`Couldn't render ${failed.length === 1 ? "mockup" : "mockups"} ${failed.join(", ")}: run the share command again to try again.`);
+    }
+    if (got.prompt) {
+        console.log(`\n${got.prompt}`);
+    }
+    else {
+        console.log(`\n"${got.outcome}" isn't waiting on anyone right now, so there's nothing to hand back yet.`);
+    }
+}
+/**
+ * `dotreq solution push`, in a repository a solution was checked out into
+ * (SOLSHARE-3): each document changed since the checkout, and each one
+ * added under `.requirements/`, to the solution's branch. False when no
+ * solution is checked out here, for the runner's push to take over.
+ */
+export async function sharePush(solution, 
+/** SOLSHARE-3.8: the repository's version wins over a newer one on the branch. */
+repoWins = false) {
+    atRepositoryRoot();
+    if (checkedOut().length === 0)
+        return false;
+    const record = oneCheckedOut(solution);
+    const changed = record.files
+        .filter((file) => fs.existsSync(file.path) && hashOf(file.path) !== file.hash)
+        .map((file) => file.path);
+    // A new document is a requirements file, or any Markdown in a solution's
+    // folder, that names no document yet; other notes under .requirements/
+    // stay where they are.
+    const added = requirementsFiles()
+        .filter((found) => !found.documentId &&
+        (found.file.endsWith(".requirements.md") ||
+            found.file.startsWith(`${SOLUTIONS}${path.sep}`)))
+        .map((found) => found.file);
+    const files = [...changed, ...added].map(submitted);
+    if (files.length === 0) {
+        console.log("Nothing to push: no document changed since the checkout.");
+        return true;
+    }
+    const saved = await shareClient().mutation(api.solutions.shares.push, {
+        token: record.token,
+        files,
+        base: record.files.map(({ documentId, version, onBranch }) => ({
+            documentId,
+            version,
+            onBranch,
+        })),
+        ...(repoWins ? { repoWins: true } : {}),
+    });
+    recordSavedIds(files, saved);
+    const byId = new Map(record.files.map((file) => [file.documentId, file]));
+    for (const entry of saved) {
+        byId.set(entry.documentId, {
+            documentId: entry.documentId,
+            path: entry.path,
+            version: entry.version,
+            onBranch: true,
+            hash: hashOf(entry.path),
+        });
+    }
+    writeRecord({ ...record, files: [...byId.values()] });
+    for (const entry of saved) {
+        console.log(`Saved ${entry.path} on the solution's branch as version ${entry.version}.${entry.replaced ? ` It replaced version ${entry.replaced.version}, saved ${new Date(entry.replaced.savedAt).toLocaleString()}, which the branch keeps.` : ""}`);
+    }
+    return true;
+}
+/**
+ * `dotreq solution done [<where it is>...] [--comment "..."]` (SOLSHARE-4):
+ * close the round of the outcome the repository was checked out for, with
+ * nothing to paste.
+ */
+export async function doneCommand(made, options) {
+    atRepositoryRoot();
+    const record = oneCheckedOut(options.solution);
+    if (record.round === null) {
+        throw new Error(`"${record.outcome}" wasn't waiting on anyone when it was checked out: run the share command again once it is.`);
+    }
+    const said = await shareClient().mutation(api.solutions.shares.done, {
+        token: record.token,
+        outcome: record.outcome,
+        round: record.round,
+        ...(made.length ? { made } : {}),
+        ...(options.comment?.trim() ? { comment: options.comment.trim() } : {}),
+    });
+    // STEP-REVIEW-18.7.0: nothing was recorded, and the message says why.
+    if (said.recorded === false)
+        throw new Error(said.message);
+    console.log(said.message);
+}
+//# sourceMappingURL=share.js.map

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

@@ -0,0 +1,14 @@
+import { type WhereOptions } from "./run-file.js";
+/**
+ * `dotreq solution stall "<what has to change>"`: the agent cannot go on
+ * with the outcome it is at, or the one `--outcome` names, and no decision
+ * would fix that. The reason is what has to change before it can be
+ * started again (VERB-3.2).
+ */
+export declare function stallCommand(reason: string, options: WhereOptions & {
+    /** False from the runner, which pushed already and says why it couldn't in the reason. */
+    push?: boolean;
+}): Promise<void>;
+/** A stall's reason, and that the work could not be pushed, and why (SOLBRANCH-3.4, 4.1). */
+export declare function withUnpushed(reason: string, why: string): string;
+//# sourceMappingURL=stall.d.ts.map

package/dist/commands/solution/stall.js

@@ -0,0 +1,41 @@
+import { api } from "../../convex.js";
+import { solutionClient } from "./client.js";
+import { pushWork } from "./pushing.js";
+import { onOutcome, requireWhere } from "./run-file.js";
+/**
+ * `dotreq solution stall "<what has to change>"`: the agent cannot go on
+ * with the outcome it is at, or the one `--outcome` names, and no decision
+ * would fix that. The reason is what has to change before it can be
+ * started again (VERB-3.2).
+ */
+export async function stallCommand(reason, options) {
+    if (!reason.trim()) {
+        throw new Error("Say what has to change before your work can be started again.");
+    }
+    const where = requireWhere(options);
+    const { solutionId, agent } = where;
+    const client = solutionClient();
+    // SOLBRANCH-3.4: a stall is recorded whether or not the work can be
+    // pushed; when it can't, the reason Quinn reads says so, and why.
+    let said = reason.trim();
+    if (where.branch && options.push !== false) {
+        const pushed = await pushWork(client, {
+            solutionId,
+            branch: where.branch,
+        });
+        if (!pushed.ok)
+            said = withUnpushed(said, pushed.why);
+    }
+    await client.mutation(api.solutions.mutations.stall, {
+        solutionId,
+        agent,
+        ...(where.outcome ? { outcome: where.outcome } : {}),
+        reason: said,
+    });
+    console.log(`Stalled${onOutcome(where.outcome)}. It can be started again once that is fixed.`);
+}
+/** A stall's reason, and that the work could not be pushed, and why (SOLBRANCH-3.4, 4.1). */
+export function withUnpushed(reason, why) {
+    return `${reason.replace(/\s+$/, "")}${/[.!?]$/.test(reason.trim()) ? "" : "."} The work could not be pushed: ${why.replace(/[.\s]+$/, "")}.`;
+}
+//# sourceMappingURL=stall.js.map

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

@@ -0,0 +1,11 @@
+/**
+ * `dotreq solution start <solution-id> <agent>`: begin an agent's work by
+ * hand. A stalled agent is started again, and it takes the part of an
+ * outcome's work it has due: the one `--outcome` names, or its first in the
+ * plan's order.
+ */
+export declare function startCommand(solutionId: string, agent: string, options: {
+    outcome?: string;
+    step?: string;
+}): Promise<void>;
+//# sourceMappingURL=start.d.ts.map

package/dist/commands/solution/start.js

@@ -0,0 +1,20 @@
+import { api } from "../../convex.js";
+import { solutionClient } from "./client.js";
+import { onOutcome } from "./run-file.js";
+/**
+ * `dotreq solution start <solution-id> <agent>`: begin an agent's work by
+ * hand. A stalled agent is started again, and it takes the part of an
+ * outcome's work it has due: the one `--outcome` names, or its first in the
+ * plan's order.
+ */
+export async function startCommand(solutionId, agent, options) {
+    const outcome = (options.outcome ?? options.step)?.trim() || undefined;
+    const client = solutionClient();
+    await client.mutation(api.solutions.mutations.start, {
+        solutionId,
+        agent,
+        ...(outcome ? { outcome } : {}),
+    });
+    console.log(`Started ${agent}${onOutcome(outcome)}.`);
+}
+//# sourceMappingURL=start.js.map

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

@@ -0,0 +1,39 @@
+import { type Panel, type PanelOutcome } from "./brief.js";
+import { solutionClient } from "./client.js";
+import { type WhereOptions } from "./run-file.js";
+/** What an agent is at: an outcome, and whether it drafts or reviews it there. */
+export type AgentAt = {
+    outcome: PanelOutcome;
+    part: "draft" | "review";
+};
+/**
+ * The outcome an agent is at, read off the plan panel: the one named, when
+ * `--outcome` names it; otherwise the one it is drafting, else one it
+ * reviews that stands reviewing, else one it stalled or asked on, else one
+ * ready for it to draft. Undefined when it is at none, as after it recorded
+ * its work; refused when it is at more than one and nothing says which.
+ */
+export declare function agentAt(panel: Pick<Panel, "phases">, agent: string, named?: string): AgentAt | undefined;
+/** The plan panel, or a refusal when the solution isn't there. */
+export declare function panelOf(client: ReturnType<typeof solutionClient>, solutionId: string): Promise<Panel>;
+/**
+ * The outcome a verb is about: the one named, else the one the agent is at
+ * on the panel. Refused, saying how to name it, when it is at none.
+ */
+export declare function outcomeFor(client: ReturnType<typeof solutionClient>, where: {
+    solutionId: string;
+    agent: string;
+    outcome?: string;
+}, what: string): Promise<string>;
+/**
+ * `dotreq solution status`: where the outcome the agent is at stands, as
+ * recorded — its one word, with the reason when stalled. With `--json`,
+ * also which outcome that is, whether the agent drafts or reviews it there,
+ * and whether it still owes its part: what the Stop hook and the runner's
+ * read-back judge an agent's session by (STEP-REVIEW-9). An agent at no
+ * outcome, as after it recorded its work, owes nothing.
+ */
+export declare function statusCommand(options: WhereOptions & {
+    json?: boolean;
+}): Promise<void>;
+//# sourceMappingURL=status.d.ts.map