@popoverai/dotrequirements 0.33.0 → 0.34.1

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

@@ -0,0 +1,10 @@
+/**
+ * `dotreq solution rehearse <scenario.yaml>` (REHEARSE-4): run a scenario
+ * against the linked project, real parties awaited, and print how it went.
+ * The scenario's earlier runs are removed first, unless `--keep` says to
+ * leave them for comparing (REHEARSE-6).
+ */
+export declare function rehearseCommand(path: string, options?: {
+    keep?: boolean;
+}): Promise<void>;
+//# sourceMappingURL=rehearse.d.ts.map

package/dist/commands/solution/rehearse.js

@@ -0,0 +1,24 @@
+import { checkScenario, rehearse } from "../../rehearsal/driver.js";
+import { removeEarlierRuns } from "../../rehearsal/earlier.js";
+import { liveClient, scenarioFrom } from "../../rehearsal/live.js";
+import { renderReport } from "../../rehearsal/report.js";
+import { solutionClient } from "./client.js";
+/**
+ * `dotreq solution rehearse <scenario.yaml>` (REHEARSE-4): run a scenario
+ * against the linked project, real parties awaited, and print how it went.
+ * The scenario's earlier runs are removed first, unless `--keep` says to
+ * leave them for comparing (REHEARSE-6).
+ */
+export async function rehearseCommand(path, options = {}) {
+    const client = solutionClient();
+    const scenario = await scenarioFrom(path, client);
+    checkScenario(scenario);
+    const earlier = options.keep
+        ? { scenario: scenario.file ?? path, removed: 0, keep: true, kept: [] }
+        : await removeEarlierRuns(path, client);
+    const report = await rehearse(liveClient(), scenario);
+    process.stdout.write(renderReport({ ...report, earlier }));
+    if (!/^nothing ready$/.test(report.ended))
+        process.exitCode = 3;
+}
+//# sourceMappingURL=rehearse.js.map

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

@@ -0,0 +1,3 @@
+/** A decision request from the JSON file an agent wrote. The backend validates it against the contract. */
+export declare function readRequest(file: string): unknown;
+//# sourceMappingURL=request.d.ts.map

package/dist/commands/solution/request.js

