@floh-solutions/pharos-cli 0.24.0 → 0.26.0

package/dist/commands/comment-github.js

@@ -0,0 +1,427 @@
+import { GITHUB_HIDE_REASONS, GITHUB_REACTIONS, GitHubNotFoundError, MarkerGuardError, findMarker, formatIssueCoordinate, isPharosAuthored, parseHideReason, parseReaction, } from "@floh-solutions/gh-core";
+import { emit, refusal, usageError } from "../output.js";
+import { approve } from "../session.js";
+import { describeTarget } from "../target.js";
+// MARK: - list
+/**
+ * Every comment on an issue, with the state and the permissions REST cannot
+ * report.
+ *
+ * **This verb is why the rest of them are usable at all.** Before it, nothing
+ * in this CLI could tell an agent a GitHub comment id: `pharos issue say`
+ * returns the id of the comment it just posted and that was the entire surface.
+ * The app never needed a list because it has a window. An agent has this.
+ *
+ * The `viewerCan…` flags are the part worth having. For a window they grey out
+ * a menu item; for an agent they turn a write that would 403 into a fact known
+ * before the write, which is the difference between a failed run and a run that
+ * reports what it may do.
+ */
+export async function githubList(io, session, issue) {
+    const { github, ref } = await resolve(session, issue);
+    const sweep = await github.comments.details(ref);
+    if (sweep.issueMissing) {
+        // GraphQL answers a null `repository` with NO errors entry for an issue
+        // that was deleted, transferred or is not visible to this account. Without
+        // this the caller cannot tell that from a discussion with no comments.
+        throw refusal(`${formatIssueCoordinate(issue)} could not be read as ${ref.account}. GitHub answered with `
+            + "no issue rather than an error, which is what it does for an issue that was deleted or "
+            + "transferred — or that this account cannot see.", { issue, account: ref.account });
+    }
+    return emit(io, {
+        target: formatIssueCoordinate(issue),
+        account: ref.account,
+        truncated: sweep.truncated,
+        comments: sweep.comments.map((comment) => ({
+            id: comment.id,
+            // Printed beside the number precisely so `hide` and `pin` need no lookup.
+            nodeId: comment.nodeId,
+            author: comment.author ?? null,
+            body: comment.body,
+            createdAt: comment.createdAt,
+            // Not `createdAt !== updatedAt`: a reaction moves updatedAt, so that
+            // comparison labels a comment edited because somebody gave it a 👍.
+            lastEditedAt: comment.lastEditedAt ?? null,
+            url: comment.htmlUrl ?? null,
+            hidden: comment.isMinimized,
+            hiddenReason: comment.minimizedReason ?? null,
+            pinned: comment.isPinned,
+            /** True when this comment carries the link record. */
+            pharosAuthored: isPharosAuthored(comment.body),
+            workItemId: findMarker(comment.body)?.adoId ?? null,
+            reactions: comment.reactions.map((group) => ({
+                type: group.reaction.cli,
+                emoji: group.reaction.emoji,
+                count: group.count,
+                mine: group.viewerHasReacted,
+            })),
+            may: {
+                edit: comment.viewerCanUpdate,
+                delete: comment.viewerCanDelete,
+                hide: comment.viewerCanMinimize,
+                unhide: comment.viewerCanUnminimize,
+                pin: comment.viewerCanPin,
+                unpin: comment.viewerCanUnpin,
+                react: comment.viewerCanReact,
+            },
+        })),
+    });
+}
+// MARK: - add, which is refused
+/**
+ * There is no `pharos comment add` on a GitHub issue, and there should not be.
+ *
+ * Plan §8 — do not rebuild `gh`. Two verbs already cover posting, and they
+ * cover different jobs: `gh issue comment` writes to GitHub, and
+ * `pharos issue say` writes the same message to GitHub *and* a summary to the
+ * work item, which is the whole reason the edge exists. A third door here would
+ * post to an adopted issue without the board ever hearing, which is exactly the
+ * asymmetry `say` was built to prevent — and it would do it under a verb whose
+ * Azure DevOps spelling *does* reach the board.
+ *
+ * Refused rather than silently absent: an agent that tries this has a real
+ * intention, and the useful answer names which of the two it wanted.
+ */
+export function githubRefuseAdd(issue) {
+    const coordinate = formatIssueCoordinate(issue);
+    throw usageError(`\`pharos comment add\` does not post to a GitHub issue. Two verbs already do, and which you `
+        + `want depends on whether the board should hear about it:\n`
+        + `  pharos issue say ${coordinate} "…"   the reporter AND the linked work item\n`
+        + `  gh issue comment ${issue.number} -R ${issue.repo} …   GitHub only\n`
+        + "This CLI owns the edge, not the nodes — and a comment posted here that the work item "
+        + "never heard about is the asymmetry `say` exists to prevent.", { issue, use: ["pharos issue say", "gh issue comment"] });
+}
+// MARK: - edit
+/**
+ * Edit a comment, behind `gh-core`'s marker guard.
+ *
+ * The guard is in the package rather than here on purpose — it is a rule about
+ * the link record, not about this command, and the macOS app writes through the
+ * same rule when it edits. What this arm adds is the reporting: a restored
+ * trailer is stated in the output rather than happening quietly.
+ */
+export async function githubEdit(io, session, issue, handle, text) {
+    const { github, ref } = await resolve(session, issue);
+    const id = await restId(session, ref, handle);
+    try {
+        const result = await github.comments.edit(ref, id, text);
+        return emit(io, {
+            applied: true,
+            target: formatIssueCoordinate(issue),
+            commentId: result.comment.id,
+            url: result.comment.htmlUrl ?? null,
+            /**
+             * The caller stripped the `pharos:v1` trailer and it was put back. Said
+             * out loud because the alternative — restoring it in silence — makes a
+             * body that differs from what was handed over, and an agent comparing
+             * what it sent with what is there would find a difference it cannot
+             * explain.
+             */
+            markerPreserved: result.markerPreserved,
+            workItemId: result.marker === undefined ? null : (findMarker(result.marker)?.adoId ?? null),
+        });
+    }
+    catch (error) {
+        if (error instanceof MarkerGuardError) {
+            // Reported as a refusal (exit 3), not a failure: nothing went wrong, the
+            // edit was declined for a reason the caller can act on.
+            throw refusal(error.message, {
+                issue,
+                commentId: id,
+                reason: error.reason,
+                trailers: error.detail,
+            });
+        }
+        throw error;
+    }
+}
+// MARK: - delete
+/**
+ * Delete a comment — and name what that costs before doing it.
+ *
+ * `approve()` already gates every destructive verb behind `--yes`. What is
+ * added here is that the preview knows whether this particular comment is the
+ * one carrying the `pharos:v1` trailer, because deleting **that** comment
+ * destroys the GitHub half of the link: `linksFromComments` reads it, so after
+ * this the pair is one-sided and `pharos issue drift` reports it — correctly,
+ * and after the fact.
+ *
+ * So the comment is read *before* the gate, including under `--dry-run`. A
+ * preview that could not say which of the two deletes this is would be a
+ * preview of the wrong thing.
+ *
+ * It is not refused outright. `--yes` is the caller's decision and there are
+ * good reasons to remove a link comment — a mis-adoption, a wrong repository.
+ * The repair is named instead.
+ */
+export async function githubRemove(io, session, issue, handle) {
+    const { github, ref } = await resolve(session, issue);
+    const id = await restId(session, ref, handle);
+    let existing;
+    try {
+        existing = await github.comments.get(ref, id);
+    }
+    catch (error) {
+        if (!(error instanceof GitHubNotFoundError))
+            throw error;
+        /**
+         * **Already gone, and that is success.**
+         *
+         * This read exists so the preview can say whether the comment carries the
+         * link — but adding it would otherwise have broken the one property
+         * `CommentsApi.remove` is careful to provide: a delete whose reply was lost
+         * and is retried gets a 404, and that 404 means the caller got what it
+         * asked for. Without this arm the retry failed on the *read* before ever
+         * reaching the idempotent DELETE, which is the exact "sends somebody
+         * looking for a comment that is already gone" failure the rule is about.
+         * Found by running it against real GitHub rather than by a test (#827).
+         *
+         * The `--yes` gate is skipped deliberately: there is nothing left to
+         * destroy, and demanding confirmation for a no-op is how a safe retry
+         * becomes a manual step.
+         */
+        return emit(io, {
+            applied: true,
+            action: "deleted",
+            target: formatIssueCoordinate(issue),
+            commentId: id,
+            alreadyGone: true,
+            // Not knowable now — the comment is gone and so is its body.
+            carriesLinkMarker: null,
+            workItemId: null,
+            // The ambiguity stated rather than hidden: this is the same status code
+            // GitHub gives for a comment that exists and is not visible to this
+            // account, so "already gone" is the likely reading and not the only one.
+            note: `Nothing to delete: comment ${String(id)} is not there. On GitHub a 404 is also how `
+                + `"not visible to this account" is spelled, so if you did not expect this, check that `
+                + `${ref.account} is the right account for ${issue.repo} in repos.json.`,
+        });
+    }
+    const marker = findMarker(existing.body);
+    const carriesLink = isPharosAuthored(existing.body);
+    const stop = approve(io, session, {
+        what: carriesLink
+            ? `delete comment ${id} on ${formatIssueCoordinate(issue)} — THE COMMENT CARRYING THE LINK`
+            : `delete comment ${id} on ${formatIssueCoordinate(issue)}`,
+        would: {
+            action: "deleteComment",
+            target: formatIssueCoordinate(issue),
+            commentId: id,
+            author: existing.author ?? null,
+            /**
+             * The consequence, structured, so a caller reading JSON sees it too.
+             * "A caveat in a reply is a gap somebody closes the todo over."
+             */
+            carriesLinkMarker: carriesLink,
+            workItemId: marker?.adoId ?? null,
+            ...(carriesLink
+                ? {
+                    consequence: "This is the comment that records the link to Azure DevOps. Deleting it leaves the "
+                        + "pair one-sided: `pharos issue trail` will stop resolving it from the GitHub end "
+                        + "and `pharos issue drift` will report it.",
+                    repair: marker === undefined
+                        ? `pharos issue link ${formatIssueCoordinate(issue)} <work-item-id> --yes`
+                        : `pharos issue link ${formatIssueCoordinate(issue)} ${marker.adoId} --yes`,
+                }
+                : {}),
+        },
+        // The one destructive verb in this CLI that writes to GitHub and to nothing
+        // else, so the gate must not resolve an Azure DevOps credential on its way
+        // past. Everything above this line already ran without one (#839).
+        platform: "github",
+    });
+    if (stop !== undefined)
+        return stop;
+    const { existed } = await github.comments.remove(ref, id);
+    return emit(io, {
+        applied: true,
+        action: "deleted",
+        target: formatIssueCoordinate(issue),
+        commentId: id,
+        // A 404 on delete is success — a retry after a lost reply gets one, and it
+        // means the caller got what it asked for. Reported, never failed over.
+        alreadyGone: !existed,
+        carriesLinkMarker: carriesLink,
+        workItemId: marker?.adoId ?? null,
+    });
+}
+// MARK: - reactions
+export async function githubReact(io, session, issue, handle, rawReaction, engaged) {
+    const reaction = reactionArgument(rawReaction);
+    const { github, ref } = await resolve(session, issue);
+    const id = await restId(session, ref, handle);
+    const { changed } = await github.comments.setReaction(ref, id, reaction, engaged);
+    return emit(io, {
+        applied: true,
+        target: formatIssueCoordinate(issue),
+        commentId: id,
+        type: reaction.cli,
+        emoji: reaction.emoji,
+        engaged,
+        /**
+         * False when the end state was already true — un-reacting something you
+         * never reacted to. A desired end state rather than a toggle is what makes
+         * the verb safe to repeat, and this is how a repeat reports itself.
+         */
+        changed,
+    });
+}
+/** A count is not a name — "three people reacted" needs this second call. */
+export async function githubReactors(io, session, issue, handle, rawReaction) {
+    const reaction = reactionArgument(rawReaction);
+    const { github, ref } = await resolve(session, issue);
+    const id = await restId(session, ref, handle);
+    const { owner, name } = splitRepo(ref.repo);
+    const rows = await github.http.request({
+        account: ref.account,
+        method: "GET",
+        path: `repos/${owner}/${name}/issues/comments/${id}/reactions`,
+        query: { content: reaction.rest, per_page: 100 },
+        idempotent: true,
+    });
+    const logins = (Array.isArray(rows) ? rows : [])
+        .map((row) => row.user?.login)
+        .filter((login) => typeof login === "string");
+    return emit(io, {
+        target: formatIssueCoordinate(issue),
+        commentId: id,
+        type: reaction.cli,
+        emoji: reaction.emoji,
+        count: logins.length,
+        logins,
+    });
+}
+// MARK: - hide and pin
+/**
+ * Hide or unhide, over GraphQL. There is no REST route — `POST …/minimize`
+ * answers 404.
+ *
+ * The reason is read back and reported as GitHub spells it, which is **not**
+ * how it was sent: `OFF_TOPIC` goes out and `off-topic` comes back. The CLI
+ * takes the display spelling for exactly that reason — ask for `off-topic`,
+ * read `off-topic`, and nothing has to know about the asymmetry.
+ */
+export async function githubHide(io, session, issue, handle, reason) {
+    const { github, ref } = await resolve(session, issue);
+    const nodeId = await nodeIdOf(session, ref, handle);
+    const state = await github.comments.setHidden(ref, nodeId, reason);
+    return emit(io, {
+        applied: true,
+        target: formatIssueCoordinate(issue),
+        nodeId,
+        hidden: state.isMinimized,
+        // GitHub's own words, from the mutation's own payload — not an echo of what
+        // was asked for. If those two ever disagree, this is the one that is true.
+        hiddenReason: state.minimizedReason ?? null,
+        ...(reason === undefined ? {} : { requested: reason.display, sent: reason.wire }),
+    });
+}
+/**
+ * Pin or unpin, over GraphQL. No REST route exists at all.
+ *
+ * The input field is `issueCommentId`, not `subjectId` as minimize takes —
+ * handled in `gh-core`, noted here because the two mutations sit beside each
+ * other in GitHub's schema and the wrong one is an HTTP 200 that does nothing.
+ */
+export async function githubPin(io, session, issue, handle, pinned) {
+    const { github, ref } = await resolve(session, issue);
+    const nodeId = await nodeIdOf(session, ref, handle);
+    const now = await github.comments.setPinned(ref, nodeId, pinned);
+    return emit(io, {
+        applied: true,
+        target: formatIssueCoordinate(issue),
+        nodeId,
+        pinned: now,
+    });
+}
+// MARK: - arguments
+/**
+ * Azure DevOps has no hide and no pin — not "not implemented here", **no such
+ * concept in the API**.
+ *
+ * Said plainly rather than reported as an unknown verb, because those are
+ * different facts: an unknown verb reads as a gap this CLI could close, and
+ * somebody would then go looking for the endpoint.
+ *
+ * **Returns the error rather than throwing it**, so the call site reads
+ * `if (target.kind !== "githubIssue") throw noSuchThingOnAzureDevOps(…)` and the
+ * compiler narrows the target on the next line. A function that threw would
+ * leave every GitHub-only arm needing a second refusal for a case that cannot
+ * happen — which is how an impossible branch acquires code nobody tests.
+ */
+export function noSuchThingOnAzureDevOps(target, verb) {
+    return usageError(`\`comment ${verb}\` is a GitHub thing, and ${describeTarget(target)} is on Azure DevOps, `
+        + "which has neither hidden nor pinned comments — there is no field to set and no endpoint "
+        + "to call. Name a GitHub issue (contoso/widgets#45).", { verb, target: describeTarget(target) });
+}
+export function hideReasonArgument(raw) {
+    const reasons = GITHUB_HIDE_REASONS.map((reason) => reason.display);
+    if (raw === undefined) {
+        throw usageError(`Hide it as what? \`pharos comment hide <owner/name#n> <comment> <reason>\` — one of: `
+            + `${reasons.join(", ")}. GitHub requires a classifier and shows it beside the hidden `
+            + "comment, so there is no neutral default to pick.", { reasons });
+    }
+    const reason = parseHideReason(raw);
+    if (reason === undefined) {
+        throw usageError(`"${raw}" is not a hide reason. One of: ${reasons.join(", ")}.`, { reasons });
+    }
+    return reason;
+}
+function reactionArgument(raw) {
+    const names = GITHUB_REACTIONS.map((reaction) => reaction.cli);
+    if (raw === undefined) {
+        throw usageError(`Which reaction? One of: ${names.join(", ")}.`, { reactions: names });
+    }
+    const reaction = parseReaction(raw);
+    if (reaction === undefined) {
+        throw usageError(`"${raw}" is not a GitHub reaction. One of: ${names.join(", ")}. Azure DevOps's names `
+            + "(like, dislike, smile) are a different vocabulary and are not accepted here.", { reactions: names });
+    }
+    return reaction;
+}
+// MARK: - resolving
+async function resolve(session, issue) {
+    const github = await session.github();
+    // Throws a GitHubConfigError naming the repo and repos.json when unbound —
+    // reported as kind "config", exit 2, because no retry can fix it.
+    const binding = github.binding(issue.repo);
+    return { github, ref: { ...binding, number: issue.number } };
+}
+/** The REST id, looked up from the node id only when that is what was given. */
+async function restId(session, ref, handle) {
+    if (handle.kind === "rest")
+        return handle.id;
+    // The node id addresses nothing over REST, and there is no single-node REST
+    // route to resolve it — so this is the discussion read, and it is the one
+    // direction of the lookup that costs a page walk. Passing the number instead
+    // (which `list` prints beside the node id) avoids it entirely.
+    const github = await session.github();
+    const sweep = await github.comments.details(ref);
+    const found = sweep.comments.find((comment) => comment.nodeId === handle.nodeId);
+    if (found === undefined) {
+        throw usageError(`No comment with node id ${handle.nodeId} on ${formatIssueCoordinate(ref)}. `
+            + "`pharos comment list` prints both ids for every comment.", { nodeId: handle.nodeId });
+    }
+    return found.id;
+}
+/** The node id, looked up from the REST id only when that is what was given. */
+async function nodeIdOf(session, ref, handle) {
+    if (handle.kind === "node")
+        return handle.nodeId;
+    // One cheap REST read — the single-comment route carries `node_id`. This is
+    // the direction that does NOT need a page walk, which is why `hide` given a
+    // number costs two requests and given a node id costs one.
+    const github = await session.github();
+    const comment = await github.comments.get(ref, handle.id);
+    const nodeId = comment.nodeId;
+    if (nodeId === undefined || nodeId === "") {
+        throw usageError(`Comment ${handle.id} on ${formatIssueCoordinate(ref)} reported no node id, so it cannot be `
+            + "hidden or pinned — both are GraphQL mutations and the node id is what they address.", { commentId: handle.id });
+    }
+    return nodeId;
+}
+function splitRepo(repo) {
+    const slash = repo.indexOf("/");
+    return { owner: repo.slice(0, slash), name: repo.slice(slash + 1) };
+}
+//# sourceMappingURL=comment-github.js.map

