@floh-solutions/pharos-cli 0.24.0 → 0.25.0

package/dist/commands/issue.js

@@ -1,5 +1,5 @@
 import { addHyperlink, addParent, setField, setMarkdown, } from "@floh-solutions/ado-core";
-import { GitHubNotFoundError, PullRequestNotAnIssueError, assertIssueCoordinate, composeLinkComment, formatIssueCoordinate, isPharosAuthored, isTwoSided, issueUrl, linksFromComments, linksFromHyperlinks, mergeLinks, normalizeRepo, parseRepo, } from "@floh-solutions/gh-core";
+import { GitHubNotFoundError, PullRequestNotAnIssueError, assertIssueCoordinate, composeLinkComment, formatIssueCoordinate, isPharosAuthored, isTwoSided, issueUrl, linksFromComments, linksFromHyperlinks, mergeLinks, milestoneNumber, normalizeRepo, parseRepo, } from "@floh-solutions/gh-core";
 import { DEFAULT_WRITE_BUDGET } from "../budget.js";
 import { ADOPT_GUARD_LIMIT, READ_CONCURRENCY, WRITES_PER_ADOPTION, adoptGuardWiql, backfillCandidates, claimsOn, driftWiql, finishedStates, inBatches, isFinished, judgeLink, linkedNumbersIn, linksOnWorkItems, looksLikeWiqlRejection, reposOf, tallyDrift, terminalStateFor, } from "../issue-scan.js";
 import { CliError, emit, emitText, failureOf, refusal, usageError, } from "../output.js";
@@ -83,12 +83,13 @@ import { approve } from "../session.js";
  * `pharos issue link` command the failure itself carried:
  *
  * 1. **This machine.** `half-link.ts` records an adoption between the create
- *    and the comment, and removes it when the comment lands. Local, no round
- *    trip, and the only one of the three that can see a work item created
- *    seconds ago — WIQL answers from an index that lags a write by moments,
- *    which is precisely the window a retry arrives in. An entry is *verified*
- *    against Azure DevOps before it is believed, so a work item that was since
- *    deleted cannot wedge a legitimate adoption.
+ *    and the comment, and removes it when the comment lands. Local, so the
+ *    refusal costs no round trip — and it is the **only** guard left when the
+ *    board cannot be asked at all, which is a state this deliberately does not
+ *    treat as fatal. It also knows *which* work item this machine created and
+ *    when, where a scan can only infer it. An entry is *verified* against Azure
+ *    DevOps before it is believed, so a work item that was since deleted cannot
+ *    wedge a legitimate adoption.
  * 2. **The board**, for everything the first cannot see: a retry from another
  *    machine, another checkout, or after the journal was lost. Azure DevOps has
  *    no query over relation URLs, so this narrows on `[System.HyperLinkCount]`
@@ -120,16 +121,28 @@ export async function runIssue(io, session, positionals, options) {
             return runBackfill(io, session, positionals.slice(1), options);
         case "close":
             return runClose(io, session, positionals.slice(1), options);
+        case "edit":
+            return runEdit(io, session, positionals.slice(1), options);
         case undefined:
-            throw usageError("Which issue verb? adopt, link, say, trail, drift or backfill. Reading and writing an "
-                + "issue itself is `gh`.", { verbs: ISSUE_VERBS });
+            throw usageError(`Which issue verb? ${ISSUE_VERBS.join(", ")}. Reading an issue is \`gh\`.`, { verbs: ISSUE_VERBS });
         default:
             throw usageError(`Unknown issue verb "${verb}". This owns the EDGE — ${ISSUE_VERBS.join(", ")} — and `
                 + "nothing else: listing, viewing and commenting on an issue are `gh`'s job. Closing "
-                + "one END is `gh issue close`; closing the PAIR is `pharos issue close`.", { verbs: ISSUE_VERBS });
+                + "one END is `gh issue close`; closing the PAIR is `pharos issue close`. Editing one "
+                + "unguarded is `gh issue edit`; editing it behind a lost-update guard is "
+                + "`pharos issue edit`.", { verbs: ISSUE_VERBS });
     }
 }
