@popoverai/dotrequirements 0.32.1 → 0.34.0

package/dist/commands/link.js

@@ -1,15 +1,17 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { ConvexHttpClient } from "convex/browser";
-import { getConvexUrl } from "../config.js";
+import { convexUrl } from "../cloud.js";
 import { api } from "../convex.js";
 import { WEB_APP_URL } from "../push/index.js";
 import { brand } from "../utils/brand.js";
+import { commandErrorMessage } from "../utils/command-error.js";
 import { ensureGitignore } from "../utils/gitignore.js";
 import { executeOAuthFlow } from "../utils/oauth-flow.js";
 import { getOrCreateProjectSecret, promptExpiryDays, selectTeam, } from "../utils/project-selector.js";
 import { findProjectRoot, readProjectSettings, writeProjectSettings, } from "../utils/project-settings.js";
 import { promptChoice, promptConfirm } from "../utils/prompts.js";
+import { markVersionMessagesShown, versionMessages, } from "../version-messages.js";
 import { hasCapacity, isNonInteractive, resolveProject, resolveProjectName, resolveTeam, } from "./link-resolution.js";
 import { syncCommand } from "./sync.js";
 /**
@@ -47,10 +49,13 @@ async function runNonInteractiveLink(options) {
     if (options.json) {
         console.log = (...args) => console.error(...args);
     }
+    // CLI-MSG-1.1: the JSON result carries the cloud's messages, so it is
+    // printed once the command is done and they are in.
+    let jsonOutcome = null;
     const finish = (outcome) => {
         console.log = originalLog;
         if (options.json) {
-            originalLog(JSON.stringify(outcome));
+            jsonOutcome = outcome;
         }
         else if (outcome.status === "decision_needed") {
             console.log(`\n${outcome.message}`);
@@ -101,7 +106,7 @@ async function runNonInteractiveLink(options) {
         }
         // LINK-3 / LINK-10.7: browser auth is the only human step
         const oauthResult = await executeOAuthFlow();
-        const client = new ConvexHttpClient(getConvexUrl());
+        const client = new ConvexHttpClient(convexUrl());
         client.setAuth(oauthResult.accessToken);
         await client.mutation(api.teams.mutations.ensureDefaultTeam, {});
         const teams = (await client.query(api.teams.queries.listForUserWithUsage));
@@ -201,12 +206,9 @@ async function runNonInteractiveLink(options) {
         if (projectResolution.rename) {
             const newName = resolveProjectName(options, readPackageName(cwd), path.basename(cwd));
             try {
-                await client.mutation(api.projects.mutations.update, {
-                    target: {
-                        type: "project",
-                        // biome-ignore lint/suspicious/noExplicitAny: CLI workspace doesn't import convex's branded Id type; the runtime value is a plain string the server validates.
-                        id: projectResolution.project.projectId,
-                    },
+                await client.mutation(api.projects.mutations.updateProject, {
+                    // biome-ignore lint/suspicious/noExplicitAny: CLI workspace doesn't import convex's branded Id type; the runtime value is a plain string the server validates.
+                    projectId: projectResolution.project.projectId,
                     name: newName,
                 });
                 projectName = newName;
@@ -234,13 +236,17 @@ async function runNonInteractiveLink(options) {
         });
     }
     catch (error) {
-        finish({
-            status: "error",
-            message: error instanceof Error ? error.message : String(error),
-        });
+        finish({ status: "error", message: commandErrorMessage(error) });
     }
     finally {
         console.log = originalLog;
+        // Here, not after the block: every outcome above returns from inside
+        // `try`. Assigned inside `finish`, which TypeScript can't follow.
+        const outcome = jsonOutcome;
+        if (outcome) {
+            originalLog(JSON.stringify({ ...outcome, messages: await versionMessages() }));
+            markVersionMessagesShown();
+        }
     }
 }
 /**
@@ -253,18 +259,18 @@ async function runNonInteractiveLink(options) {
 async function mintShareArtifacts(client, teamId, projectId) {
     const artifacts = {};
     try {
-        const invite = (await client.mutation(api.teamInvites.mutations.createInvite, 
+        const invite = (await client.mutation(api.teamInvites.mutations.createInviteLink, 
         // biome-ignore lint/suspicious/noExplicitAny: CLI workspace doesn't import convex's branded Id type; the runtime value is a plain string the server validates.
-        { target: { type: "team", id: teamId } }));
+        { teamId: teamId }));
         artifacts.inviteUrl = `${WEB_APP_URL}/invite/${invite.token}`;
     }
     catch {
         // LINK-13.3: admin-gated — omit the invite URL for non-admin members
     }
     try {
-        const share = (await client.mutation(api.projectSecrets.mutations.ensureShareToken, 
+        const share = (await client.mutation(api.projectSecrets.mutations.ensureProjectShareToken, 
         // biome-ignore lint/suspicious/noExplicitAny: CLI workspace doesn't import convex's branded Id type; the runtime value is a plain string the server validates.
-        { target: { type: "project", id: projectId } }));
+        { projectId: projectId }));
         artifacts.shareSyncCommand = `npx -y @popoverai/dotrequirements@latest sync --share ${share.token}`;
     }
     catch {
@@ -273,9 +279,9 @@ async function mintShareArtifacts(client, teamId, projectId) {
     return artifacts;
 }
 async function listProjects(client, teamId) {
-    const projects = (await client.query(api.projectSecrets.queries.listOwnSecretsForTeam, 
+    const projects = (await client.query(api.projectSecrets.queries.listOwnForTeam, 
     // biome-ignore lint/suspicious/noExplicitAny: CLI workspace doesn't import convex's branded Id type; the runtime value is a plain string the server validates.
-    { target: { type: "team", id: teamId } }));
+    { teamId: teamId }));
     return projects.map((p) => ({
         projectId: p.projectId,
         projectName: p.projectName,
@@ -349,7 +355,7 @@ async function runInteractiveLink(options) {
             return;
         }
         // Set up authenticated client using the session token
-        const client = new ConvexHttpClient(getConvexUrl());
+        const client = new ConvexHttpClient(convexUrl());
         client.setAuth(oauthResult.accessToken);
         // LINK-4: Select team
         const selectedTeam = await selectTeam(client);
@@ -417,7 +423,7 @@ async function runInteractiveLink(options) {
         console.log("\nDocumentation: https://docs.dotrequirements.io/getting-started");
     }
     catch (error) {
-        console.error(`\n✗ Error: ${error instanceof Error ? error.message : String(error)}`);
+        console.error(`\n✗ Error: ${commandErrorMessage(error)}`);
         // LINK-8: Network error guidance
         if (error instanceof Error && error.message.includes("fetch")) {
             console.error("\nCheck your internet connection and try again.");

package/dist/commands/mockup/index.d.ts

@@ -0,0 +1,11 @@
+import type { Command } from "commander";
+export declare function guideCommand(): Promise<void>;
+export declare function createCommand(options: {
+    title: string;
+    file: string;
+}): Promise<void>;
+export declare function previewCommand(mockupId: string, options: {
+    out?: string;
+}): Promise<void>;
+export declare function registerMockup(program: Command): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/commands/mockup/index.js

@@ -0,0 +1,82 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { webApiUrl } from "../../cloud.js";
+import { api } from "../../convex.js";
+import { getProjectCredentials } from "../../utils/project-settings.js";
+import { solutionClient } from "../solution/client.js";
+/**
+ * Hidden from help until solutions launch: today's users see the CLI they
+ * have now, and the server refuses these commands for a team without the
+ * solutions switch (SOLACCESS-2).
+ */
+const HIDDEN_UNTIL_LAUNCH = { hidden: true };
+/**
+ * Mockups from the shell (SIGHT-5): the guide, a mockup made from a file,
+ * and a mockup rendered to a file an agent can open in its browser. The
+ * guide and the render come through the app, which owns the dialect's
+ * text and its renderer; the create goes to the backend.
+ */
+async function throughApp(path, extra) {
+    const { projectId, projectSecret } = getProjectCredentials();
+    const base = webApiUrl();
+    const response = await fetch(`${base}${path}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ projectId, projectSecret, ...extra }),
+    });
+    if (!response.ok) {
+        const body = (await response.json().catch(() => ({})));
+        throw new Error(body.error || response.statusText);
+    }
+    return response;
+}
+export async function guideCommand() {
+    const response = await throughApp("/api/mockups/guide", {});
+    const { guide } = (await response.json());
+    process.stdout.write(`${guide}\n`);
+}
+export async function createCommand(options) {
+    const markup = readFileSync(resolve(options.file), "utf8");
+    const client = solutionClient();
+    const { mockupId } = await client.mutation(api.mockups.mutations.create, { project: client.project, title: options.title, markup });
+    console.log(`Created mockup ${mockupId}. Submit it as mockup:${mockupId}; render it with: dotreq mockup preview ${mockupId} --out mockup.html`);
+}
+export async function previewCommand(mockupId, options) {
+    const response = await throughApp("/api/mockups/frame", { mockupId });
+    const html = await response.text();
+    const out = resolve(options.out ?? `mockup-${mockupId}.html`);
+    writeFileSync(out, html);
+    console.log(`Wrote ${out}. Look at it: agent-browser open file://${out} && agent-browser screenshot mockup.png`);
+}
+export function registerMockup(program) {
+    const mockup = program
+        .command("mockup", HIDDEN_UNTIL_LAUNCH)
+        .description("Make and look at wireframe mockups");
+    mockup
+        .command("guide")
+        .description("Print the mockup authoring guide: the markup dialect, the components, a complete example")
+        .action(wrap(guideCommand));
+    mockup
+        .command("create")
+        .description("Create a mockup in the project from a markup file")
+        .requiredOption("--title <title>", "The mockup's title")
+        .requiredOption("--file <path>", "The markup file")
+        .action(wrap(createCommand));
+    mockup
+        .command("preview <mockup-id>")
+        .description("Render a mockup to a self-contained HTML file, to open in a browser")
+        .option("--out <path>", "Where to write it (default: mockup-<id>.html)")
+        .action(wrap(previewCommand));
+}
+function wrap(fn) {
+    return async (...args) => {
+        try {
+            await fn(...args);
+        }
+        catch (error) {
+            console.error(`\nError: ${error instanceof Error ? error.message : String(error)}\n`);
+            process.exitCode = 1;
+        }
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/commands/report.js

@@ -1,9 +1,10 @@
+import { convexUrl } from "../cloud.js";
 import { findRequirementsDir, readCoverageCache } from "../harness/cache.js";
 import { formatUnrecordedNotice } from "../harness/reportingStatus.js";
 import { getProjectCoverage, getRequirementCoverage, } from "../requirements/cloud-coverage.js";
 import { buildLocalReport, } from "../requirements/coverage.js";
 import { findProjectRoot, getProjectCredentials, } from "../utils/project-settings.js";
-const CONVEX_URL = "https://data.dotrequirements.io";
+import { markVersionMessagesShown, versionMessages, } from "../version-messages.js";
 export async function reportCommand(options) {
     const source = options.source ?? "local";
     const format = options.format ?? "console";
@@ -52,24 +53,28 @@ export async function reportCommand(options) {
     if (options.requirement) {
         // REPORT-CLOUD-1.7: --branch/--since apply to the requirement-scoped
         // output too, not just the project-wide report
-        const record = await getRequirementCoverage(options.requirement, projectId, projectSecret, CONVEX_URL, {
+        const record = await getRequirementCoverage(options.requirement, projectId, projectSecret, convexUrl(), {
             branch: options.branch,
             sinceTimestamp: options.since,
         });
         console.log(printCloudRequirement(record, format, {
             branch: options.branch,
             since: options.since,
-        }));
+        }, format === "json" ? await versionMessages() : []));
+        if (format === "json")
+            markVersionMessagesShown();
         return;
     }
-    const record = await getProjectCoverage(projectId, projectSecret, CONVEX_URL, {
+    const record = await getProjectCoverage(projectId, projectSecret, convexUrl(), {
         branch: options.branch,
         sinceTimestamp: options.since,
     });
     console.log(printCloudProject(record, format, {
         branch: options.branch,
         since: options.since,
-    }));
+    }, format === "json" ? await versionMessages() : []));
+    if (format === "json")
+        markVersionMessagesShown();
 }
 function printLocalReport(report, format) {
     switch (format) {
@@ -122,9 +127,10 @@ function formatLocalMarkdown(report) {
     }
     return out;
 }
-function printCloudRequirement(record, format, filters) {
+function printCloudRequirement(record, format, filters, messages = []) {
     if (format === "json") {
-        return JSON.stringify({ source: "cloud", requirement: record }, null, 2);
+        // CLI-MSG-1.1: the cloud's messages for this version travel in the JSON.
+        return JSON.stringify({ source: "cloud", requirement: record, messages }, null, 2);
     }
     if (!record.lastTestedAt) {
         // REPORT-CLOUD-1.7: with filters in play, an empty record means nothing
@@ -168,9 +174,16 @@ function printCloudRequirement(record, format, filters) {
     }
     return lines.join("\n");
 }
-function printCloudProject(record, format, filters) {
+function printCloudProject(record, format, filters, messages = []) {
     if (format === "json") {
-        return JSON.stringify({ source: "cloud", filters, summary: cloudSummary(record), ...record }, null, 2);
+        // CLI-MSG-1.1: the cloud's messages for this version travel in the JSON.
+        return JSON.stringify({
+            source: "cloud",
+            filters,
+            summary: cloudSummary(record),
+            ...record,
+            messages,
+        }, null, 2);
     }
     const summary = cloudSummary(record);
     const filterNote = formatCloudFilters(filters);

package/dist/commands/review-test.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { DEFAULT_API_BASE_URL, fetchReviewTestFeedback, } from "../requirements/cloud-ai.js";
+import { webApiUrl } from "../cloud.js";
+import { fetchReviewTestFeedback } from "../requirements/cloud-ai.js";
 import { findRequirementsInFile } from "../requirements/grep.js";
 import { formatRequirementTree, getRequirementTree, loadAllRequirements, } from "../requirements/index.js";
 import { getProjectCredentials } from "../utils/project-settings.js";
@@ -145,7 +146,7 @@ async function runCloudReview(params) {
             `(${error instanceof Error ? error.message : String(error)})`);
     }
     // CLI-REVIEW-3.0 / .1 / .3: dispatch to the hosted endpoint
-    const apiBaseUrl = process.env.DOTREQUIREMENTS_API_URL ?? DEFAULT_API_BASE_URL;
+    const apiBaseUrl = webApiUrl();
     let feedback;
     let quotaWarning;
     try {

package/dist/commands/scores/index.d.ts

@@ -0,0 +1,50 @@
+import type { Command } from "commander";
+import type { Scores } from "../solution/things.js";
+/**
+ * Scores from the shell (VERB-7, SCORES-1): a solution's price on CREATED's
+ * seven axes, made with `create` and revised with `update`, each axis a
+ * whole number from 1 to 5 with a reason. Like a board or a mockup, scores
+ * are a thing: `create` prints the `scores:<id>` a writer submits with
+ * `dotreq solution author`, whose comment says what changed and why.
+ * Nothing reaches the backend unless every axis is whole, and the backend
+ * refuses the same again.
+ */
+/**
+ * The seven axes as `dotreq scores` takes them (VERB-7): the key the backend stores,
+ * the name a person reads, and the option, which is also how a line of the
+ * reasons file names the axis. The backend's own list is
+ * packages/convex/solutions/scores.ts; the CLI can't import it, so a test
+ * keeps the two equal.
+ */
+export declare const AXES: ReadonlyArray<{
+    key: keyof Scores;
+    label: string;
+    option: string;
+}>;
+export type ScoresOptions = {
+    costOfDelay?: string;
+    relevance?: string;
+    entities?: string;
+    api?: string;
+    testing?: string;
+    experience?: string;
+    doubt?: string;
+    /** A file with one line per axis: `<axis>: <reason>`. */
+    reasons?: string;
+};
+/**
+ * Each axis's reason from the reasons file (VERB-7.0): one line an axis,
+ * `<axis>: <reason>`, the axis spelled as its option is, in any case; a
+ * leading "- " and blank lines are passed over. Refuses a line in another
+ * form, an axis that isn't one of the seven or is named twice (VERB-7.3),
+ * and an axis with no reason (VERB-7.2).
+ */
+export declare function reasonsFrom(text: string, file: string): Record<keyof Scores, string>;
+/** `dotreq scores create`: new scores, and the reference to record them by (VERB-7.0). */
+export declare function createCommand(options: ScoresOptions): Promise<void>;
+/** `dotreq scores update <id>`: all seven axes again, for a revision (VERB-7.1). */
+export declare function updateCommand(scoresId: string, options: ScoresOptions): Promise<void>;
+/** The axes, the reasons file and an example, on `scores --help` (VERB-7.4). */
+export declare const SCORES_HELP = "\nScores are seven axes, each a whole number from 1 to 5 with one line of reasoning:\n  suitability, whether to do this now:\n    --cost-of-delay, --relevance\n  appetite, what it takes to build and how likely the other six are wrong:\n    --entities, --api, --testing, --experience, --doubt\n\nThe reasons file has one line per axis, the axis named as its option is,\nwithout the dashes:\n  cost-of-delay: <why this score>\n  relevance: <why>\n  entities: <why>\n  api: <why>\n  testing: <why>\n  experience: <why>\n  doubt: <why>\n\ncreate prints the scores' reference; record them with it, as any work is\nrecorded. To revise them, update them with all seven axes again and record\nthem again.\n\nExamples:\n  dotreq scores create --cost-of-delay 4 --relevance 3 --entities 2 --api 2 \\\n    --testing 2 --experience 3 --doubt 2 --reasons reasons.txt\n  dotreq solution author scores:<id> --comment \"Scored against the pitch's draft and the discovery board.\"\n  dotreq scores update <id> --cost-of-delay 4 --relevance 3 --entities 3 --api 2 \\\n    --testing 2 --experience 3 --doubt 3 --reasons reasons.txt\n";
+export declare function registerScores(program: Command): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/commands/scores/index.js

@@ -0,0 +1,190 @@
+import { readFileSync } from "node:fs";
+import { api } from "../../convex.js";
+import { solutionClient } from "../solution/client.js";
+/**
+ * Hidden from help until solutions launch: today's users see the CLI they
+ * have now, and the server refuses these commands for a team without the
+ * solutions switch (SOLACCESS-2).
+ */
+const HIDDEN_UNTIL_LAUNCH = { hidden: true };
+/**
+ * Scores from the shell (VERB-7, SCORES-1): a solution's price on CREATED's
+ * seven axes, made with `create` and revised with `update`, each axis a
+ * whole number from 1 to 5 with a reason. Like a board or a mockup, scores
+ * are a thing: `create` prints the `scores:<id>` a writer submits with
+ * `dotreq solution author`, whose comment says what changed and why.
+ * Nothing reaches the backend unless every axis is whole, and the backend
+ * refuses the same again.
+ */
+/**
+ * The seven axes as `dotreq scores` takes them (VERB-7): the key the backend stores,
+ * the name a person reads, and the option, which is also how a line of the
+ * reasons file names the axis. The backend's own list is
+ * packages/convex/solutions/scores.ts; the CLI can't import it, so a test
+ * keeps the two equal.
+ */
+export const AXES = [
+    { key: "costOfDelay", label: "Cost of delay", option: "cost-of-delay" },
+    { key: "relevance", label: "Relevance", option: "relevance" },
+    { key: "entities", label: "Entities", option: "entities" },
+    { key: "api", label: "API", option: "api" },
+    { key: "testing", label: "Testing", option: "testing" },
+    { key: "experience", label: "Experience", option: "experience" },
+    { key: "doubt", label: "Doubt", option: "doubt" },
+];
+const AXIS_NAMES = `The axes are ${AXES.map((axis) => axis.option).join(", ")}.`;
+/** Each axis's score from its option, or a refusal naming the axis (VERB-7.2). */
+function scoresFrom(options) {
+    const scores = {};
+    for (const axis of AXES) {
+        const given = options[axis.key]?.trim();
+        if (!given) {
+            throw new Error(`${axis.label} has no score: give it with --${axis.option} <1-5>.`);
+        }
+        const score = Number(given);
+        if (!/^\d+$/.test(given) || score < 1 || score > 5) {
+            throw new Error(`${axis.label} is scored "${given}": a score is a whole number from 1 to 5.`);
+        }
+        scores[axis.key] = score;
+    }
+    return scores;
+}
+/**
+ * Each axis's reason from the reasons file (VERB-7.0): one line an axis,
+ * `<axis>: <reason>`, the axis spelled as its option is, in any case; a
+ * leading "- " and blank lines are passed over. Refuses a line in another
+ * form, an axis that isn't one of the seven or is named twice (VERB-7.3),
+ * and an axis with no reason (VERB-7.2).
+ */
+export function reasonsFrom(text, file) {
+    const reasons = {};
+    const lines = text.split(/\r?\n/);
+    lines.forEach((raw, index) => {
+        const line = raw.trim().replace(/^-\s+/, "");
+        if (!line)
+            return;
+        const colon = line.indexOf(":");
+        if (colon === -1) {
+            throw new Error(`Line ${index + 1} of ${file} isn't "<axis>: <reason>": "${raw.trim()}". ${AXIS_NAMES}`);
+        }
+        const name = line.slice(0, colon).trim().toLowerCase();
+        const axis = AXES.find((a) => a.option === name);
+        if (!axis) {
+            throw new Error(`"${name}" in ${file} isn't an axis. ${AXIS_NAMES}`);
+        }
+        if (reasons[axis.key] !== undefined) {
+            throw new Error(`"${name}" is named twice in ${file}. ${AXIS_NAMES}`);
+        }
+        reasons[axis.key] = line.slice(colon + 1).trim();
+    });
+    for (const axis of AXES) {
+        if (!reasons[axis.key]) {
+            throw new Error(`${axis.label} has no reason: add the line "${axis.option}: <why>" to ${file}.`);
+        }
+    }
+    return reasons;
+}
+/** The seven axes, checked, from the options and the reasons file. */
+function axesFrom(options) {
+    const scores = scoresFrom(options);
+    const file = options.reasons?.trim();
+    if (!file) {
+        throw new Error(`Give each axis's reason in a file: --reasons <file>, one line per axis, "<axis>: <reason>". ${AXIS_NAMES}`);
+    }
+    let text;
+    try {
+        text = readFileSync(file, "utf8");
+    }
+    catch {
+        throw new Error(`Can't read the reasons file ${file}.`);
+    }
+    const reasons = reasonsFrom(text, file);
+    return Object.fromEntries(AXES.map((axis) => [
+        axis.key,
+        { score: scores[axis.key], reason: reasons[axis.key] },
+    ]));
+}
+/** `dotreq scores create`: new scores, and the reference to record them by (VERB-7.0). */
+export async function createCommand(options) {
+    const axes = axesFrom(options);
+    const client = solutionClient();
+    const { scoresId } = await client.mutation(api.scores.mutations.create, { project: client.project, ...axes });
+    console.log(`Created scores ${scoresId}. Record them with: dotreq solution author scores:${scoresId} --comment "..."`);
+}
+/** `dotreq scores update <id>`: all seven axes again, for a revision (VERB-7.1). */
+export async function updateCommand(scoresId, options) {
+    const axes = axesFrom(options);
+    // Named by its id or by the reference `create` printed.
+    const id = scoresId.replace(/^scores:/, "");
+    await solutionClient().mutation(api.scores.mutations.update, {
+        scoresId: id,
+        ...axes,
+    });
+    console.log(`Updated scores ${id}. Record the revision with: dotreq solution author scores:${id} --comment "..."`);
+}
+/** The axes, the reasons file and an example, on `scores --help` (VERB-7.4). */
+export const SCORES_HELP = `
+Scores are seven axes, each a whole number from 1 to 5 with one line of reasoning:
+  suitability, whether to do this now:
+    --cost-of-delay, --relevance
+  appetite, what it takes to build and how likely the other six are wrong:
+    --entities, --api, --testing, --experience, --doubt
+
+The reasons file has one line per axis, the axis named as its option is,
+without the dashes:
+  cost-of-delay: <why this score>
+  relevance: <why>
+  entities: <why>
+  api: <why>
+  testing: <why>
+  experience: <why>
+  doubt: <why>
+
+create prints the scores' reference; record them with it, as any work is
+recorded. To revise them, update them with all seven axes again and record
+them again.
+
+Examples:
+  dotreq scores create --cost-of-delay 4 --relevance 3 --entities 2 --api 2 \\
+    --testing 2 --experience 3 --doubt 2 --reasons reasons.txt
+  dotreq solution author scores:<id> --comment "Scored against the pitch's draft and the discovery board."
+  dotreq scores update <id> --cost-of-delay 4 --relevance 3 --entities 3 --api 2 \\
+    --testing 2 --experience 3 --doubt 3 --reasons reasons.txt
+`;
+/** The seven axis options and the reasons file, on both subcommands. */
+function axisOptions(command) {
+    return command
+        .option("--cost-of-delay <n>", "Cost of delay, 1 to 5")
+        .option("--relevance <n>", "Relevance, 1 to 5")
+        .option("--entities <n>", "Entities, 1 to 5")
+        .option("--api <n>", "API, 1 to 5")
+        .option("--testing <n>", "Testing, 1 to 5")
+        .option("--experience <n>", "Experience, 1 to 5")
+        .option("--doubt <n>", "Doubt, 1 to 5")
+        .option("--reasons <file>", "A file with one line per axis, <axis>: <reason> (required)")
+        .addHelpText("after", SCORES_HELP);
+}
+export function registerScores(program) {
+    const scores = program
+        .command("scores", HIDDEN_UNTIL_LAUNCH)
+        .description("Make and revise a solution's scores: seven axes, each a whole number from 1 to 5 with a reason")
+        .addHelpText("after", SCORES_HELP);
+    axisOptions(scores
+        .command("create")
+        .description("Make scores from the seven axis options and a reasons file, and print the reference to record them by")).action(wrap(createCommand));
+    axisOptions(scores
+        .command("update <scores>")
+        .description("Revise scores, named by their id or scores:<id>, with all seven axes again; record them again with author")).action(wrap(updateCommand));
+}
+function wrap(fn) {
+    return async (...args) => {
+        try {
+            await fn(...args);
+        }
+        catch (error) {
+            console.error(`\nError: ${error instanceof Error ? error.message : String(error)}\n`);
+            process.exitCode = 1;
+        }
+    };
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,9 @@
+import { type WhereOptions } from "./run-file.js";
+/**
+ * `dotreq solution ask <request-file>`: the drafter puts a decision to the
+ * owner, on the outcome it is drafting or the one `--outcome` names. A
+ * reviewer escalates instead (`dotreq solution review escalate`), and the
+ * backend refuses its question (VERB-3.5).
+ */
+export declare function askCommand(file: string, options: WhereOptions): Promise<void>;
+//# sourceMappingURL=ask.d.ts.map

package/dist/commands/solution/ask.js

@@ -0,0 +1,27 @@
+import { api } from "../../convex.js";
+import { solutionClient } from "./client.js";
+import { pushBeforeRecord } from "./pushing.js";
+import { readRequest } from "./request.js";
+import { onOutcome, requireWhere } from "./run-file.js";
+/**
+ * `dotreq solution ask <request-file>`: the drafter puts a decision to the
+ * owner, on the outcome it is drafting or the one `--outcome` names. A
+ * reviewer escalates instead (`dotreq solution review escalate`), and the
+ * backend refuses its question (VERB-3.5).
+ */
+export async function askCommand(file, options) {
+    const request = readRequest(file);
+    const where = requireWhere(options);
+    const { solutionId, agent } = where;
+    const client = solutionClient();
+    // SOLBRANCH-3.0: the drafter's commits reach the branch before Quinn is asked.
+    await pushBeforeRecord(client, where);
+    await client.mutation(api.solutions.mutations.ask, {
+        solutionId,
+        agent,
+        ...(where.outcome ? { outcome: where.outcome } : {}),
+        request,
+    });
+    console.log(`Asked${onOutcome(where.outcome)}. It waits on the owner's decision.`);
+}
+//# sourceMappingURL=ask.js.map

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

@@ -0,0 +1,19 @@
+import { type WhereOptions } from "./run-file.js";
+import { type SummaryOptions } from "./summary.js";
+export type AuthorOptions = WhereOptions & SummaryOptions & {
+    /** What changed and why, for the outcome's thread (VERB-1.1, STEP-REVIEW-5.0). */
+    comment?: string;
+    /** Each reference's name on the outcome's tab: one per reference, in their order, or none (SIGHT-12.3). */
+    title?: string[];
+};
+/**
+ * `dotreq solution author <reference>... --comment "<what changed and why>"`:
+ * the drafter's submission of the outcome it is drafting, or of the one
+ * `--outcome` names. The references say where what it made is; the comment
+ * is what the next reader of the thread sees first, so nothing is recorded
+ * without it (VERB-1.2). On an outcome no agent reviews, the work goes to
+ * the owner with the executive summary, `--executive-summary "..."`, which
+ * the backend asks for there (VERB-1.6).
+ */
+export declare function authorCommand(references: string[], options: AuthorOptions): Promise<void>;
+//# sourceMappingURL=author.d.ts.map