@popoverai/dotrequirements 0.32.1 → 0.34.0

package/dist/commands/solution/status.js

@@ -0,0 +1,145 @@
+import { api } from "../../convex.js";
+import { outcomesOf } from "./brief.js";
+import { solutionClient } from "./client.js";
+import { requireWhere } from "./run-file.js";
+const drafts = (outcome, agent) => outcome.drafter === agent;
+const reviews = (outcome, agent) => (outcome.reviewers ?? []).includes(agent);
+/**
+ * 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 function agentAt(panel, agent, named) {
+    const outcomes = outcomesOf(panel);
+    if (named) {
+        const outcome = outcomes.find((each) => each.name === named);
+        if (!outcome) {
+            throw new Error(`The plan has no outcome called "${named}". Its outcomes: ${outcomes.map((each) => each.name).join(", ")}.`);
+        }
+        const drafting = drafts(outcome, agent);
+        const reviewing = reviews(outcome, agent);
+        if (!drafting && !reviewing) {
+            throw new Error(`${agent} neither drafts nor reviews "${named}".`);
+        }
+        return {
+            outcome,
+            part: reviewing && (!drafting || outcome.status === "reviewing")
+                ? "review"
+                : "draft",
+        };
+    }
+    const tiers = [
+        (outcome) => drafts(outcome, agent) && outcome.status === "drafting"
+            ? { outcome, part: "draft" }
+            : undefined,
+        (outcome) => reviews(outcome, agent) && outcome.status === "reviewing"
+            ? { outcome, part: "review" }
+            : undefined,
+        (outcome) => outcome.status === "stalled" || outcome.status === "awaiting decision"
+            ? drafts(outcome, agent)
+                ? { outcome, part: "draft" }
+                : reviews(outcome, agent)
+                    ? { outcome, part: "review" }
+                    : undefined
+            : undefined,
+        (outcome) => drafts(outcome, agent) && outcome.status === "ready"
+            ? { outcome, part: "draft" }
+            : undefined,
+    ];
+    for (const tier of tiers) {
+        const found = outcomes.flatMap((outcome) => {
+            const at = tier(outcome);
+            return at ? [at] : [];
+        });
+        if (found.length === 1)
+            return found[0];
+        if (found.length > 1) {
+            throw new Error(`${agent} is at more than one outcome: ${found.map((at) => `"${at.outcome.name}"`).join(", ")}. Name one with --outcome "<name>".`);
+        }
+    }
+    return undefined;
+}
+/** The plan panel, or a refusal when the solution isn't there. */
+export async function panelOf(client, solutionId) {
+    const panel = await client.query(api.solutions.queries.getPlan, {
+        solutionId,
+    });
+    if (!panel)
+        throw new Error("Solution not found.");
+    return 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 async function outcomeFor(client, where, what) {
+    if (where.outcome)
+        return where.outcome;
+    const at = agentAt(await panelOf(client, where.solutionId), where.agent);
+    if (!at) {
+        throw new Error(`${where.agent} is at no outcome now, so nothing says which ${what}. Name it with --outcome "<name>".`);
+    }
+    return at.outcome.name;
+}
+/**
+ * Whether a reviewer still owes its result on an outcome standing
+ * reviewing: an outcome with several reviewers stands reviewing until the
+ * last gives its result, so one that gave its own since the latest
+ * submission owes nothing more.
+ */
+async function reviewerOwes(client, solutionId, outcome, agent) {
+    const thread = (await client.query(api.solutions.queries.getThread, {
+        solutionId,
+        outcome,
+    })) ?? [];
+    let since = 0;
+    thread.forEach((entry, at) => {
+        if (entry.kind === "submission")
+            since = at + 1;
+    });
+    return !thread
+        .slice(since)
+        .some((entry) => entry.agent === agent &&
+        (entry.kind === "review" || entry.kind === "escalation"));
+}
+/**
+ * `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 async function statusCommand(options) {
+    const where = requireWhere(options);
+    const client = solutionClient();
+    const panel = await panelOf(client, where.solutionId);
+    const at = agentAt(panel, where.agent, where.outcome);
+    if (!at) {
+        if (options.json) {
+            process.stdout.write(`${JSON.stringify({ agent: where.agent, outcome: null, part: null, status: null, reason: null, reviews: false, owes: false })}\n`);
+            return;
+        }
+        process.stdout.write(`${where.agent} is at no outcome now.\n`);
+        return;
+    }
+    const { outcome, part } = at;
+    // CHECKPOINT-6.3.2.3: a drafter whose work was set aside owes nothing
+    // more there; the new draft is another session's.
+    const setAside = part === "draft" && outcome.setAside === true;
+    const owes = part === "draft"
+        ? !setAside &&
+            (outcome.status === "drafting" || outcome.status === "ready")
+        : outcome.status === "reviewing" &&
+            (await reviewerOwes(client, where.solutionId, outcome.name, where.agent));
+    if (options.json) {
+        process.stdout.write(`${JSON.stringify({ agent: where.agent, outcome: outcome.name, part, status: outcome.status, reason: outcome.reason ?? null, reviews: part === "review", ...(setAside ? { setAside } : {}), owes })}\n`);
+        return;
+    }
+    process.stdout.write(outcome.reason
+        ? `${outcome.name}: ${outcome.status} — ${outcome.reason}\n`
+        : `${outcome.name}: ${outcome.status}\n`);
+}
+//# sourceMappingURL=status.js.map

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

@@ -0,0 +1,13 @@
+/**
+ * The executive summary a verb carries (STEP-REVIEW-20): for the owner,
+ * what the work is and what most needs their eye, where the comment is for
+ * the thread. `--executive-summary` is its name; `--summary` is short for
+ * it, for a person typing it by hand (VERB-1.6, 2.5).
+ */
+export type SummaryOptions = {
+    executiveSummary?: string;
+    summary?: string;
+};
+/** The summary given, by either name; undefined when none, or only blanks. */
+export declare function summaryGiven(options: SummaryOptions): string | undefined;
+//# sourceMappingURL=summary.d.ts.map

package/dist/commands/solution/summary.js

@@ -0,0 +1,5 @@
+/** The summary given, by either name; undefined when none, or only blanks. */
+export function summaryGiven(options) {
+    return (options.executiveSummary?.trim() || options.summary?.trim() || undefined);
+}
+//# sourceMappingURL=summary.js.map

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

@@ -0,0 +1,118 @@
+/** Where a thing is, as the backend stores it (solutions/schema.ts, `thingValidator`). */
+export type Thing = {
+    kind: "document";
+    documentId: string;
+} | {
+    kind: "board";
+    boardId: string;
+} | {
+    kind: "mockup";
+    mockupId: string;
+} | {
+    kind: "file";
+    path: string;
+    branch?: string;
+} | {
+    kind: "link";
+    url: string;
+    title?: string;
+} | {
+    kind: "preview";
+    port: number;
+    page?: string;
+    command: string;
+    screenshot?: string;
+} | {
+    kind: "pull request";
+    url: string;
+    number: number;
+} | {
+    kind: "video";
+    storageId: string;
+    name: string;
+    script: string;
+    /** Where each step of the script begins in the video, in seconds, when the recorder said (SIGHT-7.4). */
+    stepStarts?: number[];
+} | {
+    kind: "demo script";
+    name: string;
+    script: string;
+} | {
+    kind: "image";
+    storageId: string;
+    name: string;
+} | ({
+    kind: "scores";
+} & Scores);
+/** One axis of a solution's scores: a whole number from 1 to 5, and why. */
+export type AxisScore = {
+    score: number;
+    reason: string;
+};
+/**
+ * A solution's scores, by axis, as the backend stores them on an outcome
+ * (solutions/scores.ts). Made with `dotreq scores`, submitted as
+ * `scores:<id>`.
+ */
+export type Scores = {
+    costOfDelay: AxisScore;
+    relevance: AxisScore;
+    entities: AxisScore;
+    api: AxisScore;
+    testing: AxisScore;
+    experience: AxisScore;
+    doubt: AxisScore;
+};
+/**
+ * A thing as an agent names it on the command line: where it is, or, for
+ * scores, the reference `dotreq scores create` printed, which the backend
+ * copies onto the outcome when the work is recorded
+ * (solutions/schema.ts, `submittedThingValidator`); for a video, the file in
+ * the checkout and the script it was recorded from, which `author` submits
+ * as the stored copy's id and the script's text (SIGHT-7.0); for an image,
+ * the file, which `author` submits as the stored copy's id and its name
+ * (SIGHT-9.0); for a demo's script, the steps file, which `author` submits
+ * as its text (SIGHT-13.0); for the solution's pull request, its number, which `author`
+ * checks against the repository and submits with its address (PULL-3); for
+ * a preview, its port, page and command, which `author` submits with a
+ * screenshot of its page when one can be taken (SIGHT-12.0). Any of them
+ * goes with the `--title` given for it, when titles are given (12.3).
+ */
+export type Reference = Exclude<Thing, {
+    kind: "scores";
+} | {
+    kind: "video";
+} | {
+    kind: "demo script";
+} | {
+    kind: "image";
+} | {
+    kind: "pull request";
+} | {
+    kind: "preview";
+}> | {
+    kind: "scores";
+    scoresId: string;
+} | {
+    kind: "video";
+    path: string;
+    scriptPath: string;
+} | {
+    kind: "demo script";
+    path: string;
+} | {
+    kind: "image";
+    path: string;
+} | {
+    kind: "pull request";
+    number: number;
+} | {
+    kind: "preview";
+    port: number;
+    page?: string;
+    command: string;
+};
+export declare const REFERENCE_FORMS = "A reference is document:<id>, board:<id>, mockup:<id>, scores:<id>, pr:<number>, file:<path>[@<branch>], link:<url>, image:<path>, video:<path> <script> (one argument, e.g. \"video:final.mp4 steps.json\"), demo-script:<path> or preview:<port>[/<page>] <command> (one argument, e.g. \"preview:8080/design/roll-count pnpm dev\", with the page when it isn't the first one).";
+/** A thing from the reference an agent types on the command line. */
+export declare function parseThing(reference: string): Reference;
+//# sourceMappingURL=things.d.ts.map

package/dist/commands/solution/things.js

@@ -0,0 +1,78 @@
+/** A preview's reference, as an example the agent can follow. */
+const PREVIEW_EXAMPLE = '"preview:8080/design/roll-count pnpm dev"';
+export const REFERENCE_FORMS = `A reference is document:<id>, board:<id>, mockup:<id>, scores:<id>, pr:<number>, file:<path>[@<branch>], link:<url>, image:<path>, video:<path> <script> (one argument, e.g. "video:final.mp4 steps.json"), demo-script:<path> or preview:<port>[/<page>] <command> (one argument, e.g. ${PREVIEW_EXAMPLE}, with the page when it isn't the first one).`;
+/** A thing from the reference an agent types on the command line. */
+export function parseThing(reference) {
+    const colon = reference.indexOf(":");
+    if (colon === -1) {
+        throw new Error(`"${reference}" isn't a reference. ${REFERENCE_FORMS}`);
+    }
+    const kind = reference.slice(0, colon);
+    const rest = reference.slice(colon + 1);
+    if (!rest)
+        throw new Error(`"${reference}" names nothing. ${REFERENCE_FORMS}`);
+    switch (kind) {
+        case "document":
+            return { kind, documentId: rest };
+        case "board":
+            return { kind, boardId: rest };
+        case "mockup":
+            return { kind, mockupId: rest };
+        case "scores":
+            return { kind, scoresId: rest };
+        case "pr": {
+            // PULL-3: the solution's pull request, by the reference
+            // `dotreq solution pull-request` printed.
+            const number = Number(rest.replace(/^#/, ""));
+            if (!Number.isInteger(number) || number <= 0) {
+                throw new Error(`"${reference}" isn't a pull request's reference. It is pr: and the pull request's number, as \`dotreq solution pull-request\` prints it, e.g. pr:42.`);
+            }
+            return { kind: "pull request", number };
+        }
+        case "image":
+            // SIGHT-9.0: an image from the checkout, such as a screenshot.
+            return { kind, path: rest };
+        case "file": {
+            const at = rest.lastIndexOf("@");
+            if (at === -1)
+                return { kind, path: rest };
+            return { kind, path: rest.slice(0, at), branch: rest.slice(at + 1) };
+        }
+        case "link":
+            return { kind, url: rest };
+        case "demo-script":
+            // SIGHT-13.0: a demo's script, which the agent reviewing it records.
+            return { kind: "demo script", path: rest };
+        case "video": {
+            // SIGHT-7.0.1: a video comes with the script it was recorded from.
+            const space = rest.search(/\s/);
+            const path = space === -1 ? rest : rest.slice(0, space);
+            const scriptPath = space === -1 ? "" : rest.slice(space + 1).trim();
+            if (!scriptPath) {
+                throw new Error(`"${reference}" names a video without its script, so nothing was submitted. Submit the steps file it was recorded from with it, as one argument: "video:${path} steps.json".`);
+            }
+            return { kind, path, scriptPath };
+        }
+        case "preview": {
+            // SIGHT-3.2: the port, then, when the preview opens on a page other
+            // than the first, that page's path (3.2.0), then the command.
+            const space = rest.search(/\s/);
+            const address = /^(\d+)(\/\S*)?$/.exec(space === -1 ? rest : rest.slice(0, space));
+            const port = Number(address?.[1]);
+            const page = address?.[2] ?? "";
+            const command = space === -1 ? "" : rest.slice(space + 1).trim();
+            if (!address || port <= 0 || !command) {
+                throw new Error(`"${reference}" needs a port and the command that listens on it, as one argument: ${PREVIEW_EXAMPLE}.`);
+            }
+            if (page.startsWith("//")) {
+                throw new Error(`"${reference}" names a page that isn't a path on the preview. Name it from the root, as in ${PREVIEW_EXAMPLE}.`);
+            }
+            return page && page !== "/"
+                ? { kind, port, page, command }
+                : { kind, port, command };
+        }
+        default:
+            throw new Error(`"${kind}" isn't a kind of thing. ${REFERENCE_FORMS}`);
+    }
+}
+//# sourceMappingURL=things.js.map

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

@@ -0,0 +1,13 @@
+import { type WhereOptions } from "./run-file.js";
+/**
+ * `dotreq solution thread`: the thread of the outcome the agent is at, or
+ * of the one `--outcome` names, oldest first — each entry on one line
+ * saying who, any result, and what they said (VERB-6, STEP-REVIEW-5); with
+ * `--latest`, the newest comment only, and with `--latest <n>` the newest
+ * n, stalls, restarts and redrafts left out. The brief names this command
+ * rather than carrying the thread.
+ */
+export declare function threadCommand(options: WhereOptions & {
+    latest?: string | true;
+}): Promise<void>;
+//# sourceMappingURL=thread.d.ts.map

package/dist/commands/solution/thread.js

@@ -0,0 +1,53 @@
+import { api } from "../../convex.js";
+import { solutionClient } from "./client.js";
+import { requireWhere } from "./run-file.js";
+import { outcomeFor } from "./status.js";
+/**
+ * What `--latest` counts: what someone wrote — a submission note, a review
+ * result, an escalation or a decision. A stall, a restart and a redraft
+ * because the outcome it is on was redrafted are on the thread but not
+ * counted, so a drafter revising after a restart reads the review it is
+ * answering, not the restart (VERB-6.4, 6.5).
+ */
+function isComment(entry) {
+    return (entry.kind !== "stall" &&
+        entry.kind !== "restart" &&
+        entry.kind !== "input changed");
+}
+/**
+ * `dotreq solution thread`: the thread of the outcome the agent is at, or
+ * of the one `--outcome` names, oldest first — each entry on one line
+ * saying who, any result, and what they said (VERB-6, STEP-REVIEW-5); with
+ * `--latest`, the newest comment only, and with `--latest <n>` the newest
+ * n, stalls, restarts and redrafts left out. The brief names this command
+ * rather than carrying the thread.
+ */
+export async function threadCommand(options) {
+    // `--latest` alone is the newest entry; `--latest 3`, the newest three.
+    const latest = options.latest === undefined
+        ? undefined
+        : options.latest === true
+            ? 1
+            : Number(options.latest);
+    if (latest !== undefined && (!Number.isInteger(latest) || latest < 1)) {
+        throw new Error(`--latest is how many of the newest entries to print, 1 or more, not "${options.latest}".`);
+    }
+    const where = requireWhere(options);
+    const client = solutionClient();
+    const outcome = await outcomeFor(client, where, "thread to read");
+    const thread = await client.query(api.solutions.queries.getThread, { solutionId: where.solutionId, outcome });
+    if (thread === null)
+        throw new Error("Solution not found.");
+    if (thread.length === 0) {
+        process.stdout.write(`Nothing is on "${outcome}"'s thread yet.\n`);
+        return;
+    }
+    // The newest n comments, still oldest first (VERB-6.4).
+    const shown = latest === undefined ? thread : thread.filter(isComment).slice(-latest);
+    if (shown.length === 0) {
+        process.stdout.write(`Nothing but stalls and restarts is on "${outcome}"'s thread yet.\n`);
+        return;
+    }
+    process.stdout.write(`${shown.map((entry) => entry.line).join("\n")}\n`);
+}
+//# sourceMappingURL=thread.js.map

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

@@ -0,0 +1,24 @@
+import type { FunctionReference } from "convex/server";
+import type { solutionClient } from "./client.js";
+/** A file read from the checkout, ready to upload. */
+export type Upload = {
+    name: string;
+    contentType: string;
+    bytes: Uint8Array<ArrayBuffer>;
+};
+/**
+ * Upload a file the app keeps rather than the branch — a video (SIGHT-7.0)
+ * or an image (SIGHT-9.0): an upload URL from the backend, asked for with
+ * the solution it is for (none for an image a rehearsal gives an input,
+ * REHEARSE-4.7), the file POSTed to it with its type, and the stored copy's
+ * id back. Convex sets no size
+ * limit on these uploads; the POST has two minutes.
+ */
+export declare function uploadToApp(client: ReturnType<typeof solutionClient>, uploadUrl: FunctionReference<"mutation">, 
+/** The upload URL endpoint's arguments: the solution, or the project for a rehearsal's input. */
+args: {
+    solutionId: string;
+} | {
+    project: string;
+}, file: Upload): Promise<string>;
+//# sourceMappingURL=upload.d.ts.map

package/dist/commands/solution/upload.js

@@ -0,0 +1,27 @@
+/**
+ * Upload a file the app keeps rather than the branch — a video (SIGHT-7.0)
+ * or an image (SIGHT-9.0): an upload URL from the backend, asked for with
+ * the solution it is for (none for an image a rehearsal gives an input,
+ * REHEARSE-4.7), the file POSTed to it with its type, and the stored copy's
+ * id back. Convex sets no size
+ * limit on these uploads; the POST has two minutes.
+ */
+export async function uploadToApp(client, uploadUrl, 
+/** The upload URL endpoint's arguments: the solution, or the project for a rehearsal's input. */
+args, file) {
+    const url = await client.mutation(uploadUrl, args);
+    const response = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": file.contentType },
+        body: file.bytes,
+    });
+    if (!response.ok) {
+        throw new Error(`Uploading ${file.name} failed (${response.status} ${response.statusText}), so nothing was submitted. Submit it again.`);
+    }
+    const { storageId } = (await response.json());
+    if (!storageId) {
+        throw new Error(`Uploading ${file.name} returned no id, so nothing was submitted. Submit it again.`);
+    }
+    return storageId;
+}
+//# sourceMappingURL=upload.js.map

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

@@ -0,0 +1,88 @@
+import type { solutionClient } from "./client.js";
+/**
+ * Videos on an outcome (SIGHT-7): the drafter submits a video file from its
+ * checkout with the script it was recorded from. The video is uploaded to
+ * the app and never committed; the script travels as text, and the outcome's
+ * reviewer reads it in its brief.
+ *
+ * A browser plays MP4 with H.264 video and WebM with VP8 or VP9 video
+ * everywhere we support (Chrome, Edge, Firefox, Safari on macOS and iOS).
+ * HEVC and AV1 play only on some hardware, and QuickTime and Matroska only
+ * in some browsers, so they are refused. The codec is read from the file
+ * itself, since an extension says nothing about it. Kept in step with the
+ * backend's `ACCEPTED_VIDEO_FORMATS` (convex/solutions/videos.ts).
+ */
+export declare const ACCEPTED_VIDEO_FORMATS = "an MP4 with H.264 video, or a WebM with VP8 or VP9 video";
+export type VideoContentType = "video/mp4" | "video/webm";
+/** What the file is: a format a browser plays, or why it isn't one. */
+export type VideoFormat = {
+    contentType: VideoContentType;
+} | {
+    refused: string;
+};
+/** A video read from the checkout, ready to upload. */
+export type Video = {
+    name: string;
+    contentType: VideoContentType;
+    bytes: Uint8Array<ArrayBuffer>;
+};
+/** The video at a path, or a refusal naming the accepted formats (SIGHT-7.0.0). */
+export declare function readVideo(path: string): Video;
+/**
+ * The script a video was recorded from (SIGHT-7.0, 7.0.1): agentic-demo's
+ * steps file, JSON holding the browser commands for each step and the
+ * sentence said over it, as its text. Anything else is refused, so a
+ * reviewer never reads the wrong file as the demo's script.
+ */
+export declare function readScript(path: string): string;
+/**
+ * Where each step of the script begins in the video, in seconds
+ * (SIGHT-7.4): read from the summary `agentic-demo record` writes beside
+ * the video it records, `final.json` (@popoverai/browser-automation 0.15.4
+ * on), one segment per step: `index`, the step's 0-based place in the steps
+ * file, and `startSeconds`, where the step's first frame is in the final
+ * video, taken as given. The starts are kept in the steps file's order, so
+ * step n of a link, counted from 1 as the recorder prints it ("step 1/6"),
+ * is the start at n − 1 (SOLDOC-15.1.1). None when there is no such file,
+ * as beside a video recorded before the recorder wrote one, so a link to a
+ * step of the script opens the video at its start (SOLDOC-15.1.1.0); none,
+ * with a word on stderr, when the file isn't the recorder's summary of this
+ * script, one start for each of its steps.
+ */
+export declare function readStepStarts(videoPath: string, script: string): number[] | undefined;
+/**
+ * A demo's script, as the drafter submits it (SIGHT-13.0): the steps file
+ * the agent reviewing it records the video from, as its text.
+ */
+export declare function readDemoScript(path: string): {
+    name: string;
+    script: string;
+};
+/** What container and video codec the bytes hold, read from the file itself. */
+export declare function videoFormat(bytes: Uint8Array): VideoFormat;
+/** A video read from the checkout with the script it was recorded from, and where each step of it begins when the recorder said. */
+export type Recording = {
+    video: Video;
+    script: string;
+    stepStarts?: number[];
+};
+/**
+ * A video and its script, read and checked before anything is uploaded or
+ * recorded (SIGHT-7.0.0, 7.0.1), with its steps' starts (7.4).
+ */
+export declare function readRecording(path: string, scriptPath: string): Recording;
+/**
+ * A recording as it is submitted (SIGHT-7.0, 7.4, 13.2): the app's copy of
+ * the video, by the file's name, with the script's text and its steps'
+ * starts. Nothing goes on the branch.
+ */
+export declare function submittedRecording(client: ReturnType<typeof solutionClient>, solutionId: string, { video, script, stepStarts }: Recording): Promise<{
+    kind: "video";
+    storageId: string;
+    name: string;
+    script: string;
+    stepStarts?: number[];
+}>;
+/** Upload a video to the app (SIGHT-7.0), and the stored copy's id back. */
+export declare function uploadVideo(client: ReturnType<typeof solutionClient>, solutionId: string, video: Video): Promise<string>;
+//# sourceMappingURL=video.d.ts.map