package/dist/commands/comment-github.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"comment-github.js","sourceRoot":"","sources":["../../src/commands/comment-github.ts"],"names":[],"mappings":"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"}

package/dist/commands/comment.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"comment.d.ts","sourceRoot":"","sources":["../../src/commands/comment.ts"],"names":[],"mappings":"AAEA,OAAO,EAAoB,KAAK,QAAQ,EAAE,KAAK,EAAE,EAAE,MAAM,cAAc,CAAC;AACxE,OAAO,EAAW,KAAK,OAAO,EAAE,MAAM,eAAe,CAAC;AAoCtD,wBAAsB,UAAU,CAC9B,EAAE,EAAE,EAAE,EACN,OAAO,EAAE,OAAO,EAChB,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,KAAK,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GACnC,OAAO,CAAC,QAAQ,CAAC,CAoCnB"}
+{"version":3,"file":"comment.d.ts","sourceRoot":"","sources":["../../src/commands/comment.ts"],"names":[],"mappings":"AAEA,OAAO,EAAoB,KAAK,QAAQ,EAAE,KAAK,EAAE,EAAE,MAAM,cAAc,CAAC;AACxE,OAAO,EAAW,KAAK,OAAO,EAAE,MAAM,eAAe,CAAC;AAuFtD,wBAAsB,UAAU,CAC9B,EAAE,EAAE,EAAE,EACN,OAAO,EAAE,OAAO,EAChB,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,KAAK,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GACnC,OAAO,CAAC,QAAQ,CAAC,CAoEnB"}

