@popoverai/dotrequirements 0.33.0 → 0.34.0

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