@popoverai/dotrequirements 0.36.0 → 0.36.1

package/dist/commands/solution/index.js

@@ -102,11 +102,17 @@ Reading it changes nothing.
 `;
 /** What `pr wait` does, on its `--help` (PULL-5, PULL-6). */
 const PR_WAIT_HELP = `
-For a reviewer, when the pull request has to change before you can give a result,
-as while its checks run. Records where it stands now; then end your session
-without a result. You are started again, in this session, when GitHub reports it
-changed and nothing on it is still running, or once it is merged or closed. A new
-submission ends the wait too, and you review that as you would any other.
+For a reviewer, while the pull request's checks run or GitHub works out whether it
+can merge. Records where it stands now; then end your session without a result.
+You are started again, in this session, once GitHub reports it clean, once it is
+merged or closed, or when the wait is up: ten minutes unless you say, up to an
+hour. A conflict, a failed check or a branch behind doesn't change by waiting:
+judge it now. A new submission ends the wait too, and you review that as you
+would any other.
+
+Examples:
+  dotreq solution pr wait
+  dotreq solution pr wait 30m
 `;
 /** What `pr open` does, on its `--help`, where `author --help` sends the agent (PULL-2). */
 const PULL_REQUEST_HELP = `
@@ -256,8 +262,8 @@ export function registerSolution(program) {
         .addHelpText("after", PR_STATUS_HELP)
         .action(wrap(prStatusCommand));
     whereOptions(pr
-        .command("wait")
-        .description("Wait on the pull request with your session ended: you start again when it changes and nothing on it is still running"))
+        .command("wait [duration]")
+        .description("Wait on the pull request with your session ended, for ten minutes unless you say (as 5m or 1h, up to an hour): you start again once it is clean, merged or closed, or when the time is up"))
         .addHelpText("after", PR_WAIT_HELP)
         .action(wrap(prWaitCommand));
     whereOptions(solution

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

@@ -25,10 +25,7 @@ export type PullRequestState = {
     }>;
     head: string;
 };
-/**
- * Where the pull request stood, as a wait records it (PULL-6.4): what a
- * reviewer judges by, so a later read that differs is a change.
- */
+/** Where the pull request stood, in words, as a wait records it beside what the line shows (PULL-5.1.0). */
 export declare function seenOf(state: PullRequestState): string;
 /** Where the pull request stands, as a reviewer reads it (PULL-4). */
 export declare function describeState(state: PullRequestState): string;
@@ -39,14 +36,17 @@ export declare function describeState(state: PullRequestState): string;
 export declare function prStatusCommand(options: WhereOptions & {
     json?: boolean;
 }): Promise<void>;
+/** A wait's length as an agent types it, `90s`, `5m` or `1h`, in milliseconds; refused past an hour or at none (PULL-5.8 to 5.10). */
+export declare function waitFor(duration: string | undefined): number;
 /**
- * `dotreq solution pr wait`: the reviewer waits on the pull request with
- * no session running (PULL-5): it records where the pull request stands,
- * and its session can end without a result. It starts again, in the same
- * session, when the pull request changes and nothing on it is still running
- * (PULL-6).
+ * `dotreq solution pr wait [duration]`: the reviewer waits on the pull
+ * request with no session running (PULL-5), ten minutes unless it says, up
+ * to an hour: it records what it saw, and its session can end without a
+ * result. It starts again, in the same session, once the pull request is
+ * `clean`, once it is merged or closed, or when the wait is up (PULL-6). A
+ * pull request already `clean` needs no wait (5.11).
  */
-export declare function prWaitCommand(options: WhereOptions): Promise<void>;
+export declare function prWaitCommand(duration: string | undefined, options: WhereOptions): Promise<void>;
 /**
  * `dotreq solution pr open`: the solution's pull request, opened or
  * found (PULL-2). Inside a runner the branch is pushed first, as a submission

package/dist/commands/solution/pull-request.js

@@ -7,10 +7,7 @@ import { requireWhere } from "./run-file.js";
 import { outcomeFor } from "./status.js";
 /** The command that opens the solution's pull request and prints its reference. */
 export const OPEN_IT = "dotreq solution pr open";
