@popoverai/dotrequirements 0.32.1 → 0.34.0

package/dist/rehearsal/driver.js

@@ -0,0 +1,337 @@
+import { planOf } from "./derive.js";
+/**
+ * The plan a scenario rehearses, refused when it names an outcome the plan
+ * doesn't have or leaves one of its inputs holding nothing: what a live
+ * rehearsal checks before it removes the scenario's earlier runs, so a
+ * mistake in the scenario never costs the run under review. An input the
+ * scenario doesn't name holds something when the earlier rehearsal it
+ * starts from holds it (REHEARSE-4.8).
+ */
+export function checkScenario(scenario) {
+    const plan = planOf(scenario.plan);
+    for (const name of plan.inputs) {
+        if (scenario.inputs?.[name])
+            continue;
+        if (scenario.history?.outcomes.includes(name))
+            continue;
+        throw new Error(scenario.history
+            ? `The plan's input "${name}" holds nothing: solution ${scenario.history.solution} held no "${name}" when it made "${scenario.history.after}", so name its artifacts in the scenario.`
+            : `The plan's input "${name}" holds nothing: name its artifacts in the scenario.`);
+    }
+    return plan;
+}
+/**
+ * Who plays an agent at a part of an outcome's work in a scenario: the key
+ * naming that agent on that outcome (`Code/Code Reviewer`), then the key
+ * naming the part — the outcome's name for its drafter or whoever makes it
+ * from outside (`Pitch`), "<outcome>/reviewer" for its reviewers
+ * (`Pitch/reviewer`) — then the agent's own name (`Acceptance Tester`, or
+ * `Pitch/drafter` for one dedicated to its outcome), then whoever outside
+ * makes it (`release manager`). Unnamed, an agent is real. The key that
+ * matched, for counting turns.
+ */
+export function partiesOf(parties) {
+    return (at) => {
+        const keys = [
+            ...(at.agent ? [`${at.outcome}/${at.agent}`] : []),
+            at.part === "review" ? `${at.outcome}/reviewer` : at.outcome,
+            ...(at.agent ? [at.agent] : []),
+            ...(at.party ? [at.party] : []),
+        ];
+        const key = keys.find((name) => parties[name] !== undefined);
+        return key ? { party: parties[key], key } : { party: "real", key: keys[0] };
+    };
+}
+/** Every outcome on the panel, in the plan's order. */
+const outcomesOn = (panel) => (panel?.phases ?? []).flatMap((phase) => phase.outcomes);
+/**
+ * The parts of the work an agent, or someone outside, could take now or is
+ * at, in the plan's order: a ready or drafting outcome's draft, a review of
+ * an outcome standing reviewing (each of its reviewers, since the panel
+ * doesn't say which have given their result), and an outcome waiting on
+ * whoever makes it from outside.
+ */
+function partsDue(outcomes) {
+    return outcomes.flatMap((outcome) => {
+        if ((outcome.status === "ready" || outcome.status === "drafting") &&
+            outcome.drafter) {
+            return [{ outcome: outcome.name, part: "draft", agent: outcome.drafter }];
+        }
+        if (outcome.status === "reviewing") {
+            return (outcome.reviewers ?? []).map((agent) => ({
+                outcome: outcome.name,
+                part: "review",
+                agent,
+            }));
+        }
+        if (outcome.status === "awaiting external" ||
+            outcome.status === "awaiting collaboration") {
+            return [
+                {
+                    outcome: outcome.name,
+                    part: "outside",
+                    ...(outcome.party ? { party: outcome.party } : {}),
+                },
+            ];
+        }
+        return [];
+    });
+}
+/**
+ * The driver (docs/working/rehearsing-steps.md): the orchestrator the
+ * product has as events, as a loop. Look at where every outcome stands;
+ * for each part of the work due, find who plays its agent; play a script
+ * through the same verbs an agent uses — `next` for the agent, then what
+ * its script records — or wait for a real one; answer decisions and
+ * checkpoints from the person's script; stop when nothing is ready, or
+ * when something needs a person nobody scripted, or an agent stalls.
+ */
+export async function rehearse(client, scenario) {
+    const plan = checkScenario(scenario);
+    const inputs = Object.entries(scenario.inputs ?? {}).map(([name, things]) => ({ name, things }));
+    const solutionId = await client.create({
+        title: scenario.title,
+        scenario: scenario.file,
+        description: scenario.description,
+        plan,
+        inputs,
+        ...(scenario.branch ? { branch: scenario.branch } : {}),
+        ...(scenario.published?.length ? { published: scenario.published } : {}),
+        ...(scenario.history
+            ? {
+                history: {
+                    solution: scenario.history.solution,
+                    after: scenario.history.after,
+                },
+            }
+            : {}),
+    });
+    const partyFor = partiesOf(scenario.parties);
+    const played = {};
+    /** The script for this turn: the n-th of a list, the last repeating, counted by outcome and agent. */
+    const scriptFor = (at, party) => {
+        if (!Array.isArray(party))
+            return party;
+        const key = `${at.outcome}/${at.agent ?? at.part}`;
+        const n = played[key] ?? 0;
+        played[key] = n + 1;
+        return party[Math.min(n, party.length - 1)];
+    };
+    const asked = {};
+    /** The person's next scripted answer under a name, taken. */
+    const answerFor = (name) => {
+        const answers = scenario.person?.[name] ?? [];
+        const n = asked[name] ?? 0;
+        const answer = answers[n];
+        if (answer)
+            asked[name] = n + 1;
+        return answer;
+    };
+    const waited = {};
+    const waitMs = scenario.waitMs ?? 20 * 60 * 1000;
+    const pollMs = 15_000;
+    let ended = "nothing ready";
+    for (let turn = 0; turn < 500; turn++) {
+        const panel = await client.panel(solutionId);
+        const outcomes = outcomesOn(panel);
+        // A decision waiting: the person's script answers, or the rehearsal ends.
+        const deciding = outcomes.find((o) => o.status === "awaiting decision");
+        if (deciding) {
+            const decision = await client.openDecision?.(solutionId, deciding.name);
+            const answer = decision && client.answer ? answerFor(deciding.name) : undefined;
+            if (!answer || !decision || !client.answer) {
+                ended = `"${deciding.name}" waits on a decision nobody scripted`;
+                break;
+            }
+            await client.answer(decision.id, answer);
+            continue;
+        }
+        const stalled = outcomes.find((o) => o.status === "stalled");
+        if (stalled) {
+            ended = `"${stalled.name}" stalled: ${stalled.reason ?? "no reason given"}`;
+            break;
+        }
+        // A checkpoint waiting on the person: her scripted approval, or the end.
+        const checkpoint = panel?.checkpoints?.find((c) => c.stands === "deciding");
+        if (checkpoint) {
+            const answer = client.approveCheckpoint
+                ? answerFor(checkpoint.name)
+                : undefined;
+            if (!answer || !client.approveCheckpoint) {
+                ended = `the ${checkpoint.name} checkpoint waits on a decision nobody scripted`;
+                break;
+            }
+            if (answer.kind !== "approval" || answer.outcome !== "approved") {
+                throw new Error(`The person's script answers the ${checkpoint.name} checkpoint with an approval: { kind: approval, outcome: approved }, with any comment as her words.`);
+            }
+            await client.approveCheckpoint(solutionId, checkpoint.name, answer.comment);
+            continue;
+        }
+        // The parts due, scripted ones first: a script takes its agent's work
+        // through `next`, as the agent would.
+        const due = partsDue(outcomes).map((at) => ({ at, ...partyFor(at) }));
+        let acted = false;
+        for (const { at, party } of due) {
+            if (party === "real")
+                continue;
+            if (at.part === "outside") {
+                await playOutside(client, solutionId, at, scriptFor(at, party));
+                acted = true;
+                break;
+            }
+            const brief = await client.next({ solutionId, agent: at.agent });
+            if (brief.kind === "nothing ready")
+                continue;
+            const taken = takenPart(brief, at.agent);
+            const script = partyFor(taken);
+            if (script.party === "real") {
+                throw new Error(`${at.agent} is scripted for "${at.outcome}" but real for "${taken.outcome}", which it took first: script it for both, or neither.`);
+            }
+            await play(client, solutionId, taken, scriptFor(taken, script.party), brief);
+            acted = true;
+            break;
+        }
+        if (acted)
+            continue;
+        // Nothing a script could take: wait for a real agent at work or due.
+        const real = due
+            .filter(({ at, party }) => party === "real" && at.part !== "outside")
+            .map(({ at }) => ({ outcome: at.outcome, agent: at.agent }))[0];
+        if (!real) {
+            ended = "nothing ready";
+            break;
+        }
+        if (!client.sleep) {
+            throw new Error(`${real.agent} is real on "${real.outcome}", and only a live rehearsal can wait for a real agent.`);
+        }
+        const key = `${real.outcome}/${real.agent}`;
+        waited[key] = (waited[key] ?? 0) + pollMs;
+        if (waited[key] > waitMs) {
+            ended = `"${real.outcome}" waited ${Math.round(waitMs / 60000)} minutes for ${real.agent}`;
+            break;
+        }
+        await client.sleep(pollMs);
+    }
+    const reports = [];
+    for (const outcome of outcomesOn(await client.panel(solutionId))) {
+        const report = {
+            outcome: outcome.name,
+            status: outcome.status,
+            reason: outcome.reason,
+            things: await client.things(solutionId, outcome.name),
+            thread: await client.thread(solutionId, outcome.name),
+        };
+        if (client.agentLog) {
+            const agents = [
+                ...(outcome.drafter ? [outcome.drafter] : []),
+                ...(outcome.reviewers ?? []),
+            ];
+            const logs = {};
+            for (const agent of agents) {
+                const part = {
+                    outcome: outcome.name,
+                    part: agent === outcome.drafter ? "draft" : "review",
+                    agent,
+                };
+                if (partyFor(part).party === "real") {
+                    logs[agent] = await client.agentLog(solutionId, agent);
+                }
+            }
+            if (Object.keys(logs).length > 0)
+                report.agentLogs = logs;
+        }
+        reports.push(report);
+    }
+    return { solutionId, ended, outcomes: reports };
+}
+/** The part a brief hands the agent: the outcome it names, drafting or reviewing it. */
+function takenPart(brief, agent) {
+    const step = brief.step;
+    const outcome = step?.outcome ?? step?.label;
+    if (!outcome) {
+        throw new Error(`${agent} was given a brief that names no outcome.`);
+    }
+    return { outcome, part: brief.kind === "review" ? "review" : "draft", agent };
+}
+/** A script for an agent: check the brief it was given as the agent would read it, then act. */
+async function play(client, solutionId, at, script, brief) {
+    const agent = at.agent;
+    const { outcome } = at;
+    const where = `"${outcome}" (${agent}, ${at.part === "review" ? "reviewing" : "drafting"})`;
+    if (script.expect) {
+        try {
+            script.expect(brief);
+        }
+        catch (error) {
+            throw new Error(`${where}: the brief isn't what the script expected — ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    if (script.stall) {
+        await client.stall({ solutionId, agent, outcome, reason: script.stall });
+        return;
+    }
+    if (script.ask) {
+        await client.ask({ solutionId, agent, outcome, request: script.ask });
+        return;
+    }
+    // REHEARSE-1.1: a script records exactly as a real agent does, so an
+    // approval carries the summary the script gives (VERB-2.5) and none
+    // stands in for a missing one; the backend refuses it as it would the
+    // agent's.
+    if (at.part === "review") {
+        if (!script.review) {
+            throw new Error(`${where}: the script gives no review — give it review, ask or stall.`);
+        }
+        await client.complete({
+            solutionId,
+            agent,
+            outcome,
+            review: script.review,
+        });
+        return;
+    }
+    const made = await madeBy(client, script);
+    if (!made) {
+        throw new Error(`${where}: the script says nothing to do — give it made, scores, ask or stall.`);
+    }
+    await client.complete({
+        solutionId,
+        agent,
+        outcome,
+        made,
+        comment: script.comment,
+        summary: script.summary,
+    });
+}
+/** What a script submits: its things, or the scores it makes first, as `dotreq scores create` would. */
+async function madeBy(client, script) {
+    if (script.made)
+        return script.made;
+    if (script.scores) {
+        return [
+            {
+                kind: "scores",
+                scoresId: await client.createScores(script.scores),
+            },
+        ];
+    }
+    return undefined;
+}
+/**
+ * A script for whoever makes an outcome from outside the product, or the
+ * owner with an agent: it closes the outcome with what it made, as their
+ * close would (AWAIT-7.1: a rehearsal's scripts play every party).
+ */
+async function playOutside(client, solutionId, at, script) {
+    const made = await madeBy(client, script);
+    if (!made) {
+        throw new Error(`"${at.outcome}" (${at.party ?? "made outside"}): the script says nothing to do — give it made or scores.`);
+    }
+    await client.complete({
+        solutionId,
+        outcome: at.outcome,
+        made,
+        comment: script.comment,
+    });
+}
+//# sourceMappingURL=driver.js.map

package/dist/rehearsal/earlier.d.ts

@@ -0,0 +1,25 @@
+import type { solutionClient } from "../commands/solution/client.js";
+import type { EarlierRuns } from "./types.js";
+/**
+ * A new rehearsal replaces the earlier runs of its scenario (REHEARSE-6):
+ * the rehearsal solutions in the project recorded as runs of the same
+ * scenario file are removed before it starts, with what they made. What any scenario in the
+ * same folder names as an input stays, so that scenario can still start
+ * from it; so does an earlier run whose history a scenario there starts
+ * from (6.2.0), whole.
+ */
+/**
+ * What the scenarios in this scenario's folder name: the documents, boards
+ * and mockups they name as inputs, and the earlier rehearsals' solutions
+ * whose history they start from (REHEARSE-6.2.0), each by id, with the files
+ * that name it. Refuses when one of those files can't be read, since then
+ * what it names can't be known.
+ */
+export declare function namedInputs(scenarioPath: string): Map<string, string[]>;
+/**
+ * Remove the earlier runs of the scenario, keeping what a scenario names
+ * (REHEARSE-6.0, 6.2), and keeping whole an earlier run whose history a
+ * scenario starts from (6.2.0).
+ */
+export declare function removeEarlierRuns(scenarioPath: string, client: ReturnType<typeof solutionClient>, pause?: (ms: number) => Promise<void>): Promise<EarlierRuns>;
+//# sourceMappingURL=earlier.d.ts.map

package/dist/rehearsal/earlier.js

@@ -0,0 +1,138 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { parse } from "yaml";
+import { parseThing } from "../commands/solution/things.js";
+import { api } from "../convex.js";
+/**
+ * A new rehearsal replaces the earlier runs of its scenario (REHEARSE-6):
+ * the rehearsal solutions in the project recorded as runs of the same
+ * scenario file are removed before it starts, with what they made. What any scenario in the
+ * same folder names as an input stays, so that scenario can still start
+ * from it; so does an earlier run whose history a scenario there starts
+ * from (6.2.0), whole.
+ */
+/**
+ * What the scenarios in this scenario's folder name: the documents, boards
+ * and mockups they name as inputs, and the earlier rehearsals' solutions
+ * whose history they start from (REHEARSE-6.2.0), each by id, with the files
+ * that name it. Refuses when one of those files can't be read, since then
+ * what it names can't be known.
+ */
+export function namedInputs(scenarioPath) {
+    return namedInFolder(scenarioPath).inputs;
+}
+function namedInFolder(scenarioPath) {
+    const folder = dirname(resolve(scenarioPath));
+    const named = new Map();
+    const histories = new Map();
+    for (const name of readdirSync(folder).sort()) {
+        if (!name.endsWith(".yaml"))
+            continue;
+        let inputs;
+        try {
+            const file = parse(readFileSync(join(folder, name), "utf8"));
+            inputs = file?.inputs;
+            const source = file?.history?.solution;
+            if (typeof source === "string" && source.trim()) {
+                const id = source.trim();
+                histories.set(id, [...(histories.get(id) ?? []), name]);
+            }
+            for (const entries of Object.values((inputs ?? {}))) {
+                for (const entry of Array.isArray(entries) ? entries : []) {
+                    if (typeof entry !== "string")
+                        continue;
+                    const thing = parseThing(entry);
+                    const id = thing.kind === "document"
+                        ? thing.documentId
+                        : thing.kind === "board"
+                            ? thing.boardId
+                            : thing.kind === "mockup"
+                                ? thing.mockupId
+                                : null;
+                    if (id)
+                        named.set(id, [...(named.get(id) ?? []), name]);
+                }
+            }
+        }
+        catch (error) {
+            throw new Error(`Can't tell what ${name} names as its inputs, so no earlier run was removed: ${error instanceof Error ? error.message : String(error)} Fix it, or rehearse with --keep.`);
+        }
+    }
+    return { inputs: named, histories };
+}
+/**
+ * How long a rehearsal waits for an earlier run's branch to be deleted
+ * before it starts anyway: the deletion is the backend's, scheduled as the
+ * run is removed.
+ */
+const BRANCH_WAIT_MS = 60_000;
+/**
+ * Wait for the backend to delete an earlier run's branch (REHEARSE-6.7):
+ * it must be gone before the new run makes its own, or that one takes a
+ * suffixed name. What became of it, or pending when it took too long.
+ */
+async function branchOutcome(client, removalId, pause) {
+    const deadline = Date.now() + BRANCH_WAIT_MS;
+    for (;;) {
+        const removal = await client.query(api.solutions.branches.removal, { removalId });
+        if (!removal)
+            return null;
+        if (removal.outcome) {
+            return {
+                name: removal.branch,
+                outcome: removal.outcome,
+                ...(removal.why ? { why: removal.why } : {}),
+            };
+        }
+        if (Date.now() >= deadline) {
+            return { name: removal.branch, outcome: "pending" };
+        }
+        await pause(1000);
+    }
+}
+/**
+ * Remove the earlier runs of the scenario, keeping what a scenario names
+ * (REHEARSE-6.0, 6.2), and keeping whole an earlier run whose history a
+ * scenario starts from (6.2.0).
+ */
+export async function removeEarlierRuns(scenarioPath, client, pause = (ms) => new Promise((resolve) => setTimeout(resolve, ms))) {
+    const { inputs: named, histories } = namedInFolder(scenarioPath);
+    const scenario = basename(scenarioPath);
+    const earlier = await client.query(api.solutions.queries.rehearsalsOf, { project: client.project, scenario });
+    const kept = [];
+    const keptRuns = [];
+    const branches = [];
+    let removedRuns = 0;
+    for (const solutionId of earlier) {
+        const startFromIt = histories.get(solutionId);
+        if (startFromIt) {
+            keptRuns.push({ solutionId, namedBy: startFromIt });
+            continue;
+        }
+        removedRuns++;
+        const removed = await client.mutation(api.solutions.mutations.removeRehearsal, {
+            solutionId,
+            keep: [...named.keys()],
+        });
+        // Each of its branches, one per pull-request surface (SOLBRANCH-1.4).
+        for (const removalId of removed.branchRemovals ?? []) {
+            const branch = await branchOutcome(client, removalId, pause);
+            if (branch)
+                branches.push(branch);
+        }
+        for (const thing of removed.kept) {
+            kept.push({
+                reference: `${thing.kind}:${thing.id}`,
+                namedBy: thing.because === "named" ? (named.get(thing.id) ?? []) : [],
+            });
+        }
+    }
+    return {
+        scenario,
+        removed: removedRuns,
+        kept,
+        ...(keptRuns.length > 0 ? { keptRuns } : {}),
+        ...(branches.length > 0 ? { branches } : {}),
+    };
+}
+//# sourceMappingURL=earlier.js.map

package/dist/rehearsal/index.d.ts

@@ -0,0 +1,5 @@
+export { planForOutcomes, planOf } from "./derive.js";
+export { partiesOf, rehearse } from "./driver.js";
+export { renderReport } from "./report.js";
+export type * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/rehearsal/index.js

@@ -0,0 +1,4 @@
+export { planForOutcomes, planOf } from "./derive.js";
+export { partiesOf, rehearse } from "./driver.js";
+export { renderReport } from "./report.js";
+//# sourceMappingURL=index.js.map

package/dist/rehearsal/live.d.ts

@@ -0,0 +1,72 @@
+import { solutionClient } from "../commands/solution/client.js";
+import type { Party, PersonScript, RehearsalClient, Scenario } from "./types.js";
+/**
+ * The live mode (REHEARSE-4): the driver over the CLI's client against the
+ * linked project. Scripted agents run through the same verbs an agent
+ * runs; real agents are the runner's, awaited; the person's decisions are
+ * answered from the scenario's own script, and the rehearsal stops only at
+ * a decision nobody scripted.
+ */
+/** The scenario as a file: plans and artifacts by name, scripts as data. */
+export type ScenarioFile = {
+    title: string;
+    /** What the person wrote about the solution beyond its title, as Markdown. */
+    description?: string;
+    /**
+     * "default" for the project's plan; a path to a plan file; or some of
+     * either's outcomes, run on their own: `{ from: default, outcomes: [Code,
+     * Demo] }`, or `outcome: Pitch` for one. `step` and `steps` are read as
+     * `outcome` and `outcomes`.
+     */
+    plan: "default" | string | {
+        from?: "default" | string;
+        outcome?: string;
+        outcomes?: string[];
+        step?: string;
+        steps?: string[];
+    };
+    /**
+     * The branch the solution's branch is made from, rather than the
+     * repository's default branch (REHEARSE-4.5): `branch: rehearsal-fixtures/spec`.
+     */
+    branch?: string;
+    /**
+     * An earlier rehearsal's solution and an outcome it made, whose history
+     * the solution starts with (REHEARSE-4.8):
+     * `history: { solution: q97fe7s7…, after: Code }`. Each input `inputs`
+     * doesn't name is taken from that solution as it stood when that outcome
+     * was made, with its thread.
+     */
+    history?: {
+        solution?: unknown;
+        after?: unknown;
+    };
+    /**
+     * Artifacts by input name: references; `image:<path>` for an image, its
+     * path from the scenario's folder, to upload first (REHEARSE-4.7); or
+     * { file } to publish first.
+     */
+    inputs?: Record<string, Array<string | {
+        file: string;
+        title?: string;
+    }>>;
+    /**
+     * By agent (`Code Reviewer`, `Pitch/drafter`), by an outcome's name (its
+     * drafter), by "<outcome>/reviewer" (its reviewers), or by
+     * "<outcome>/<agent>": "real", or a script as data (`Scenario.parties`).
+     */
+    parties?: Record<string, "real" | Omit<Party, "expect">>;
+    /** What the person answers, by an outcome's name or a checkpoint's, in order asked. */
+    person?: PersonScript;
+    /** Minutes to wait for a real agent. */
+    wait?: number;
+};
+/** The scenario file read into a scenario the driver runs. */
+export declare function scenarioFrom(path: string, client: ReturnType<typeof solutionClient>): Promise<Scenario>;
+/**
+ * The driver's client over the CLI: the project secret for every call. The
+ * solution is created as a rehearsal's, which is what lets that same secret
+ * answer the decisions the scenario scripted.
+ */
+export declare function liveClient(): RehearsalClient;
+//# sourceMappingURL=live.d.ts.map