@floh-solutions/pharos-cli 0.24.0 → 0.26.0

package/dist/commands/issue.js

@@ -1,108 +1,10 @@
 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";
+import { FALLBACK_WORK_ITEM_TYPE, resolveWorkItemType } from "../adopt-type.js";
 import { approve } from "../session.js";
-/**
- * `pharos issue` — the cross-platform **edge**, and only the edge.
- *
- * ## Why there are three verbs here and not thirty
- *
- * **Do not rebuild `gh`** (plan §8). The agent already has it, it is better than
- * anything here would be, and a second GitHub CLI is the "second implementation
- * that drifts" failure `AGENTS.md` names three separate times. There is no
- * `pharos issue list`, no `issue view`, no `issue close`: reading and writing an
- * issue is `gh`'s job, reading and writing a work item is the other twenty-seven
- * verbs' job. What neither can do is join them, and that is all this is.
- *
- * | verb | what only this can do |
- * |---|---|
- * | `adopt` | create the work item AND write both ends of the link, in that order, idempotently |
- * | `link`  | join an existing pair, or finish a join that half-happened |
- * | `say`   | one message, two audiences — the full explanation to GitHub, a summary and the comment's URL to Azure DevOps |
- * | `trail` | the whole trail from **either** end, with the evidence for each half |
- *
- * `say` is the one that could be mistaken for `gh issue comment` plus `pharos
- * comment add`, and it is not: those two write the same words twice to two
- * audiences with different access, and neither of them knows the other
- * happened. The asymmetry is the feature (§8) — see {@link runSay}.
- *
- * ## The link is three layers, and this writes two of them
- *
- * Plan §6, in order of durability:
- *
- * 1. **Durable and human-visible.** On Azure DevOps a `Hyperlink` relation to
- *    the issue URL. Measured, not chosen: `_apis/githubconnections` answers 401
- *    on Pharos's PAT scopes while a control WIQL call answers 200 with the same
- *    token, so the connection id a native `vstfs:///GitHub/Issue/…` artifact
- *    link needs cannot be read at all (§2). On GitHub, one Pharos comment
- *    carrying `AB#<id>` — free official linking wherever the Azure Boards app
- *    happens to be installed, harmless text where it is not.
- * 2. **Machine-readable.** The `<!-- pharos:v1 … -->` trailer inside that same
- *    comment. **In a comment, never the issue body**: editing a reporter's body
- *    collides with them, is rude on a public repo, and needs write access we may
- *    not have on a community issue.
- * 3. **Fast.** A local join table, rebuilt from 1 and 2. This CLI has none — it
- *    reads the durable layers every time, which is why it needs no state on disk
- *    and cannot be stale.
- *
- * Both layers are composed by `gh-core`'s {@link composeLinkComment} and read
- * back by its {@link linksFromComments} / {@link linksFromHyperlinks}. Nothing
- * here parses or formats a marker. The grammar is a **shared contract** with a
- * Swift port that tests against the same fixture file, and a second parser here
- * would be the drift that fixture exists to prevent.
- *
- * ## The write order, and the one failure it leaves behind
- *
- * Azure DevOps first, GitHub second — in `adopt` because the work item id does
- * not exist until the create lands, and in `link` for the same order so there is
- * **one** recovery path rather than two. So the failure this can leave is always
- * the same shape: the ADO end written, the GitHub end not. `pharos issue link
- * <repo#n> <id>` completes exactly that, and `adopt` reports the created id and
- * that command when the comment fails rather than only reporting the error — a
- * work item nobody can name is worse than a failed call.
- *
- * ## What "already linked" means, and the three places it is asked
- *
- * The GitHub comment is the index, and it is the *first* thing read: an issue
- * carrying a marker is already adopted, `adopt` returns the work item it names,
- * exit 0, nothing written. That is the property an agent that retries depends
- * on.
- *
- * **It is not sufficient on its own, and that cost a real duplicate.** In the
- * half-linked state — the work item created, the comment not — the marker was
- * never posted, so the index is silent about a work item that already exists.
- * A retry there used to create a *second* one: its own id, its own place in a
- * sprint, its own notifications, on a client's board, and nothing in this app
- * removes it. That state is exactly the one a retry follows, because it is the
- * one that just returned an error.
- *
- * So before creating anything, two more questions are asked, cheapest first,
- * and either of them makes `adopt` **refuse** and hand over the same
- * `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.
- * 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]`
- *    and matches the URLs client-side — see `issue-scan.ts` ▸
- *    {@link adoptGuardWiql}, which explains why it is capped and why it is not
- *    the statement `drift` uses. A failed guard query is reported and does not
- *    block the adoption: this is a safety net, and one that refuses to adopt
- *    because it could not run would be worse than the thing it prevents.
- *
- * `pharos issue drift` is still the sweep that finds a half-linked pair nobody
- * retried, and reports it as `one-sided` with the same repair.
- */
-/** The Basic process's name for a reported problem. Overridden with `--type`. */
-const DEFAULT_WORK_ITEM_TYPE = "Issue";
 export async function runIssue(io, session, positionals, options) {
     const verb = positionals[0];
     switch (verb) {
@@ -120,16 +22,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
@@ -157,7 +71,10 @@ async function runAdopt(io, session, positionals, options) {
     // when it finds one; a second work item is the damage this whole verb has to
     // avoid.
     const boardCheck = await refuseIfAlreadyTracked(session, coordinate);
-    const type = options.type ?? DEFAULT_WORK_ITEM_TYPE;
+    // **RESOLVED, NOT NAMED** (#872). `"Issue"` was hardcoded here and is right
+    // on Basic by accident — on Agile it means an impediment. See `adopt-type.ts`.
+    const chosen = await resolveWorkItemType(session, issue, { type: options.type });
+    const type = chosen.type;
     const title = options.title ?? issue.title;
     const url = issueUrl(coordinate);
     const parent = options.parent === undefined ? undefined : await resolveParent(session, options.parent);
@@ -208,10 +125,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);
@@ -1441,7 +1358,7 @@ async function runBackfill(io, session, positionals, options) {
         });
     }
     const parent = options.parent === undefined ? undefined : await resolveParent(session, options.parent);
-    const type = options.type ?? DEFAULT_WORK_ITEM_TYPE;
+    const type = options.type ?? FALLBACK_WORK_ITEM_TYPE;
     const adopted = [];
     const skipped = [];
     const failed = [];
@@ -1886,6 +1803,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 +2154,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 +2183,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.