package/dist/commands/comment.js

@@ -1,8 +1,9 @@
 import { emit, usageError } from "../output.js";
 import { approve } from "../session.js";
 import { describeTarget, parseTarget } from "../target.js";
+import { githubHide, githubList, githubPin, githubReact, githubReactors, githubRefuseAdd, githubRemove, githubEdit, hideReasonArgument, noSuchThingOnAzureDevOps, } from "./comment-github.js";
 /**
- * `pharos comment …` — the discussion, on either surface.
+ * `pharos comment …` — the discussion, on any of its three surfaces.
  *
  * **Wiki comments exist in no other tool.** The Azure DevOps MCP server ships
  * none of these verbs for a wiki page — not list, not add, not edit, not
@@ -10,19 +11,43 @@ import { describeTarget, parseTarget } from "../target.js";
  * comments it has add and update only, so delete and reactions are also
  * reachable from nowhere else.
  *
- * The two surfaces behave differently in ways that would bite a caller writing
- * this by hand, and each difference is handled on its own side rather than
- * assumed away:
+ * The surfaces behave differently in ways that would bite a caller writing this
+ * by hand, and each difference is handled on its own side rather than assumed
+ * away:
  *
- * | | work item | wiki page |
- * |---|---|---|
- * | keyed on | the work item id | the page's NUMERIC id, not its path |
- * | `includeDeleted` | honoured | ignored — deleted comments come back regardless |
- * | second delete | 404 | 500 |
- * | reactions api-version | `7.2-preview.1` | `7.1-preview.1` |
+ * | | work item | wiki page | GitHub issue |
+ * |---|---|---|---|
+ * | keyed on | the work item id | the page's NUMERIC id, not its path | the issue coordinate |
+ * | `includeDeleted` | honoured | ignored — deleted comments come back regardless | n/a |
+ * | second delete | 404 | 500 | 404, and it means success |
+ * | reactions api-version | `7.2-preview.1` | `7.1-preview.1` | n/a |
+ * | reaction vocabulary | like/dislike/heart/hooray/smile/confused | same | eight, and `+1` is one of them |
+ * | hide, pin | no such concept | no such concept | GraphQL only — no REST route exists |
  *
- * Both are `swallowed`/`filtered`/`pinned` inside `ado-core`; the table is here
- * because the temptation when reading this file is to unify the two branches.
+ * The first two are `swallowed`/`filtered`/`pinned` inside `ado-core`; the
+ * GitHub arm lives in `comment-github.ts` over `gh-core`. The table is here
+ * because the temptation when reading this file is to unify the branches.
+ *
+ * ## Why GitHub is a third target rather than `pharos issue comment`
+ *
+ * Because `Target` already existed. This file has always dispatched on "which
+ * kind of thing is this comment attached to", and a GitHub issue is a third
+ * answer to a question that was already being asked. The alternative spells
+ * `edit`, `delete`, `react` and `unreact` a second time under another noun,
+ * over another engine — the drifting-second-implementation shape `AGENTS.md`
+ * names three separate times, and the one it says nobody looks at.
+ *
+ * ## `add` is REFUSED on a GitHub issue, and that refusal is the design
+ *
+ * Plan §8: do not rebuild `gh`. Posting a plain comment is `gh issue comment`,
+ * and posting one that reaches the reporter *and* the board is
+ * `pharos issue say`. A `pharos comment add` on a GitHub issue would be a third
+ * thing — a comment on an adopted issue that the work item never hears about —
+ * which is precisely the asymmetry `say` exists to prevent. So it is refused
+ * with both alternatives named. See {@link githubRefuseAdd}.
+ *
+ * Everything else here acts on a comment that already exists, which is work
+ * neither `gh` nor `say` does at all.
  */
 const REACTIONS = [
     "like",
@@ -32,35 +57,81 @@ const REACTIONS = [
     "smile",
     "confused",
 ];
+const VERBS = [
+    "list",
+    "add",
+    "edit",
+    "delete",
+    "react",
+    "unreact",
+    "reactors",
+    "hide",
+    "unhide",
+    "pin",
+    "unpin",
+];
 export async function runComment(io, session, positionals, input) {
     const verb = positionals[0];
     if (verb === undefined) {
-        throw usageError("`pharos comment <list|add|edit|delete|react|unreact> <target> …`.");
+        throw usageError(`\`pharos comment <${VERBS.join("|")}> <target> …\`.`, { verbs: VERBS });
     }
     const rawTarget = positionals[1];
     if (rawTarget === undefined) {
-        throw usageError(`Which thing? \`pharos comment ${verb} <target>\` — a work item id (210) or a wiki page `
-            + "path (/Plans/Foo).");
+        throw usageError(`Which thing? \`pharos comment ${verb} <target>\` — a work item id (210), a wiki page `
+            + "path (/Plans/Foo), or a GitHub issue (contoso/widgets#45).");
     }
     const target = parseTarget(rawTarget);
     const rest = positionals.slice(2);
     switch (verb) {
         case "list":
+            if (target.kind === "githubIssue")
+                return githubList(io, session, target.issue);
             return list(io, session, target);
         case "add":
+            if (target.kind === "githubIssue")
+                return githubRefuseAdd(target.issue);
             return add(io, session, target, textFrom(rest[0], input.text));
         case "edit":
+            if (target.kind === "githubIssue") {
+                return githubEdit(io, session, target.issue, handle(rest[0]), textFrom(rest[1], input.text));
+            }
             return edit(io, session, target, commentId(rest[0]), textFrom(rest[1], input.text));
         case "delete":
+            if (target.kind === "githubIssue")
+                return githubRemove(io, session, target.issue, handle(rest[0]));
             return remove(io, session, target, commentId(rest[0]));
         case "react":
-            return react(io, session, target, commentId(rest[0]), reactionType(rest[1]), true);
-        case "unreact":
-            return react(io, session, target, commentId(rest[0]), reactionType(rest[1]), false);
+        case "unreact": {
+            const on = verb === "react";
+            if (target.kind === "githubIssue") {
+                return githubReact(io, session, target.issue, handle(rest[0]), rest[1], on);
+            }
+            return react(io, session, target, commentId(rest[0]), reactionType(rest[1]), on);
+        }
         case "reactors":
+            if (target.kind === "githubIssue") {
+                return githubReactors(io, session, target.issue, handle(rest[0]), rest[1]);
+            }
             return reactors(io, session, target, commentId(rest[0]), reactionType(rest[1]));
+        // Hide and pin exist on GitHub and nowhere else — Azure DevOps has no such
+        // field and no such endpoint, so the refusal says that rather than letting
+        // it read as a verb this CLI has not got round to.
+        case "hide":
+        case "unhide": {
+            if (target.kind !== "githubIssue")
+                throw noSuchThingOnAzureDevOps(target, verb);
+            return githubHide(io, session, target.issue, handle(rest[0]), verb === "hide" ? hideReasonArgument(rest[1]) : undefined);
+        }
+        case "pin":
+        case "unpin": {
+            if (target.kind !== "githubIssue")
+                throw noSuchThingOnAzureDevOps(target, verb);
+            return githubPin(io, session, target.issue, handle(rest[0]), verb === "pin");
+        }
         default:
-            throw usageError(`Unknown comment verb "${verb}". Try list, add, edit, delete, react, unreact or reactors.`);
+            throw usageError(`Unknown comment verb "${verb}". Try ${VERBS.join(", ")}.`, {
+                verbs: VERBS,
+            });
     }
 }
 async function list(io, session, target) {
@@ -206,6 +277,30 @@ function commentId(raw) {
     }
     return Number(raw);
 }
+/**
+ * A GitHub comment, named by **either** of its two ids.
+ *
+ * GitHub gives a comment a numeric REST id and a string node id, and neither is
+ * derivable from the other: edit, delete and reactions address the number,
+ * while hide and pin take the node. `pharos comment list` prints both, so the
+ * normal agent flow — list, then act — already holds whichever one is needed.
+ *
+ * Taking either here means that flow never needs a lookup: pass the number and
+ * a verb that wants the node resolves it with one extra read; pass the node
+ * back and nothing is spent. Anything not all-digits is treated as a node id
+ * (they are opaque strings, currently `IC_…`, and this does not hard-code that
+ * prefix — GitHub has changed node id formats before).
+ */
+function handle(raw) {
+    if (raw === undefined || raw.trim() === "") {
+        throw usageError("Which comment? Expected a comment id — the number or the node id, both of which "
+            + "`pharos comment list <owner/name#n>` prints.");
+    }
+    const value = raw.trim();
+    return /^\d+$/.test(value)
+        ? { kind: "rest", id: Number(value) }
+        : { kind: "node", nodeId: value };
+}
 function reactionType(raw) {
     if (raw === undefined) {
         throw usageError(`Which reaction? One of: ${REACTIONS.join(", ")}.`);