-const ISSUE_VERBS = ["adopt", "link", "say", "trail", "drift", "backfill", "close"];
+const ISSUE_VERBS = [
+    "adopt",
+    "link",
+    "say",
+    "trail",
+    "drift",
+    "backfill",
+    "close",
+    "edit",
+];
 // MARK: - adopt
 /**
  * `pharos issue adopt <repo#n>` — the issue becomes a work item, and both ends
@@ -208,10 +221,10 @@ async function runAdopt(io, session, positionals, options) {
  * **The duplicate guard.** Refuses when a work item already tracks this issue
  * without the issue saying so, and otherwise reports what the check cost.
  *
- * Two sources, cheapest first, and the order is the whole design — see this
- * file's header ▸ *What "already linked" means*. Neither subsumes the other:
- * the journal sees a work item created seconds ago that the query index has not
- * indexed yet, and the board sees one this machine has no memory of.
+ * Two sources, cheapest first — see this file's header ▸ *What "already linked"
+ * means*. The board is the stronger one and it is what catches a retry from
+ * another machine; the journal is what is left when the board query cannot run,
+ * and it answers without a round trip.
  */
 async function refuseIfAlreadyTracked(session, coordinate) {
     const key = halfLinkKey(session, coordinate);
@@ -1886,6 +1899,213 @@ function titleOfField(item, name) {
     const value = item.fields?.[name];
     return typeof value === "string" && value !== "" ? value : null;
 }
+// MARK: - edit
+/**
+ * `pharos issue edit <owner/name#45>` — change the issue's own fields, behind
+ * the lost-update guard GitHub does not offer.
+ *
+ * ## This one verb is not an edge verb, and that needs saying out loud
+ *
+ * Everything else under `pharos issue` exists because `gh` cannot join the two
+ * platforms. **`gh issue edit` exists and is good.** So the rule at the top of
+ * this file — do not rebuild `gh` — is met here not by refusing to build the
+ * verb but by building the one thing `gh` does not: a guard.
+ *
+ * `gh issue edit --title "…"` is last-write-wins. It reads nothing, compares
+ * nothing, and if a colleague renamed the issue while you were composing, their
+ * rename is gone and neither of you is told. That is fine for the interactive
+ * human `gh` is written for, and it is not fine for an agent — which reads an
+ * issue, spends a minute thinking, and writes back into a world that moved.
+ *
+ * So: **if you want an unguarded edit, `gh issue edit` is right there and is
+ * better at it.** What this adds is the refusal.
+ *
+ * ## The guard, and what it honestly is
+ *
+ * There is no conditional write. `PATCH /repos/{o}/{r}/issues/{n}` answers
+ * **400** to `If-Match` — measured (#832), re-measured (#798) — so the Azure
+ * DevOps `{"op":"test","path":"/rev"}` guarantee has no GitHub analogue.
+ *
+ * The guard is therefore a **value compare**, in `gh-core`'s
+ * {@link IssueEditApi.fields}: re-read immediately before sending, compare the
+ * text about to be overwritten with the text the caller believes is there,
+ * refuse only if *that* moved. Never `updated_at` and never the ETag — both move
+ * when somebody merely comments, which would refuse a legitimate edit for a
+ * change that touched nothing.
+ *
+ * **The base defaults to the read this command already makes**, so the guard is
+ * on by default and costs nothing extra: `edit` has to read the issue anyway —
+ * to refuse a pull-request number, to report what changed, and to know the
+ * current values it is not overwriting. That default protects a window of one
+ * round trip, which is honest but small, and the output says so as
+ * `guard.window: "in-command"`.
+ *
+ * `--if-title` / `--if-body` / `--if-body-file` widen it to the base the caller
+ * actually saw, and that is where the guard earns its keep: an agent that read
+ * the issue, thought for a minute and came back can hand over what it read.
+ * The output then says `guard.window: "caller"`.
+ *
+ * Either way it is **not atomic** and nothing client-side can make it so. It
+ * narrows the race to one round trip; it does not close it. The refusal says
+ * that rather than leaving somebody to infer a guarantee that is not there.
+ *
+ * ## Why labels and assignees are three calls and not one PATCH
+ *
+ * `PATCH /issues/{n}` carries `labels` and `assignees` as **whole arrays**, so
+ * routing them through it would make every label write a blind overwrite of
+ * every label — the exact failure the guard above exists to prevent, reproduced
+ * on a field where it would be silent. Their own add/remove sub-resources put
+ * them back inside the append argument: adding a label cannot remove somebody
+ * else's.
+ *
+ * Two things those endpoints do quietly, both measured live on #798 and both
+ * handled by `gh-core` rather than here:
+ *
+ * - `POST …/labels` **creates** a repository label that does not exist. A
+ *   typo'd `--add-label` would leave grey litter on a client's repository
+ *   forever. Unknown labels are refused, with the near misses named;
+ *   `--create-label` is how you mean it.
+ * - `POST …/assignees` **silently ignores** a login it will not assign, and
+ *   still answers 201. `ignored` in the output is that difference, and it is the
+ *   difference between telling somebody their teammate is assigned and it being
+ *   true.
+ *
+ * ## Order
+ *
+ * Fields first, then labels, then assignees — because the fields call is the one
+ * that can **refuse**, and a refusal after the labels had already been rewritten
+ * would leave the issue half-edited with no single command to finish it.
+ */
+async function runEdit(io, session, positionals, options) {
+    const ref = await resolveIssue(session, positionals[0], "edit");
+    const coordinate = formatIssueCoordinate({ repo: ref.repo, number: ref.number });
+    const wantsFields = options.title !== undefined || options.message !== undefined || options.milestone !== undefined;
+    const wantsLabels = options.addLabels.length > 0 || options.removeLabels.length > 0;
+    const wantsAssignees = options.addAssignees.length > 0 || options.removeAssignees.length > 0;
+    if (!wantsFields && !wantsLabels && !wantsAssignees) {
+        throw usageError(`Nothing to edit on ${coordinate}. Pass --title, a body (--text/--file/--stdin), `
+            + "--milestone, --add-label/--remove-label or --add-assignee/--remove-assignee.", { verb: "edit" });
+    }
+    const github = await session.github();
+    // Reads the issue AND refuses a pull-request number, which `gh-core` does at
+    // this boundary rather than in each caller. Doing it first means a PR number
+    // never reaches a write.
+    const before = await github.issues.get(ref);
+    const milestone = milestoneArgument(options.milestone);
+    const guarded = wantsFields;
+    const base = guarded
+        ? {
+            // The caller's base where it gave one, this read's where it did not.
+            // Both are real bases; they differ only in how wide a window they cover,
+            // and `guard.window` below is what says which.
+            ...(options.title === undefined ? {} : { title: options.ifTitle ?? before.title }),
+            ...(options.message === undefined ? {} : { body: options.ifBody ?? before.body ?? "" }),
+            ...(milestone === undefined ? {} : { milestone: milestoneNumber(before) }),
+        }
+        : undefined;
+    const plan = {
+        issue: summariseIssue(before, { repo: ref.repo, number: ref.number }),
+        edit: {
+            ...(options.title === undefined ? {} : { title: options.title }),
+            ...(options.message === undefined ? {} : { body: options.message }),
+            ...(milestone === undefined ? {} : { milestone }),
+            ...(options.addLabels.length === 0 ? {} : { addLabels: options.addLabels }),
+            ...(options.removeLabels.length === 0 ? {} : { removeLabels: options.removeLabels }),
+            ...(options.addAssignees.length === 0 ? {} : { addAssignees: options.addAssignees }),
+            ...(options.removeAssignees.length === 0 ? {} : { removeAssignees: options.removeAssignees }),
+        },
+    };
+    const gate = approve(io, session, {
+        what: `edit ${coordinate}`,
+        // GitHub only. Demanding an Azure DevOps PAT for a verb that never touches
+        // Azure DevOps is #839, and it has a test.
+        platform: "github",
+        would: { ...plan, wouldWrite: writeList(wantsFields, wantsLabels, wantsAssignees) },
+    });
+    if (gate !== undefined)
+        return gate;
+    const result = { issue: plan.issue, edit: plan.edit };
+    let latest = before;
+    if (wantsFields) {
+        const edit = await github.edits.fields(ref, {
+            ...(options.title === undefined ? {} : { title: options.title }),
+            ...(options.message === undefined ? {} : { body: options.message }),
+            ...(milestone === undefined ? {} : { milestone }),
+            ...(base === undefined ? {} : { base }),
+        });
+        latest = edit.issue;
+        result["fields"] = {
+            changed: edit.changed,
+            converged: edit.guard.converged,
+            guard: {
+                ...edit.guard,
+                window: usedCallerBase(options) ? "caller" : "in-command",
+                note: "GitHub offers no conditional write on this endpoint — If-Match is refused with a 400 "
+                    + "— so this is a re-read compared on the VALUE. It narrows the race to one round trip "
+                    + "and does not close it.",
+            },
+        };
+    }
+    if (wantsLabels) {
+        const labels = await github.edits.labels(ref, {
+            add: options.addLabels,
+            remove: options.removeLabels,
+            createMissing: options.createLabel,
+        });
+        result["labels"] = {
+            now: labels.labels.map((label) => label.name),
+            added: labels.added,
+            removed: labels.removed,
+            alreadyAbsent: labels.alreadyAbsent,
+            created: labels.created,
+        };
+    }
+    if (wantsAssignees) {
+        const assignees = await github.edits.assignees(ref, {
+            add: options.addAssignees,
+            remove: options.removeAssignees,
+        });
+        result["assignees"] = {
+            now: assignees.assignees,
+            added: assignees.added,
+            removed: assignees.removed,
+            // Named rather than buried: GitHub answered 201 for these and did not
+            // assign them. A caller that only checks the status code reports a lie.
+            ignored: assignees.ignored,
+            notRemoved: assignees.notRemoved,
+        };
+    }
+    result["edited"] = summariseIssue(latest, { repo: ref.repo, number: ref.number });
+    return report(io, session, result);
+}
+/** `--milestone 4`, or `--milestone none` to clear it. */
+function milestoneArgument(given) {
+    if (given === undefined)
+        return undefined;
+    const text = given.trim().toLowerCase();
+    // `none` rather than an empty string, which a shell eats, and rather than `0`,
+    // which is a plausible milestone number somebody could mean literally.
+    if (text === "none" || text === "null")
+        return null;
+    if (!/^\d+$/.test(text)) {
+        throw usageError(`"${given}" is not a milestone. Pass its NUMBER — the one in the milestone's URL — or `
+            + "`none` to clear it. GitHub answers 422 for a number that does not exist.", { given });
+    }
+    return Number(text);
+}
+function usedCallerBase(options) {
+    return options.ifTitle !== undefined || options.ifBody !== undefined;
+}
+function writeList(fields, labels, assignees) {
+    const out = [];
+    if (fields)
+        out.push("fields");
+    if (labels)
+        out.push("labels");
+    if (assignees)
+        out.push("assignees");
+    return out;
+}
 // MARK: - shared
 /**
  * `owner/name#45` → everything needed to call GitHub about it.
@@ -2030,6 +2250,8 @@ function render(result) {
         return renderBackfill(result);
     if (result["pairs"] !== undefined)
         return renderClose(result);
+    if (result["edited"] !== undefined)
+        return renderEdit(result);
     const message = result["message"];
     if (typeof message === "string")
         return message;
@@ -2057,6 +2279,62 @@ function render(result) {
     }
     return `${coordinate} ↔ #${String(workItem?.["id"] ?? "")} — wrote ${written}${unchecked}`;
 }
+/**
+ * What actually changed, and — the two lines nobody must miss — what GitHub
+ * quietly did not do.
+ *
+ * `ignored` and `created` are printed as warnings rather than folded into the
+ * summary, because both are cases where the call **succeeded** and the outcome
+ * is not what was asked for. `--pretty` is the mode where nobody is reading the
+ * JSON that says so, and silence there reads as "all of it worked".
+ */
+function renderEdit(result) {
+    const edited = result["edited"];
+    const coordinate = `${String(edited?.["repo"] ?? "")}#${String(edited?.["number"] ?? "")}`;
+    const lines = [];
+    const fields = result["fields"];
+    const changed = fields?.["changed"] ?? [];
+    const converged = fields?.["converged"] ?? [];
+    if (fields !== undefined) {
+        lines.push(changed.length === 0
+            ? `${coordinate} — no field written (GitHub already held what was asked for)`
+            : `${coordinate} — wrote ${changed.join(" + ")}`);
+        if (converged.length > 0) {
+            lines.push(`  ${converged.join(", ")} already matched — not sent`);
+        }
+        const guard = fields["guard"];
+        if (guard?.["window"] === "in-command") {
+            lines.push("  guarded against this command's own read only — pass --if-title/--if-body to guard "
+                + "against what you actually saw");
+        }
+    }
+    const labels = result["labels"];
+    if (labels !== undefined) {
+        lines.push(`  labels: ${(labels["now"] ?? []).join(", ") || "none"}`);
+        const created = labels["created"] ?? [];
+        if (created.length > 0) {
+            lines.push(`! CREATED on the repository, not just on the issue: ${created.join(", ")}`);
+        }
+        const absent = labels["alreadyAbsent"] ?? [];
+        if (absent.length > 0)
+            lines.push(`  not on the issue anyway: ${absent.join(", ")}`);
+    }
+    const assignees = result["assignees"];
+    if (assignees !== undefined) {
+        const now = assignees["now"] ?? [];
+        lines.push(`  assignees: ${now.join(", ") || "none"}`);
+        const ignored = assignees["ignored"] ?? [];
+        if (ignored.length > 0) {
+            // The measured trap: 201, and these were never assigned.
+            lines.push(`! GitHub accepted the request and did NOT assign: ${ignored.join(", ")} — they need `
+                + "push access to the repository");
+        }
+        const notRemoved = assignees["notRemoved"] ?? [];
+        if (notRemoved.length > 0)
+            lines.push(`! still assigned after removal: ${notRemoved.join(", ")}`);
+    }
+    return lines.join("\n");
+}
 /**
  * Two lines for two audiences, because one line would flatten the only thing
  * about this verb worth seeing at a glance.