@popoverai/dotrequirements 0.32.1 → 0.34.0

package/dist/sync/snapshot.js

@@ -1,14 +1,14 @@
 /**
  * Snapshot acquisition for the comparator — kept separate from comparison so
  * the comparator stays a pure function (compare.ts). The local half reads the
- * workspace; the cloud half is one exportProjectForCli query.
+ * workspace; the cloud half is one export query.
  */
 import * as fs from "node:fs";
 import { ConvexHttpClient } from "convex/browser";
 import YAML from "yaml";
-import { getConvexUrl } from "../config.js";
+import { convexUrl } from "../cloud.js";
 import { api } from "../convex.js";
-import { findRequirementsFiles } from "../requirements/index.js";
+import { findRequirementsFiles, findSyncedFiles, } from "../requirements/index.js";
 import { splitLeadingH1, validateMetadata } from "../schema/index.js";
 import { parseRequirementBlocksFromMarkdown, splitFrontmatter, stripFrontmatterBlock, } from "../schema/parser-core.js";
 /**
@@ -33,6 +33,8 @@ export function readLocalDocument(filePath) {
     let title;
     let defaultPrefix;
     let attachments;
+    let solution;
+    let outcome;
     let frontmatterError;
     const split = splitFrontmatter(raw);
     if (split) {
@@ -57,6 +59,11 @@ export function readLocalDocument(filePath) {
                     title = d.title;
                 if (typeof d.defaultPrefix === "string")
                     defaultPrefix = d.defaultPrefix;
+                // SOLDOC-5: the belonging, read like the id — before validation.
+                if (typeof d.solution === "string")
+                    solution = d.solution;
+                if (typeof d.outcome === "string")
+                    outcome = d.outcome;
                 // ATTACH-10.1: attachments from frontmatter. Shape-filtered here for
                 // the same reason as the fields above; a malformed entry is caught by
                 // validateMetadata below and flags the file rather than half-syncing.
@@ -108,6 +115,8 @@ export function readLocalDocument(filePath) {
         title: derivedTitle,
         defaultPrefix,
         attachments,
+        solution,
+        outcome,
         body,
     };
 }
@@ -115,26 +124,66 @@ export function readLocalDocument(filePath) {
  * Build the local snapshot from the workspace, or from an explicit set of file
  * paths (scope). Files are always read fresh from disk.
  */
