@popoverai/dotrequirements 0.38.4 → 0.39.1

package/dist/commands/solution/author.js

@@ -4,6 +4,7 @@ import { api } from "../../convex.js";
 import { currentBranch, headCommit, repositoryRoot } from "./branch.js";
 import { solutionClient } from "./client.js";
 import { readImage, uploadImage } from "./image.js";
+import { ownChangesOf } from "./own-changes.js";
 import { screenshotPreview } from "./preview-screenshot.js";
 import { checkPullRequest } from "./pull-request.js";
 import { pushBeforeRecord, refuseUncommitted } from "./pushing.js";
@@ -76,6 +77,12 @@ export async function authorCommand(references, options) {
     // SOLDOC-12.2.0: a file from the checkout's own branch keeps the commit
     // it was submitted at, so the page can tell when it changes after.
     const commit = checkout ? headCommit(cwd) : null;
+    // CHECKPOINT-12.4 to 12.6: what the pull request would merge, taken after
+    // the push, so the checkpoint can tell a branch brought up to date from
+    // changed code. Without one, as when the fetch fails, the work is
+    // recorded all the same and reads as changed.
+    const merging = [...pullRequests.values()].find((made) => made.base);
+    const ownChanges = checkout && merging?.base ? ownChangesOf(cwd, merging.base) : null;
     /** A reference as it is submitted: where the thing is, as the backend keeps it. */
     const submissionOf = async (thing) => {
         const recording = videos.get(thing);
@@ -99,8 +106,12 @@ export async function authorCommand(references, options) {
             return { kind: "image", storageId, name: image.name };
         }
         const pullRequest = pullRequests.get(thing);
-        if (pullRequest)
-            return { kind: "pull request", ...pullRequest };
+        if (pullRequest) {
+            // The branch it merges into is the CLI's, for `ownChanges`; the
+            // backend keeps the pull request by its number and address.
+            const { base: _base, ...kept } = pullRequest;
+            return { kind: "pull request", ...kept };
+        }
         if (thing.kind === "preview") {
             // SIGHT-12.0, 12.2: a screenshot of the page it opens on, kept as an
             // image is; without one, it is submitted all the same.
@@ -141,6 +152,7 @@ export async function authorCommand(references, options) {
         comment,
         ...(summary ? { summary } : {}),
         ...(files.length ? { files } : {}),
+        ...(ownChanges ? { ownChanges } : {}),
     };
     const result = await client.mutation(api.solutions.mutations.complete, args);
     const saved = result?.saved ?? [];

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

@@ -12,7 +12,8 @@
  * images and demo scripts `next` saves in the checkout (SIGHT-9.3, 13.1).
  */
 export type Brief = {
-    kind: "step" | "review";
+    /** `request`: what the solution's agent asked it, which it answers (CONVO-11). */
+    kind: "step" | "review" | "request";
     /** The outcome the agent took; `label` is its name too. */
     step: {
         label: string;

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

@@ -0,0 +1,12 @@
+import { type WhereOptions } from "./run-file.js";
+/**
+ * `dotreq solution change --comment "<what changed and why>"`: a made
+ * outcome's drafter, asked by the solution's agent to change it, records
+ * the change in place (VERB-8). Its commits are pushed first, as before any
+ * record (VERB-8.1, SOLBRANCH-3); the outcome stays made, and its history
+ * says what changed and why, at the solution's agent's request.
+ */
+export declare function changeCommand(options: WhereOptions & {
+    comment?: string;
+}): Promise<void>;
+//# sourceMappingURL=change.d.ts.map

package/dist/commands/solution/change.js

@@ -0,0 +1,29 @@
+import { api } from "../../convex.js";
+import { solutionClient } from "./client.js";
+import { pushBeforeRecord } from "./pushing.js";
+import { requireWhere } from "./run-file.js";
+/**
+ * `dotreq solution change --comment "<what changed and why>"`: a made
+ * outcome's drafter, asked by the solution's agent to change it, records
+ * the change in place (VERB-8). Its commits are pushed first, as before any
+ * record (VERB-8.1, SOLBRANCH-3); the outcome stays made, and its history
+ * says what changed and why, at the solution's agent's request.
+ */
+export async function changeCommand(options) {
+    const comment = options.comment?.trim();
+    // VERB-8.3: what it says is all the history shows of the change.
+    if (!comment) {
+        throw new Error("Say what changed and why with --comment: what you say is what the outcome's history shows of the change.");
+    }
+    const where = requireWhere(options);
+    const client = solutionClient();
+    await pushBeforeRecord(client, where);
+    const { done } = await client.mutation(api.solutions.mutations.changeInPlace, {
+        solutionId: where.solutionId,
+        agent: where.agent,
+        ...(where.outcome ? { outcome: where.outcome } : {}),
+        comment,
+    });
+    console.log(done);
+}
+//# sourceMappingURL=change.js.map

package/dist/commands/solution/index.js

@@ -2,6 +2,7 @@ import { Option } from "commander";
 import { approvalCompleteCommand } from "./approval.js";
 import { askCommand } from "./ask.js";
 import { authorCommand } from "./author.js";
+import { changeCommand } from "./change.js";
 import { checkoutCommand, pushCommand } from "./checkout.js";
 import { REQUEST_CONTRACT } from "./contract.js";
 import { createCommand } from "./create.js";
@@ -219,7 +220,7 @@ export function registerSolution(program) {
     whereOptions(solution
         .command("author <reference...>", HIDDEN)
         .description("Record what you made, and what changed and why"))
-        .option("--comment <text>", "What changed and why: the next reader sees it first (required)")
+        .option("--comment <text>", "What changed and why: the next reader sees it first, so open on a sentence that stands on its own and says what changed (required)")
         .option("--executive-summary <text>", "For the owner, when your work moves on before anyone reviews it (required there)")
         .option("--summary <text>", "Short for --executive-summary")
         .option("--title <text>", "A reference's name on the outcome's tab, for the owner: one per reference, in the order the references are given, or none", (value, previous = []) => [...previous, value])
@@ -269,6 +270,11 @@ export function registerSolution(program) {
     whereOptions(solution
         .command("things <name>", HIDDEN)
         .description("What an outcome or an input holds now, or the outcomes a checkpoint presents: one reference a line")).action(wrap(thingsCommand));
+    whereOptions(solution
+        .command("change", HIDDEN)
+        .description("Record a change you made in place to a made outcome, as the solution's agent asked: what changed and why. The outcome stays made"))
+        .option("--comment <text>", "What changed and why: what the outcome's history shows of the change (required)")
+        .action(wrap(changeCommand));
     whereOptions(solution
         .command("stall <reason>", HIDDEN)
         .description("Your work cannot go on, and no decision would fix that: what has to change before it can be started again"))

package/dist/commands/solution/own-changes.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The pull request's own changes, fingerprinted from the checkout: what it
+ * would merge into `base`, as `git patch-id` sees it (CHECKPOINT-12.4 to
+ * 12.6). Merging a newer `base` in, or rebasing onto it, leaves the
+ * fingerprint as it was; resolving a conflict, a whitespace change or a new
+ * commit of the branch's own gives a new one.
+ *
+ * `--verbatim` keeps whitespace, and `-U0` drops the context lines and
+ * leaves line numbers only in the hunk headers, which `patch-id` ignores, so
+ * what moved under the change doesn't count as changing it. The cost, an
+ * accepted limit (12.4.0): a fix that only moves the branch's own lines
+ * elsewhere in the same file keeps the fingerprint too.
+ *
+ * Null when any step fails, the fetch included: the work is then recorded
+ * without one, and the checkpoint counts the pull request as changed
+ * (12.6). Never throws.
+ */
+export declare function ownChangesOf(cwd: string, base: string): {
+    commit: string;
+    patchId: string;
+} | null;
+//# sourceMappingURL=own-changes.d.ts.map

package/dist/commands/solution/own-changes.js

@@ -0,0 +1,78 @@
+import { spawnSync } from "node:child_process";
+/**
+ * The pull request's own changes, fingerprinted from the checkout: what it
+ * would merge into `base`, as `git patch-id` sees it (CHECKPOINT-12.4 to
+ * 12.6). Merging a newer `base` in, or rebasing onto it, leaves the
+ * fingerprint as it was; resolving a conflict, a whitespace change or a new
+ * commit of the branch's own gives a new one.
+ *
+ * `--verbatim` keeps whitespace, and `-U0` drops the context lines and
+ * leaves line numbers only in the hunk headers, which `patch-id` ignores, so
+ * what moved under the change doesn't count as changing it. The cost, an
+ * accepted limit (12.4.0): a fix that only moves the branch's own lines
+ * elsewhere in the same file keeps the fingerprint too.
+ *
+ * Null when any step fails, the fetch included: the work is then recorded
+ * without one, and the checkpoint counts the pull request as changed
+ * (12.6). Never throws.
+ */
+export function ownChangesOf(cwd, base) {
+    try {
+        // The base as the repository has it now: an older one would put its
+        // newer commits, merged into the branch, among the branch's own.
+        const fetched = run(cwd, [
+            "fetch",
+            "--quiet",
+            "origin",
+            `+refs/heads/${base}:refs/remotes/origin/${base}`,
+        ]);
+        if (!fetched)
+            return null;
+        const commit = text(run(cwd, ["rev-parse", "--verify", "--quiet", "HEAD"]));
+        if (!commit)
+            return null;
+        const mergeBase = text(run(cwd, ["merge-base", "HEAD", `refs/remotes/origin/${base}`]));
+        if (!mergeBase)
+            return null;
+        const diff = run(cwd, [
+            "diff",
+            "--no-ext-diff",
+            "--no-textconv",
+            "--no-color",
+            "--binary",
+            "-U0",
+            mergeBase,
+            commit,
+        ]);
+        if (!diff)
+            return null;
+        // `patch-id` prints nothing for an empty diff.
+        if (diff.length === 0)
+            return { commit, patchId: "empty" };
+        const id = run(cwd, ["patch-id", "--verbatim"], diff);
+        if (!id)
+            return null;
+        // A diff it gives no id for, as one only changing a file's mode, can't
+        // be told from another: no fingerprint.
+        const patchId = text(id)?.split(/\s+/)[0];
+        return patchId ? { commit, patchId } : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Git's stdout, as bytes, or null when it failed. */
+function run(cwd, args, input) {
+    const ran = spawnSync("git", args, {
+        cwd,
+        input,
+        maxBuffer: 1024 * 1024 * 1024,
+        // A fetch that wants a password fails rather than waiting for one.
+        env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+    });
+    return ran.status === 0 && !ran.error ? ran.stdout : null;
+}
+function text(out) {
+    return out?.toString("utf8").trim() || null;
+}
+//# sourceMappingURL=own-changes.js.map

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

@@ -1,8 +1,12 @@
 import { type Where, type WhereOptions } from "./run-file.js";
-/** The solution's pull request: its number and where it opens. */
+/**
+ * The solution's pull request: its number and where it opens, and, when
+ * checked by its number, the branch it merges into (CHECKPOINT-12.4).
+ */
 export type PullRequest = {
     url: string;
     number: number;
+    base?: string;
 };
 /** The command that opens the solution's pull request and prints its reference. */
 export declare const OPEN_IT = "dotreq solution pr open";

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

@@ -91,9 +91,13 @@ export async function checkPullRequest(where, number) {
     return pullRequest;
 }
 function pullRequestIn(said) {
-    return said.url && typeof said.number === "number"
-        ? { url: said.url, number: said.number }
-        : null;
+    if (!said.url || typeof said.number !== "number")
+        return null;
+    return {
+        url: said.url,
+        number: said.number,
+        ...(typeof said.base === "string" && said.base ? { base: said.base } : {}),
+    };
 }
 /**
  * Ask the app's pull-request route, on the project's credentials: with the

package/dist/convex.d.ts

@@ -101,6 +101,7 @@ export declare const api: {
             ask: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
             completeApproval: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
             stall: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
+            changeInPlace: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
             answer: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
             approveCheckpoint: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
             removeRehearsal: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;

package/dist/convex.js

@@ -115,6 +115,8 @@ export const api = {
             // DECIDE-4: the action on the option the owner chose, taken once.
             completeApproval: mutation("solutions/mutations:completeApproval"),
             stall: mutation("solutions/mutations:stall"),
+            // VERB-8: a made outcome's drafter's change in place.
+            changeInPlace: mutation("solutions/mutations:changeInPlace"),
             answer: mutation("solutions/mutations:answer"),
             // A rehearsal's scripted approval of a checkpoint (CHECKPOINT-1.1).
             approveCheckpoint: mutation("solutions/mutations:approveCheckpoint"),

package/package.json

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