-/**
- * Where the pull request stood, as a wait records it (PULL-6.4): what a
- * reviewer judges by, so a later read that differs is a change.
- */
+/** Where the pull request stood, in words, as a wait records it beside what the line shows (PULL-5.1.0). */
 export function seenOf(state) {
     return [
         state.head,
@@ -72,26 +69,63 @@ export async function prStatusCommand(options) {
     const state = await stateFor(requireWhere(options));
     console.log(options.json ? JSON.stringify(state) : describeState(state));
 }
+/** What a reviewer is told when it asks for a wait it can't have (PULL-5.10), in the backend's words. */
+const WAIT_REFUSED = "Nothing is waiting: a wait is up to an hour, ten minutes unless you say, as `dotreq solution pr wait 5m` or `pr wait 1h`.";
+/** A wait's length as an agent types it, `90s`, `5m` or `1h`, in milliseconds; refused past an hour or at none (PULL-5.8 to 5.10). */
+export function waitFor(duration) {
+    if (duration === undefined)
+        return 10 * 60 * 1000;
+    const found = /^(\d+)(s|m|h)$/.exec(duration.trim());
+    const unit = { s: 1000, m: 60 * 1000, h: 60 * 60 * 1000 };
+    const ms = found ? Number(found[1]) * unit[found[2]] : 0;
+    if (!(ms > 0 && ms <= 60 * 60 * 1000))
+        throw new Error(WAIT_REFUSED);
+    return ms;
+}
+/** In words, how long a wait is. */
+function forHowLong(ms) {
+    if (ms === 3_600_000)
+        return "an hour";
+    if (ms % 60_000 !== 0) {
+        const seconds = Math.round(ms / 1000);
+        return `${seconds} second${seconds === 1 ? "" : "s"}`;
+    }
+    const minutes = ms / 60_000;
+    return `${minutes} minute${minutes === 1 ? "" : "s"}`;
+}
 /**
- * `dotreq solution pr wait`: the reviewer waits on the pull request with
- * no session running (PULL-5): it records where the pull request stands,
- * and its session can end without a result. It starts again, in the same
- * session, when the pull request changes and nothing on it is still running
- * (PULL-6).
+ * `dotreq solution pr wait [duration]`: the reviewer waits on the pull
+ * request with no session running (PULL-5), ten minutes unless it says, up
+ * to an hour: it records what it saw, and its session can end without a
+ * result. It starts again, in the same session, once the pull request is
+ * `clean`, once it is merged or closed, or when the wait is up (PULL-6). A
+ * pull request already `clean` needs no wait (5.11).
  */
-export async function prWaitCommand(options) {
+export async function prWaitCommand(duration, options) {
+    const forMs = waitFor(duration);
     const where = requireWhere(options);
     const state = await stateFor(where);
+    if (state.mergeState === "clean") {
+        throw new Error(`Nothing is waiting: the pull request is already \`clean\`.\n\n${describeState(state)}`);
+    }
     await solutionClient().mutation(api.solutions.waits.waitOnPullRequest, {
         solutionId: where.solutionId,
         agent: where.agent,
         ...(where.outcome ? { outcome: where.outcome } : {}),
         seen: seenOf(state),
+        saw: {
+            number: state.number,
+            url: state.url,
+            conflicting: state.mergeable === "conflicting",
+            failed: state.failed.length,
+            running: state.running.length,
+        },
+        forMs,
     });
     console.log([
         describeState(state),
         "",
-        "Waiting on it. End your session now: you'll be started again, here, when it changes and nothing on it is still running.",
+        `Waiting on it. End your session now: you'll be started again, here, once it is \`clean\`, once it is merged or closed, or in ${forHowLong(forMs)}, whichever comes first.`,
     ].join("\n"));
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popoverai/dotrequirements",
-  "version": "0.36.0",
+  "version": "0.36.1",
   "description": "Requirements as testable, human-readable data — CLI and test harness for spec-driven development with AI coding agents",
   "type": "module",
   "bin": {