@@ -0,0 +1,13 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+/** A decision request from the JSON file an agent wrote. The backend validates it against the contract. */
+export function readRequest(file) {
+    const text = readFileSync(resolve(process.cwd(), file), "utf8");
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        throw new Error(`${file} isn't JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+//# sourceMappingURL=request.js.map

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

@@ -0,0 +1,27 @@
+import { type WhereOptions } from "./run-file.js";
+import { type SummaryOptions } from "./summary.js";
+export type ReviewOptions = WhereOptions & SummaryOptions & {
+    /** What should change, what was checked, or what the owner is to decide: required for every result (VERB-2.0, 2.1, 2.4). */
+    comment?: string;
+    /**
+     * With an approval of a demo's script: the video recorded from it and
+     * the script as the reviewer left it, each `"video:<video> <steps
+     * file>"`, given after the result on the command line (SIGHT-13.2).
+     */
+    videos?: string[];
+};
+/**
+ * `dotreq solution review <result> --comment "..."`: the reviewer's
+ * result on the outcome it is reviewing, or on the one `--outcome` names.
+ * The comment is what the next reader of the thread sees first — the
+ * drafter works from it, and on an escalation it is the note the owner
+ * reads — so every result is refused without one before anything is
+ * recorded (VERB-2.0, 2.1, 2.4). An approval also carries an executive
+ * summary, `--executive-summary "..."`, which is what the owner reads with
+ * the work (VERB-2.5); the outcome's own rules decide what follows. An
+ * approval of a demo's script carries the video the reviewer recorded from
+ * it, `"video:<video> <steps file>"`, which takes the script's place
+ * (SIGHT-13.2); no other result carries one (13.4.0).
+ */
+export declare function reviewCommand(result: string, options: ReviewOptions): Promise<void>;
+//# sourceMappingURL=review.d.ts.map

package/dist/commands/solution/review.js

@@ -0,0 +1,104 @@
+import { api } from "../../convex.js";
+import { solutionClient } from "./client.js";
+import { pushBeforeRecord } from "./pushing.js";
+import { onOutcome, requireWhere } from "./run-file.js";
+import { summaryGiven } from "./summary.js";
+import { parseThing } from "./things.js";
+import { readRecording, submittedRecording } from "./video.js";
+/** What an agent types, and the result in the words the outcome keeps. */
+const RESULTS = {
+    approved: "approved",
+    "approved-with-revisions": "approved with revisions",
+    "needs-revision": "needs revision",
+    escalate: "escalate",
+};
+/**
+ * `dotreq solution review <result> --comment "..."`: the reviewer's
+ * result on the outcome it is reviewing, or on the one `--outcome` names.
+ * The comment is what the next reader of the thread sees first — the
+ * drafter works from it, and on an escalation it is the note the owner
+ * reads — so every result is refused without one before anything is
+ * recorded (VERB-2.0, 2.1, 2.4). An approval also carries an executive
+ * summary, `--executive-summary "..."`, which is what the owner reads with
+ * the work (VERB-2.5); the outcome's own rules decide what follows. An
+ * approval of a demo's script carries the video the reviewer recorded from
+ * it, `"video:<video> <steps file>"`, which takes the script's place
+ * (SIGHT-13.2); no other result carries one (13.4.0).
+ */
+export async function reviewCommand(result, options) {
+    const outcome = RESULTS[result];
+    if (!outcome) {
+        throw new Error(`A review result is approved, approved-with-revisions, needs-revision or escalate, not "${result}".`);
+    }
+    const comment = options.comment?.trim();
+    if (!comment) {
+        throw new Error(outcome === "approved"
+            ? "Say what you checked: your comment is what the next reader sees first."
+            : outcome === "escalate"
+                ? "Say what the owner is to decide: your comment is the note they read with the work."
+                : "Say what should change: the drafter works from your comment.");
+    }
+    // VERB-2.5, 2.5.0: an approval carries an executive summary for the
+    // owner, and nothing else does; refused before anything is recorded, in
+    // the backend's words.
+    const summary = summaryGiven(options);
+    const approving = outcome === "approved" || outcome === "approved with revisions";
+    if (approving && !summary) {
+        throw new Error("Write an executive summary for the owner with --executive-summary: it's what they read first. Say what this is and what most needs their eye, as the work will stand once any fixes you asked for are made.");
+    }
+    if (!approving && summary) {
+        throw new Error(`Only an approval carries an executive summary, so nothing was recorded. Leave --executive-summary off: ${outcome === "escalate" ? "your comment is the note the owner reads." : "the drafter works from your comment."}`);
+    }
+    // SIGHT-13.2, 13.4.0: a video goes only with a plain approval, and is
+    // read before anything is pushed, uploaded or recorded.
+    const recordings = readVideos(options.videos ?? []);
+    if (recordings.length > 0 && outcome !== "approved") {
+        throw new Error(outcome === "approved with revisions"
+            ? "Nothing was recorded: a demo's script isn't approved with revisions, because its drafter can't change the script without the video going out of step. Fix anything small yourself, record the video, and approve with it, saying in your comment what you changed; or give needs-revision."
+            : `Nothing was recorded: only an approval carries a video. Give your result without it: ${outcome === "escalate" ? "your comment is the note the owner reads" : "the drafter works from your comment"}, and no video is kept.`);
+    }
+    const where = requireWhere(options);
+    const { solutionId, agent } = where;
+    const client = solutionClient();
+    // SOLBRANCH-3.0: what the reviewer committed reaches the branch first.
+    await pushBeforeRecord(client, where);
+    const videos = [];
+    for (const recording of recordings) {
+        videos.push(await submittedRecording(client, solutionId, recording));
+    }
+    const args = {
+        solutionId,
+        agent,
+        ...(where.outcome ? { outcome: where.outcome } : {}),
+        review: {
+            outcome,
+            comment,
+            ...(summary ? { summary } : {}),
+            ...(videos.length ? { videos } : {}),
+        },
+    };
+    const said = await client.mutation(api.solutions.mutations.complete, args);
+    // STEP-REVIEW-18.7.0: the drafter submitted again after this review began.
+    // Nothing was recorded; the words say what changed and to give the result
+    // again once the reviewer has looked.
+    if (said?.refused)
+        throw new Error(said.refused);
+    console.log(outcome === "escalate"
+        ? `Escalated${onOutcome(where.outcome)}. It waits on the owner's decision.`
+        : `Recorded your review${onOutcome(where.outcome)}: ${outcome}.`);
+}
+/**
+ * The videos a review carries (SIGHT-13.2): each recorded from a demo's
+ * script, named as the drafter names one, `"video:<video> <steps file>"`.
+ * Nothing else goes with a review.
+ */
+function readVideos(references) {
+    return references.map((reference) => {
+        const thing = parseThing(reference);
+        if (thing.kind !== "video") {
+            throw new Error(`Nothing was recorded: a review carries no "${reference}". The one thing it carries is the video you recorded from a demo's script, with your approval: "video:<video> <steps file>".`);
+        }
+        return readRecording(thing.path, thing.scriptPath);
+    });
+}
+//# sourceMappingURL=review.js.map

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

@@ -0,0 +1,43 @@
+/**
+ * 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, outcome }` — 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 one the
+ * run was handed, so a verb records on the outcome the agent is at even
+ * when it drafts one outcome and reviews another (VERB-3.4, 6.0);
+ * `--outcome` names another. Outside a run, the backend works it out.
+ */
+/** 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 the agent named, or the one its run was handed; otherwise the backend's to work out. */
+    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,69 @@
+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, outcome } = parsed;
+    return {
+        solutionId: typeof solutionId === "string" ? solutionId : undefined,
+        agent: typeof agent === "string" && agent ? agent : undefined,
+        branch: typeof branch === "string" && branch ? branch : undefined,
+        outcome: typeof outcome === "string" && outcome ? outcome : 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();
+    const agent = options.agent?.trim() || run.agent;
+    // The run's outcome is its own agent's on its own solution: naming
+    // another is working outside the run.
+    const inTheRun = (options.solution === undefined || options.solution === run.solutionId) &&
+        agent === run.agent;
+    return {
+        solutionId: options.solution ?? run.solutionId,
+        agent,
+        outcome: outcomeNamed(options) ?? (inTheRun ? run.outcome : undefined),
+        // 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