-export async function acquireLocalSnapshot(workspaceRoot, filePaths) {
-    const paths = filePaths ?? (await findRequirementsFiles(workspaceRoot));
+export async function acquireLocalSnapshot(workspaceRoot, filePaths, options = {}) {
+    // SOLACCESS-2.2: a project whose team doesn't have solutions syncs the
+    // files it always did — solution directories' Markdown is left alone.
+    const paths = filePaths ??
+        (options.solutions === false
+            ? await findRequirementsFiles(workspaceRoot)
+            : await findSyncedFiles(workspaceRoot));
     return { documents: paths.map(readLocalDocument) };
 }
 /**
- * Build the cloud snapshot with one exportProjectForCli query. A share token is
- * passed as the projectSecret with no slug (the read-only wrapper resolves the
- * project from the token) — the read-only path never writes back.
+ * The project's solutions as the sync places files by them (SOLDOC-4), or
+ * null when the project's team doesn't have solutions, so the sync behaves
+ * as it did before solutions (SOLACCESS-2.2). Whether it has them is the
+ * export's answer — the one the cloud side was read with — so the local
+ * side can't follow a different one. A share run places nothing, so it
+ * needs no list. A failure to fetch the list fails the sync, as does a
+ * switch flipped between the two reads: guessing would leave solution
+ * documents out of the repo's side, and a repo-wins sync would delete them
+ * from the cloud.
+ */
+export async function projectSolutions(auth, cloud) {
+    if (cloud.solutions !== true)
+        return null;
+    if (!auth.projectSlug)
+        return [];
+    const client = new ConvexHttpClient(convexUrl());
+    const answer = await client.query(api.solutions.queries.forSync, {
+        projectAuth: {
+            projectSlug: auth.projectSlug,
+            projectSecret: auth.projectSecret,
+        },
+        project: auth.projectSlug,
+    });
+    if (!Array.isArray(answer)) {
+        throw new Error("The project's solutions were switched off while syncing. Run the sync again.");
+    }
+    return answer;
+}
+/**
+ * Build the cloud snapshot with one export query: the project's own, with a
+ * project secret, or the share endpoint, with a bare share token (the token
+ * names the project) — the read-only path never writes back.
  */
 export async function acquireCloudSnapshot(auth) {
-    const client = new ConvexHttpClient(getConvexUrl());
-    const projectAuth = auth.projectSlug
-        ? { projectSlug: auth.projectSlug, projectSecret: auth.projectSecret }
-        : { projectSecret: auth.projectSecret };
-    const result = (await client.query(api.documents.queries.exportProjectForCli, {
-        projectAuth,
-    }));
+    const client = new ConvexHttpClient(convexUrl());
+    const result = (await (auth.projectSlug
+        ? client.query(api.documents.queries.exportProject, {
+            projectAuth: {
+                projectSlug: auth.projectSlug,
+                projectSecret: auth.projectSecret,
+            },
+            project: auth.projectSlug,
+        })
+        : client.query(api.documents.queries.exportProjectForShare, {
+            shareToken: auth.projectSecret,
+        })));
     return {
         projectName: result.projectName,
         projectSlug: result.projectSlug,
+        solutions: result.solutions === true,
         documents: result.documents.map((d) => ({
             documentId: d.documentId,
             title: d.title,
@@ -143,7 +192,35 @@ export async function acquireCloudSnapshot(auth) {
             body: d.markdownContent,
             version: d.version,
             updatedAt: d.updatedAt,
+            solution: d.solution,
+            isRequirementsDoc: d.isRequirementsDoc,
         })),
     };
 }
+/**
+ * SYNC-FAIL-5: of the ids the workspace's files carry, the ones that name
+ * another project's document, each with the words a push of that file gets,
+ * so `dotreq diff` says what `dotreq sync` will. A backend that can't answer
+ * leaves the diff as it was rather than failing it.
+ */
+export async function foreignDocumentNotes(auth, documentIds) {
+    // A share token only syncs down, so it pushes nothing to warn about.
+    if (documentIds.length === 0 || !auth.projectSlug)
+        return new Map();
+    const client = new ConvexHttpClient(convexUrl());
+    try {
+        const foreign = (await client.query(api.documents.queries.foreignDocumentIds, {
+            projectAuth: {
+                projectSlug: auth.projectSlug,
+                projectSecret: auth.projectSecret,
+            },
+            project: auth.projectSlug,
+            documentIds,
+        }));
+        return new Map(foreign.map((f) => [f.documentId, f.message]));
+    }
+    catch {
+        return new Map();
+    }
+}
 //# sourceMappingURL=snapshot.js.map

package/dist/sync/solution-documents.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Where a solution's documents live, the sync's half (SOLDOC; the decision
+ * is in docs/working/four-areas-prototype.md, "Where a solution's documents
+ * live"). A document that belongs to a solution and is not a requirements
+ * document lives in a solution directory, `.requirements/solutions/<solution>/`,
+ * named for its outcome; the `.requirements.md` name is what makes a file a
+ * requirements document, wherever it sits. A new file declares its belonging
+ * by its path; once the frontmatter carries it, the frontmatter is the truth.
+ */
+export declare const SOLUTIONS_DIR = "solutions";
+/** What a file's place in the workspace says about it, before any frontmatter. */
+export interface PathClaim {
+    /** The solution directory's name and the file's stem, as slugs. */
+    solutionSlug: string;
+    outcomeSlug: string;
+}
+/** The solution directory a file sits directly in, if any (SOLDOC-8.1). */
+export declare function solutionDirOf(filePath: string): PathClaim | undefined;
+/** `pitch` for `pitch.md` and for `pitch.requirements.md`. */
+export declare function stemOf(fileName: string): string;
+/** SOLDOC-3: the name, never the content. Undefined for a file the rule doesn't reach. */
+export declare function requirementsDocByName(filePath: string): boolean | undefined;
+export interface SolutionForSync {
+    solutionId: string;
+    title: string;
+    /**
+     * The solution's directory name, which no other solution in the project
+     * has (SOLDOC-9). A backend from before it was sent leaves it out, and the
+     * title's slug stands in.
+     */
+    directory?: string;
+    outcomes: string[];
+}
+/** The directory a solution's documents live in, by name. */
+export declare function directoryOf(solution: SolutionForSync): string;
+export interface Belonging {
+    solutionId: string;
+    outcome: string;
+}
+export type Resolved = {
+    belonging: Belonging;
+    warning?: string;
+} | {
+    belonging: undefined;
+    warning?: string;
+};
+/**
+ * What a pushed file belongs to (SOLDOC-4, SOLDOC-5): the frontmatter's
+ * belonging when it has one, else what its path claims, resolved against
+ * the project's solutions. A frontmatter that disagrees with the path is
+ * kept and reported; a path that resolves to nothing refuses the push.
+ */
+export declare function resolveBelonging(filePath: string, frontmatter: {
+    solution?: string;
+    outcome?: string;
+}, claim: PathClaim | undefined, solutions: SolutionForSync[] | undefined): Resolved;
+/**
+ * SOLDOC-6, SOLDOC-9: where a pulled document that belongs to a solution
+ * lands when it has no file yet: in the solution's own directory, named for
+ * its outcome, with the `.requirements.md` name when it is a requirements
+ * document.
+ */
+export declare function solutionDocumentPath(requirementsDir: string, solutionDirectory: string, outcome: string, isRequirementsDoc: boolean): string;
+//# sourceMappingURL=solution-documents.d.ts.map

package/dist/sync/solution-documents.js

@@ -0,0 +1,97 @@
+/**
+ * Where a solution's documents live, the sync's half (SOLDOC; the decision
+ * is in docs/working/four-areas-prototype.md, "Where a solution's documents
+ * live"). A document that belongs to a solution and is not a requirements
+ * document lives in a solution directory, `.requirements/solutions/<solution>/`,
+ * named for its outcome; the `.requirements.md` name is what makes a file a
+ * requirements document, wherever it sits. A new file declares its belonging
+ * by its path; once the frontmatter carries it, the frontmatter is the truth.
+ */
+import * as path from "node:path";
+import { sanitizeFileName } from "./local-files.js";
+export const SOLUTIONS_DIR = "solutions";
+/** The solution directory a file sits directly in, if any (SOLDOC-8.1). */
+export function solutionDirOf(filePath) {
+    const parts = filePath.split(/[\\/]/);
+    const fileName = parts.at(-1);
+    const solutionSlug = parts.at(-2);
+    if (!fileName ||
+        !solutionSlug ||
+        parts.at(-3) !== SOLUTIONS_DIR ||
+        parts.at(-4) !== ".requirements" ||
+        !fileName.endsWith(".md")) {
+        return undefined;
+    }
+    return { solutionSlug, outcomeSlug: stemOf(fileName) };
+}
+/** `pitch` for `pitch.md` and for `pitch.requirements.md`. */
+export function stemOf(fileName) {
+    return fileName.replace(/\.requirements\.md$/, "").replace(/\.md$/, "");
+}
+/** SOLDOC-3: the name, never the content. Undefined for a file the rule doesn't reach. */
+export function requirementsDocByName(filePath) {
+    if (!solutionDirOf(filePath))
+        return undefined;
+    return filePath.endsWith(".requirements.md");
+}
+/** The directory a solution's documents live in, by name. */
+export function directoryOf(solution) {
+    return solution.directory ?? sanitizeFileName(solution.title);
+}
+/**
+ * What a pushed file belongs to (SOLDOC-4, SOLDOC-5): the frontmatter's
+ * belonging when it has one, else what its path claims, resolved against
+ * the project's solutions. A frontmatter that disagrees with the path is
+ * kept and reported; a path that resolves to nothing refuses the push.
+ */
+export function resolveBelonging(filePath, frontmatter, claim, solutions) {
+    const declared = frontmatter.solution && frontmatter.outcome
+        ? { solutionId: frontmatter.solution, outcome: frontmatter.outcome }
+        : undefined;
+    if (!claim)
+        return { belonging: declared };
+    const name = path.basename(filePath);
+    if (declared) {
+        // SOLDOC-5: the frontmatter wins; the path is layout. Say when they part.
+        const owner = solutions?.find((s) => s.solutionId === declared.solutionId);
+        if (owner && directoryOf(owner) !== claim.solutionSlug) {
+            return {
+                belonging: declared,
+                warning: `${name}: its path names a different solution than its frontmatter ("${owner.title}"); the frontmatter's belonging is kept.`,
+            };
+        }
+        if (sanitizeFileName(declared.outcome) !== claim.outcomeSlug) {
+            return {
+                belonging: declared,
+                warning: `${name}: its filename names a different outcome than its frontmatter ("${declared.outcome}"); the frontmatter's belonging is kept.`,
+            };
+        }
+        return { belonging: declared };
+    }
+    // SOLDOC-4, SOLDOC-9: a new file's path is its declaration, read against
+    // each solution's own directory name.
+    const matches = (solutions ?? []).filter((s) => directoryOf(s) === claim.solutionSlug);
+    if (matches.length === 0) {
+        throw new Error(`${name}: its directory "${claim.solutionSlug}" matches no solution in the project, so it can't be placed. Name the directory as the solution's is named: its title as a slug, with its numeric suffix when an older solution has the same title.`);
+    }
+    if (matches.length > 1) {
+        throw new Error(`${name}: its directory "${claim.solutionSlug}" matches more than one solution (${matches.map((s) => `"${s.title}"`).join(", ")}), so it can't be placed.`);
+    }
+    const [solution] = matches;
+    const outcome = solution.outcomes.find((o) => sanitizeFileName(o) === claim.outcomeSlug);
+    if (!outcome) {
+        throw new Error(`${name}: "${claim.outcomeSlug}" matches no outcome of "${solution.title}". Its plan produces: ${solution.outcomes.map((o) => `${o} (${sanitizeFileName(o)}.md)`).join(", ")}.`);
+    }
+    return { belonging: { solutionId: solution.solutionId, outcome } };
+}
+/**
+ * SOLDOC-6, SOLDOC-9: where a pulled document that belongs to a solution
+ * lands when it has no file yet: in the solution's own directory, named for
+ * its outcome, with the `.requirements.md` name when it is a requirements
+ * document.
+ */
+export function solutionDocumentPath(requirementsDir, solutionDirectory, outcome, isRequirementsDoc) {
+    const suffix = isRequirementsDoc ? ".requirements.md" : ".md";
+    return path.join(requirementsDir, SOLUTIONS_DIR, solutionDirectory || "solution", `${sanitizeFileName(outcome) || "outcome"}${suffix}`);
+}
+//# sourceMappingURL=solution-documents.js.map

package/dist/sync/types.d.ts

@@ -29,12 +29,15 @@ export interface LocalDocument {
     defaultPrefix?: string;
     /** document.attachments from frontmatter (ATTACH-10). */
     attachments?: Attachment[];
+    /** SOLDOC-5: the belonging the frontmatter declares. */
+    solution?: string;
+    outcome?: string;
     /** Frontmatter-stripped markdown body (the comparison unit, SYNC-ARCH-1). */
     body?: string;
     parseError?: string;
 }
 /**
- * One published document as it exists in the cloud, from exportProjectForCli.
+ * One published document as it exists in the cloud, from the project export.
  */
 export interface CloudDocument {
     documentId: string;
@@ -46,6 +49,16 @@ export interface CloudDocument {
     body: string;
     version: number;
     updatedAt: number;
+    /** SOLDOC-6: which solution and outcome it belongs to, with the solution's title and directory name. */
+    solution?: {
+        solutionId: string;
+        outcome: string;
+        title: string | null;
+        /** SOLDOC-9: the solution's directory name; absent from an older backend. */
+        directory?: string | null;
+    };
+    /** SOLDOC-2/3: absent means a requirements document. */
+    isRequirementsDoc?: boolean;
 }
 export interface LocalSnapshot {
     documents: LocalDocument[];
@@ -54,6 +67,11 @@ export interface CloudSnapshot {
     projectName: string;
     projectSlug: string;
     documents: CloudDocument[];
+    /**
+     * SOLACCESS-2.2: whether the project's team has solutions, as the export
+     * read it; absent from an older backend, which reads as no.
+     */
+    solutions?: boolean;
 }
 /**
  * A single point of difference within a paired document, for verbose

package/dist/utils/command-error.d.ts

@@ -0,0 +1,19 @@
+/**
+ * What a failed command tells Sam (ERR-6).
+ *
+ * Production Convex replaces the message of every server error with
+ * "[Request ID: …] Server Error" and keeps only a ConvexError's `data`, which
+ * is where the backend puts the sentence written for users. So a refusal is
+ * read from its data; a server failure that carries none becomes a fixed
+ * sentence with its request ID; anything else is an error raised on Sam's
+ * machine, whose own message is already meant to be read.
+ */
+/**
+ * The user-facing message a ConvexError's data carries, if any: the data is
+ * either a plain string or an object with a `message`. Mirrors
+ * `packages/web/lib/convex-error.ts`.
+ */
+export declare function userFacingMessage(data: unknown): string | undefined;
+/** The text to print for an error that ended a command. */
+export declare function commandErrorMessage(error: unknown): string;
+//# sourceMappingURL=command-error.d.ts.map

package/dist/utils/command-error.js

@@ -0,0 +1,44 @@
+/**
+ * What a failed command tells Sam (ERR-6).
+ *
+ * Production Convex replaces the message of every server error with
+ * "[Request ID: …] Server Error" and keeps only a ConvexError's `data`, which
+ * is where the backend puts the sentence written for users. So a refusal is
+ * read from its data; a server failure that carries none becomes a fixed
+ * sentence with its request ID; anything else is an error raised on Sam's
+ * machine, whose own message is already meant to be read.
+ */
+/**
+ * The user-facing message a ConvexError's data carries, if any: the data is
+ * either a plain string or an object with a `message`. Mirrors
+ * `packages/web/lib/convex-error.ts`.
+ */
+export function userFacingMessage(data) {
+    if (typeof data === "string" && data.trim())
+        return data;
+    if (data && typeof data === "object" && "message" in data) {
+        const { message } = data;
+        if (typeof message === "string" && message.trim())
+            return message;
+    }
+    return undefined;
+}
+const SERVER_ERROR = /\bServer Error\b/;
+const REQUEST_ID = /Request ID: ([\w-]+)/;
+/** The text to print for an error that ended a command. */
+export function commandErrorMessage(error) {
+    if (error && typeof error === "object" && "data" in error) {
+        const message = userFacingMessage(error.data);
+        if (message)
+            return message;
+    }
+    const raw = error instanceof Error ? error.message : String(error);
+    if (SERVER_ERROR.test(raw)) {
+        const requestId = REQUEST_ID.exec(raw)?.[1];
+        return requestId
+            ? `Something went wrong in dotrequirements' cloud (request ID ${requestId}). Try again, and if it keeps happening, email support@dotrequirements.io with the request ID.`
+            : "Something went wrong in dotrequirements' cloud. Try again, and if it keeps happening, email support@dotrequirements.io.";
+    }
+    return raw;
+}
+//# sourceMappingURL=command-error.js.map

package/dist/utils/oauth-flow.js

@@ -6,7 +6,7 @@
  */
 import { randomBytes } from "node:crypto";
 import { ConvexHttpClient } from "convex/browser";
-import { getConvexUrl } from "../config.js";
+import { convexUrl } from "../cloud.js";
 import { api } from "../convex.js";
 import { openBrowserWithFallback } from "./browser-launch.js";
 import { startCallbackServer } from "./oauth-callback-server.js";
@@ -58,7 +58,7 @@ export async function executeOAuthFlow() {
     }
     console.log("Authentication successful, exchanging code for tokens...");
     // Exchange authorization code for tokens via Convex action (server-side WorkOS call)
-    const client = new ConvexHttpClient(getConvexUrl());
+    const client = new ConvexHttpClient(convexUrl());
     const result = await client.action(api.lib.authActions.exchangeAuthorizationCode, {
         code,
         codeVerifier,

package/dist/utils/project-selector.js

@@ -43,9 +43,9 @@ export async function selectTeam(client) {
  */
 export async function selectProject(client, teamId) {
     console.log("\nFetching projects...\n");
-    const projectsWithSecrets = (await client.query(api.projectSecrets.queries.listOwnSecretsForTeam, 
+    const projectsWithSecrets = (await client.query(api.projectSecrets.queries.listOwnForTeam, 
     // biome-ignore lint/suspicious/noExplicitAny: CLI workspace doesn't import convex's branded Id<"teams"> type; the runtime value is a plain string the convex server validates.
-    { target: { type: "team", id: teamId } }));
+    { teamId: teamId }));
     if (projectsWithSecrets.length === 0) {
         console.log("No projects found in this team.");
         console.log('Use "dotrequirements init" to create a new project.\n');
@@ -79,9 +79,9 @@ export async function selectProject(client, teamId) {
  *                     Free tier always gets 30 days regardless of this parameter.
  */
 export async function getOrCreateProjectSecret(client, projectId, expiryDays) {
-    const result = (await client.mutation(api.projectSecrets.mutations.ensureOwnSecret, {
+    const result = (await client.mutation(api.projectSecrets.mutations.ensureOwn, {
         // biome-ignore lint/suspicious/noExplicitAny: CLI workspace doesn't import convex's branded Id<"projects"> type; the runtime value is a plain string the convex server validates.
-        target: { type: "project", id: projectId },
+        projectId: projectId,
         expiryDays,
     }));
     return result;

package/dist/version-messages.d.ts

@@ -0,0 +1,28 @@
+/**
+ * What the cloud has to say to this CLI version (CLI-MSG-1, CLI-MSG-3).
+ *
+ * Once enabled, the first cloud use in a run asks the cloud for this
+ * version's messages, alongside the command's own work. At the end the
+ * command takes them: text commands print them after their output, JSON
+ * commands carry them in their JSON. Asking never changes the command: a
+ * failed, unreadable or slow answer means no messages.
+ */
+/** How long a finished command waits for the cloud's answer (CLI-MSG-3.2). */
+export declare const MESSAGE_WAIT_MS = 1000;
+/** Ask the cloud for this version's messages on the run's first cloud use. */
+export declare function enableVersionMessages(): void;
+/**
+ * The messages for this version, waiting at most `waitMs` for the cloud's
+ * answer; empty when the run never reached the cloud or they were already
+ * shown. Asking twice waits once.
+ */
+export declare function versionMessages(waitMs?: number): Promise<string[]>;
+/**
+ * Record that this run's messages reached the user, once they are actually
+ * printed, so `wrapCommand` doesn't print them again after a JSON command
+ * carried them — and does print them if that command failed first.
+ */
+export declare function markVersionMessagesShown(): void;
+/** The messages as text, for a command's human-readable output. */
+export declare function formatVersionMessages(messages: string[]): string;
+//# sourceMappingURL=version-messages.d.ts.map

package/dist/version-messages.js

@@ -0,0 +1,87 @@
+/**
+ * What the cloud has to say to this CLI version (CLI-MSG-1, CLI-MSG-3).
+ *
+ * Once enabled, the first cloud use in a run asks the cloud for this
+ * version's messages, alongside the command's own work. At the end the
+ * command takes them: text commands print them after their output, JSON
+ * commands carry them in their JSON. Asking never changes the command: a
+ * failed, unreadable or slow answer means no messages.
+ */
+import { convexUrl, whenCloudFirstUsed } from "./cloud.js";
+import { getOwnPackage } from "./utils/own-package.js";
+/** How long a finished command waits for the cloud's answer (CLI-MSG-3.2). */
+export const MESSAGE_WAIT_MS = 1_000;
+let pending = null;
+let abort = null;
+let shown = false;
+async function askCloud(signal) {
+    try {
+        const response = await fetch(`${convexUrl()}/api/query`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                path: "cliMessages/queries:forVersion",
+                args: { version: getOwnPackage().version },
+                format: "json",
+            }),
+            signal,
+        });
+        if (!response.ok)
+            return [];
+        const body = (await response.json());
+        const messages = body.status === "success" ? body.value?.messages : null;
+        return Array.isArray(messages)
+            ? messages.filter((m) => typeof m === "string" && !!m)
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Ask the cloud for this version's messages on the run's first cloud use. */
+export function enableVersionMessages() {
+    whenCloudFirstUsed(() => {
+        if (pending)
+            return;
+        const controller = new AbortController();
+        abort = controller;
+        // Asked just after the command's own first request goes out, so the
+        // command's work is never queued behind the question.
+        pending = new Promise((resolve) => {
+            queueMicrotask(() => resolve(askCloud(controller.signal)));
+        });
+    });
+}
+/**
+ * The messages for this version, waiting at most `waitMs` for the cloud's
+ * answer; empty when the run never reached the cloud or they were already
+ * shown. Asking twice waits once.
+ */
+export async function versionMessages(waitMs = MESSAGE_WAIT_MS) {
+    if (shown || !pending)
+        return [];
+    let timer;
+    const late = new Promise((resolve) => {
+        timer = setTimeout(() => resolve([]), waitMs);
+    });
+    const messages = await Promise.race([pending, late]);
+    clearTimeout(timer);
+    // Whatever came back is the answer: a slow one must neither keep the
+    // process alive after the command nor be waited for a second time.
+    abort?.abort();
+    pending = Promise.resolve(messages);
+    return messages;
+}
+/**
+ * Record that this run's messages reached the user, once they are actually
+ * printed, so `wrapCommand` doesn't print them again after a JSON command
+ * carried them — and does print them if that command failed first.
+ */
+export function markVersionMessagesShown() {
+    shown = true;
+}
+/** The messages as text, for a command's human-readable output. */
+export function formatVersionMessages(messages) {
+    return messages.map((message) => `\n${message}`).join("\n");
+}
+//# sourceMappingURL=version-messages.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popoverai/dotrequirements",
-  "version": "0.32.1",
+  "version": "0.34.0",
   "description": "Requirements as testable, human-readable data — CLI and test harness for spec-driven development with AI coding agents",
   "type": "module",
   "bin": {
@@ -13,7 +13,8 @@
     "./schema": "./dist/schema/index.js",
     "./schema/browser": "./dist/schema/browser.js",
     "./style-guide": "./dist/requirements/style-guide.js",
-    "./greenfield": "./dist/requirements/greenfield.js"
+    "./greenfield": "./dist/requirements/greenfield.js",
+    "./rehearsal": "./dist/rehearsal/index.js"
   },
   "publishConfig": {
     "access": "public"

package/dist/config.d.ts

@@ -1,5 +0,0 @@
-/**
- * Get the Convex deployment URL
- */
-export declare function getConvexUrl(): string;
-//# sourceMappingURL=config.d.ts.map

package/dist/config.js

@@ -1,12 +0,0 @@
-/**
- * Production Convex deployment URL
- * All users connect to the same backend
- */
-const CONVEX_URL = "https://data.dotrequirements.io";
-/**
- * Get the Convex deployment URL
- */
-export function getConvexUrl() {
-    return CONVEX_URL;
-}
-//# sourceMappingURL=config.js.map