@floh-solutions/pharos-cli 0.24.0 → 0.26.0

package/dist/commands/bridge.js

@@ -0,0 +1,255 @@
+import { WorkItemTypesApi, selectableTypes, typeForCategory } from "@floh-solutions/ado-core";
+import { CATEGORY, brokenMappings, categoryFor, defaultBridgePath, digestPolicy, emptyBridgeConfig, formatBridgeConfig, parseBridgeConfig, repoConfig, scopeKey, } from "../bridge.js";
+import { emit } from "../output.js";
+/**
+ * `pharos bridge` — **the mapping, and the file the app reads through these
+ * verbs rather than around them** (#861).
+ *
+ * ## Why the app does not read the file itself
+ *
+ * The rule `pharos-convert` and `doctor` already follow, and the one AGENTS.md
+ * restates every time it is broken: if the app parses the mapping and the CLI
+ * parses the mapping, that is two answers to one question, and the one that
+ * drifts is the one nobody is watching. `adopt` in a headless session would
+ * quietly file to a different type than the same gesture in the GUI.
+ *
+ * So this is the engine and the settings page is a door. Every verb takes
+ * `--json` with stable keys, because a GUI that has to parse English to know
+ * what happened is a GUI that will eventually be wrong.
+ */
+export async function runBridge(io, session, positionals, options = {}) {
+    const verb = positionals[0] ?? "show";
+    const env = options.env ?? process.env;
+    const path = defaultBridgePath(env);
+    const organization = session.client.organization;
+    const project = session.client.project ?? "";
+    switch (verb) {
+        case "show":
+            return show(io, session, path, organization, project, env);
+        case "labels":
+            return labels(io, session, path, organization, project, options, env);
+        case "map":
+            return map(io, session, path, organization, project, options, env);
+        case "unmap":
+            return unmap(io, path, organization, project, options, env);
+        case "digest":
+            return digest(io, path, organization, project, options, env);
+        default:
+            emit(io, {
+                ok: false,
+                error: {
+                    kind: "usage",
+                    message: `Unknown "bridge ${verb}". Try show, labels, map, unmap or digest.`,
+                    commands: ["show", "labels", "map", "unmap", "digest"],
+                },
+            });
+            return 2;
+    }
+}
+async function readConfig(path) {
+    try {
+        const { readFile } = await import("node:fs/promises");
+        return parseBridgeConfig(await readFile(path, "utf8"), path);
+    }
+    catch (error) {
+        // A file that is not there yet is the ordinary state. One that cannot be
+        // parsed is NOT swallowed here, unlike on the adopt path — somebody running
+        // `bridge` is asking about the file itself, and hiding a syntax error from
+        // them is how they end up editing a file the tool is ignoring.
+        if (error.code === "ENOENT")
+            return emptyBridgeConfig();
+        throw error;
+    }
+}
+async function writeConfig(path, config) {
+    const { mkdir, writeFile } = await import("node:fs/promises");
+    const { dirname } = await import("node:path");
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, formatBridgeConfig(config), "utf8");
+}
+async function show(io, session, path, organization, project, _env) {
+    const config = await readConfig(path);
+    const scope = config.scopes[scopeKey(organization, project)];
+    // What the PROJECT says its types are, which is the half no file can hold.
+    let types = [];
+    let categories = {};
+    let unreachable;
+    try {
+        const api = new WorkItemTypesApi(session.client.http);
+        const catalog = await api.categories();
+        types = selectableTypes(await api.list(), catalog);
+        categories = Object.fromEntries(catalog.defaults);
+    }
+    catch (error) {
+        unreachable = error.message;
+    }
+    emit(io, {
+        ok: true,
+        file: path,
+        scope: `${organization}/${project}`,
+        repos: scope?.repos ?? {},
+        digest: digestPolicy(config, organization, project),
+        // The project's own answer, beside the mapping, because a category is
+        // meaningless without it — `Microsoft.BugCategory` is `Issue` here and
+        // `Bug` on the next board.
+        project: { types, categories, ...(unreachable === undefined ? {} : { unreachable }) },
+    });
+    return 0;
+}
+async function labels(io, session, path, organization, project, options, _env) {
+    const repo = options.repo;
+    if (repo === undefined) {
+        emit(io, {
+            ok: false,
+            error: { kind: "usage", message: "`bridge labels` needs --repo owner/name." },
+        });
+        return 2;
+    }
+    const config = await readConfig(path);
+    const entry = repoConfig(config, organization, project, repo);
+    const github = await session.github();
+    // Reached AS the account bound to it, never as whichever one `gh` has active
+    // — the rule AGENTS.md states about `--user`, one layer up.
+    const live = await github.repos.labels(github.binding(repo));
+    const rows = live.map((label) => {
+        const mapped = entry.labels[String(label.id)];
+        const choice = categoryFor([{ id: label.id ?? -1, name: label.name }], entry);
+        return {
+            id: label.id ?? null,
+            name: label.name,
+            // Three different facts, and a GUI needs to tell them apart: this is
+            // mapped, this is what an unmapped one would default to, and this is the
+            // repository's catch-all.
+            mapped: mapped?.category ?? null,
+            wouldUse: choice.categories,
+            source: choice.source,
+        };
+    });
+    emit(io, {
+        ok: true,
+        repo,
+        labels: rows,
+        defaultCategory: entry.defaultCategory,
+        // A mapping whose label is gone: reported, never pruned. Delete-and-recreate
+        // yields a NEW id, so what replaced it is somebody's decision to confirm.
+        broken: brokenMappings(entry, live.map((l) => ({ id: l.id ?? -1, name: l.name }))),
+    });
+    return 0;
+}
+async function map(io, session, path, organization, project, options, _env) {
+    const { repo, label, category } = options;
+    if (repo === undefined || label === undefined || category === undefined) {
+        emit(io, {
+            ok: false,
+            error: {
+                kind: "usage",
+                message: "`bridge map` needs --repo owner/name --label <id or name> --category <reference>",
+                categories: Object.values(CATEGORY),
+            },
+        });
+        return 2;
+    }
+    const config = await readConfig(path);
+    const key = scopeKey(organization, project);
+    const scope = config.scopes[key] ?? { repos: {}, digest: { onAdopt: true, onClose: true } };
+    const repoKey = repo.toLowerCase();
+    const entry = scope.repos[repoKey] ?? {
+        labels: {},
+        defaultCategory: CATEGORY.requirement,
+    };
+    // **Keyed on the id.** A name is accepted for convenience and resolved to one
+    // here rather than stored, because a mapping stored under a name stops
+    // resolving the moment somebody renames the label — which is the thing this
+    // whole design is about.
+    const id = /^\d+$/.test(label) ? label : undefined;
+    if (id === undefined) {
+        emit(io, {
+            ok: false,
+            error: {
+                kind: "usage",
+                message: `--label must be a label ID, not a name. Run \`pharos bridge labels --repo ${repo}\` `
+                    + "to see them: a mapping keyed on a name stops resolving when the label is renamed, "
+                    + "which is exactly what keying on the id avoids.",
+            },
+        });
+        return 2;
+    }
+    // **The NAME is looked up, never taken from the flag.** `--label` is an id,
+    // so storing it as the name would put a number in the display field and the
+    // settings page would show `11710323621` where a person expects `bug`. It is
+    // display-only either way — nothing matches on it — but a field whose whole
+    // job is to be readable has to be readable.
+    let name = label;
+    try {
+        const github = await session.github();
+        const live = await github.repos.labels(github.binding(repo));
+        name = live.find((candidate) => String(candidate.id) === id)?.name ?? label;
+    }
+    catch {
+        // Offline, or a repository this machine cannot reach. The mapping still
+        // saves — it is keyed on the id and works without the name — and the name
+        // fills in the next time `labels` is run.
+    }
+    entry.labels[id] = { name, category };
+    scope.repos[repoKey] = entry;
+    config.scopes[key] = scope;
+    await writeConfig(path, config);
+    emit(io, { ok: true, applied: true, repo, label: id, category, file: path });
+    return 0;
+}
+async function unmap(io, path, organization, project, options, _env) {
+    const { repo, label } = options;
+    if (repo === undefined || label === undefined) {
+        emit(io, {
+            ok: false,
+            error: { kind: "usage", message: "`bridge unmap` needs --repo owner/name --label <id>" },
+        });
+        return 2;
+    }
+    const config = await readConfig(path);
+    const key = scopeKey(organization, project);
+    const entry = config.scopes[key]?.repos[repo.toLowerCase()];
+    const had = entry !== undefined && entry.labels[label] !== undefined;
+    if (entry !== undefined)
+        delete entry.labels[label];
+    await writeConfig(path, config);
+    // `removed: false` rather than an error: unmapping something already unmapped
+    // is the state somebody wanted, and failing it would make the verb unsafe to
+    // run twice.
+    emit(io, { ok: true, applied: true, removed: had, repo, label, file: path });
+    return 0;
+}
+async function digest(io, path, organization, project, options, _env) {
+    const config = await readConfig(path);
+    const key = scopeKey(organization, project);
+    const scope = config.scopes[key] ?? { repos: {}, digest: { onAdopt: true, onClose: true } };
+    // **`--manual` is how it gets turned OFF**, and it exists because a boolean
+    // flag can only say true: `--on-close` cannot express "stop doing that", so
+    // without this the policy was write-only. `--manual` clears both, and either
+    // flag after it turns that one back on — so `--manual --on-adopt` is "on
+    // adopt only", which is the arrangement somebody actually asks for.
+    let changed = false;
+    if (options.manual === true) {
+        scope.digest = { onAdopt: false, onClose: false };
+        changed = true;
+    }
+    if (options.onAdopt !== undefined) {
+        scope.digest.onAdopt = options.onAdopt;
+        changed = true;
+    }
+    if (options.onClose !== undefined) {
+        scope.digest.onClose = options.onClose;
+        changed = true;
+    }
+    config.scopes[key] = scope;
+    if (changed)
+        await writeConfig(path, config);
+    emit(io, { ok: true, digest: scope.digest, file: path });
+    return 0;
+}
+/** Resolve a category against a live project — shared with `adopt`'s reporting. */
+export async function categoryToType(session, ...wanted) {
+    const catalog = await new WorkItemTypesApi(session.client.http).categories();
+    return typeForCategory(catalog, ...wanted);
+}
+//# sourceMappingURL=bridge.js.map

package/dist/commands/bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.js","sourceRoot":"","sources":["../../src/commands/bridge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAE9F,OAAO,EACL,QAAQ,EACR,cAAc,EACd,WAAW,EACX,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,UAAU,EACV,QAAQ,GAET,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,IAAI,EAA0B,MAAM,cAAc,CAAC;AAG5D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,EAAM,EACN,OAAgB,EAChB,WAA8B,EAC9B,UAQI,EAAE;IAEN,MAAM,IAAI,GAAG,WAAW,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC;IACtC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IACvC,MAAM,IAAI,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC;IACpC,MAAM,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC;IACjD,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,IAAI,EAAE,CAAC;IAE7C,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,MAAM;YACT,OAAO,IAAI,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;QAC7D,KAAK,QAAQ;YACX,OAAO,MAAM,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;QACxE,KAAK,KAAK;YACR,OAAO,GAAG,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;QACrE,KAAK,OAAO;YACV,OAAO,KAAK,CAAC,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;QAC9D,KAAK,QAAQ;YACX,OAAO,MAAM,CAAC,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;QAC/D;YACE,IAAI,CAAC,EAAE,EAAE;gBACP,EAAE,EAAE,KAAK;gBACT,KAAK,EAAE;oBACL,IAAI,EAAE,OAAO;oBACb,OAAO,EACL,mBAAmB,IAAI,4CAA4C;oBACrE,QAAQ,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC;iBACvD;aACF,CAAC,CAAC;YACH,OAAO,CAAC,CAAC;IACb,CAAC;AACH,CAAC;AAED,KAAK,UAAU,UAAU,CAAC,IAAY;IACpC,IAAI,CAAC;QACH,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,CAAC;QACtD,OAAO,iBAAiB,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,IAAI,CAAC,CAAC;IAC/D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,yEAAyE;QACzE,4EAA4E;QAC5E,2EAA2E;QAC3E,+DAA+D;QAC/D,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,iBAAiB,EAAE,CAAC;QACnF,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,KAAK,UAAU,WAAW,CAAC,IAAY,EAAE,MAAoB;IAC3D,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,CAAC;IAC9D,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC;IAC9C,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAChD,MAAM,SAAS,CAAC,IAAI,EAAE,kBAAkB,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC;AAC5D,CAAC;AAED,KAAK,UAAU,IAAI,CACjB,EAAM,EACN,OAAgB,EAChB,IAAY,EACZ,YAAoB,EACpB,OAAe,EACf,IAAuB;IAEvB,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,IAAI,CAAC,CAAC;IACtC,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC,CAAC;IAE7D,2EAA2E;IAC3E,IAAI,KAAK,GAAa,EAAE,CAAC;IACzB,IAAI,UAAU,GAA2B,EAAE,CAAC;IAC5C,IAAI,WAA+B,CAAC;IACpC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,gBAAgB,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACtD,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,UAAU,EAAE,CAAC;QACvC,KAAK,GAAG,eAAe,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,EAAE,OAAO,CAAC,CAAC;QACnD,UAAU,GAAG,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACpD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,WAAW,GAAI,KAAe,CAAC,OAAO,CAAC;IACzC,CAAC;IAED,IAAI,CAAC,EAAE,EAAE;QACP,EAAE,EAAE,IAAI;QACR,IAAI,EAAE,IAAI;QACV,KAAK,EAAE,GAAG,YAAY,IAAI,OAAO,EAAE;QACnC,KAAK,EAAE,KAAK,EAAE,KAAK,IAAI,EAAE;QACzB,MAAM,EAAE,YAAY,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,CAAC;QACnD,sEAAsE;QACtE,uEAAuE;QACvE,2BAA2B;QAC3B,OAAO,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,GAAG,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE;KACtF,CAAC,CAAC;IACH,OAAO,CAAC,CAAC;AACX,CAAC;AAED,KAAK,UAAU,MAAM,CACnB,EAAM,EACN,OAAgB,EAChB,IAAY,EACZ,YAAoB,EACpB,OAAe,EACf,OAAsC,EACtC,IAAuB;IAEvB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAC1B,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,IAAI,CAAC,EAAE,EAAE;YACP,EAAE,EAAE,KAAK;YACT,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,0CAA0C,EAAE;SAC9E,CAAC,CAAC;QACH,OAAO,CAAC,CAAC;IACX,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,IAAI,CAAC,CAAC;IACtC,MAAM,KAAK,GAAG,UAAU,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IAC9D,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC;IACtC,6EAA6E;IAC7E,4DAA4D;IAC5D,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IAE7D,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;QAC9B,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;QAC9C,MAAM,MAAM,GAAG,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,CAAC,EAAE,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC;QAC9E,OAAO;YACL,EAAE,EAAE,KAAK,CAAC,EAAE,IAAI,IAAI;YACpB,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,qEAAqE;YACrE,yEAAyE;YACzE,0BAA0B;YAC1B,MAAM,EAAE,MAAM,EAAE,QAAQ,IAAI,IAAI;YAChC,QAAQ,EAAE,MAAM,CAAC,UAAU;YAC3B,MAAM,EAAE,MAAM,CAAC,MAAM;SACtB,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,EAAE,EAAE;QACP,EAAE,EAAE,IAAI;QACR,IAAI;QACJ,MAAM,EAAE,IAAI;QACZ,eAAe,EAAE,KAAK,CAAC,eAAe;QACtC,6EAA6E;QAC7E,0EAA0E;QAC1E,MAAM,EAAE,cAAc,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;KACnF,CAAC,CAAC;IACH,OAAO,CAAC,CAAC;AACX,CAAC;AAED,KAAK,UAAU,GAAG,CAChB,EAAM,EACN,OAAgB,EAChB,IAAY,EACZ,YAAoB,EACpB,OAAe,EACf,OAAiG,EACjG,IAAuB;IAEvB,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;IAC1C,IAAI,IAAI,KAAK,SAAS,IAAI,KAAK,KAAK,SAAS,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QACxE,IAAI,CAAC,EAAE,EAAE;YACP,EAAE,EAAE,KAAK;YACT,KAAK,EAAE;gBACL,IAAI,EAAE,OAAO;gBACb,OAAO,EAAE,kFAAkF;gBAC3F,UAAU,EAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC;aACpC;SACF,CAAC,CAAC;QACH,OAAO,CAAC,CAAC;IACX,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,IAAI,CAAC,CAAC;IACtC,MAAM,GAAG,GAAG,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;IAC5C,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,CAAC;IAC5F,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;IACnC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI;QACpC,MAAM,EAAE,EAAE;QACV,eAAe,EAAE,QAAQ,CAAC,WAAW;KACtC,CAAC;IAEF,8EAA8E;IAC9E,uEAAuE;IACvE,4EAA4E;IAC5E,yBAAyB;IACzB,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;IACnD,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;QACrB,IAAI,CAAC,EAAE,EAAE;YACP,EAAE,EAAE,KAAK;YACT,KAAK,EAAE;gBACL,IAAI,EAAE,OAAO;gBACb,OAAO,EACL,6EAA6E,IAAI,KAAK;sBACpF,oFAAoF;sBACpF,gDAAgD;aACrD;SACF,CAAC,CAAC;QACH,OAAO,CAAC,CAAC;IACX,CAAC;IAED,4EAA4E;IAC5E,4EAA4E;IAC5E,6EAA6E;IAC7E,4EAA4E;IAC5E,4CAA4C;IAC5C,IAAI,IAAI,GAAG,KAAK,CAAC;IACjB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC;QACtC,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QAC7D,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,IAAI,IAAI,KAAK,CAAC;IAC9E,CAAC;IAAC,MAAM,CAAC;QACP,wEAAwE;QACxE,0EAA0E;QAC1E,0CAA0C;IAC5C,CAAC;IACD,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IACtC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,KAAK,CAAC;IAC7B,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IAC3B,MAAM,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAEhC,IAAI,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7E,OAAO,CAAC,CAAC;AACX,CAAC;AAED,KAAK,UAAU,KAAK,CAClB,EAAM,EACN,IAAY,EACZ,YAAoB,EACpB,OAAe,EACf,OAAkE,EAClE,IAAuB;IAEvB,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC;IAChC,IAAI,IAAI,KAAK,SAAS,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QAC9C,IAAI,CAAC,EAAE,EAAE;YACP,EAAE,EAAE,KAAK;YACT,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,qDAAqD,EAAE;SACzF,CAAC,CAAC;QACH,OAAO,CAAC,CAAC;IACX,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,IAAI,CAAC,CAAC;IACtC,MAAM,GAAG,GAAG,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;IAC5C,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;IAC5D,MAAM,GAAG,GAAG,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,SAAS,CAAC;IACrE,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACpD,MAAM,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAEhC,8EAA8E;IAC9E,6EAA6E;IAC7E,aAAa;IACb,IAAI,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7E,OAAO,CAAC,CAAC;AACX,CAAC;AAED,KAAK,UAAU,MAAM,CACnB,EAAM,EACN,IAAY,EACZ,YAAoB,EACpB,OAAe,EACf,OAIC,EACD,IAAuB;IAEvB,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,IAAI,CAAC,CAAC;IACtC,MAAM,GAAG,GAAG,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;IAC5C,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,CAAC;IAE5F,4EAA4E;IAC5E,4EAA4E;IAC5E,6EAA6E;IAC7E,yEAAyE;IACzE,oEAAoE;IACpE,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,IAAI,OAAO,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;QAC5B,KAAK,CAAC,MAAM,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAClD,OAAO,GAAG,IAAI,CAAC;IACjB,CAAC;IACD,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAClC,KAAK,CAAC,MAAM,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QACvC,OAAO,GAAG,IAAI,CAAC;IACjB,CAAC;IACD,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAClC,KAAK,CAAC,MAAM,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QACvC,OAAO,GAAG,IAAI,CAAC;IACjB,CAAC;IACD,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IAE3B,IAAI,OAAO;QAAE,MAAM,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAE7C,IAAI,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IACzD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,mFAAmF;AACnF,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,OAAgB,EAChB,GAAG,MAAyB;IAE5B,MAAM,OAAO,GAAG,MAAM,IAAI,gBAAgB,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,CAAC;IAC7E,OAAO,eAAe,CAAC,OAAO,EAAE,GAAG,MAAM,CAAC,CAAC;AAC7C,CAAC"}

package/dist/commands/comment-github.d.ts

@@ -0,0 +1,138 @@
+import { type GitHubHideReason, type IssueCoordinate } from "@floh-solutions/gh-core";
+import { type CliError, type ExitCode, type Io } from "../output.js";
+import { type Session } from "../session.js";
+import { type AdoTarget } from "../target.js";
+/**
+ * `pharos comment …` on a GitHub issue — the half `gh-core` grew for #827.
+ *
+ * A sibling of the two Azure DevOps arms in `comment.ts`, not a second command:
+ * the verbs, the target grammar and the output shape are that file's, and this
+ * is the branch that knows what they mean on GitHub. Read its header first.
+ *
+ * ## What each verb costs, because an agent should be able to predict it
+ *
+ * | verb | requests | door |
+ * |---|---|---|
+ * | `list` | 1 per 100 comments | GraphQL |
+ * | `edit` | 2 — the read the marker guard needs, then the PATCH | REST |
+ * | `delete` | 2 — read to name the consequence, then the DELETE | REST |
+ * | `react` | 1 | REST |
+ * | `unreact` | 2 — `DELETE` names the reaction ROW id, so it lists first | REST |
+ * | `reactors` | 1 | REST |
+ * | `hide` / `unhide` / `pin` / `unpin` | 1, or 2 given a numeric id | GraphQL |
+ *
+ * The second request on `hide` and friends is the node-id lookup, and it
+ * disappears when the node id from `list` is passed back — see `handle()` in
+ * `comment.ts`.
+ *
+ * ## The account is never guessed
+ *
+ * Every call resolves its binding from `repos.json` through
+ * `GitHubClient.binding`, which throws naming the file when a repo is unbound.
+ * Plan §2: with more than one `gh` account signed in, letting anything else
+ * choose returns a perfectly good 200 from the wrong repository.
+ */
+/** A comment named by either of its two ids. See `handle()` in `comment.ts`. */
+export type GitHubCommentHandle = {
+    kind: "rest";
+    id: number;
+} | {
+    kind: "node";
+    nodeId: string;
+};
+/**
+ * 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 declare function githubList(io: Io, session: Session, issue: IssueCoordinate): Promise<ExitCode>;
+/**
+ * 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 declare function githubRefuseAdd(issue: IssueCoordinate): never;
+/**
+ * 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 declare function githubEdit(io: Io, session: Session, issue: IssueCoordinate, handle: GitHubCommentHandle, text: string): Promise<ExitCode>;
+/**
+ * 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 declare function githubRemove(io: Io, session: Session, issue: IssueCoordinate, handle: GitHubCommentHandle): Promise<ExitCode>;
+export declare function githubReact(io: Io, session: Session, issue: IssueCoordinate, handle: GitHubCommentHandle, rawReaction: string | undefined, engaged: boolean): Promise<ExitCode>;
+/** A count is not a name — "three people reacted" needs this second call. */
+export declare function githubReactors(io: Io, session: Session, issue: IssueCoordinate, handle: GitHubCommentHandle, rawReaction: string | undefined): Promise<ExitCode>;
+/**
+ * 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 declare function githubHide(io: Io, session: Session, issue: IssueCoordinate, handle: GitHubCommentHandle, reason: GitHubHideReason | undefined): Promise<ExitCode>;
+/**
+ * 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 declare function githubPin(io: Io, session: Session, issue: IssueCoordinate, handle: GitHubCommentHandle, pinned: boolean): Promise<ExitCode>;
+/**
+ * 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 declare function noSuchThingOnAzureDevOps(target: AdoTarget, verb: string): CliError;
+export declare function hideReasonArgument(raw: string | undefined): GitHubHideReason;
+//# sourceMappingURL=comment-github.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"comment-github.d.ts","sourceRoot":"","sources":["../../src/commands/comment-github.ts"],"names":[],"mappings":"AAAA,OAAO,EAUL,KAAK,gBAAgB,EACrB,KAAK,eAAe,EAErB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAA6B,KAAK,QAAQ,EAAE,KAAK,QAAQ,EAAE,KAAK,EAAE,EAAE,MAAM,cAAc,CAAC;AAChG,OAAO,EAAW,KAAK,OAAO,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EAAkB,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,gFAAgF;AAChF,MAAM,MAAM,mBAAmB,GAC3B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC5B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAIrC;;;;;;;;;;;;;GAaG;AACH,wBAAsB,UAAU,CAC9B,EAAE,EAAE,EAAE,EACN,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,eAAe,GACrB,OAAO,CAAC,QAAQ,CAAC,CAsDnB;AAID;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,eAAe,GAAG,KAAK,CAW7D;AAID;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAC9B,EAAE,EAAE,EAAE,EACN,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,eAAe,EACtB,MAAM,EAAE,mBAAmB,EAC3B,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,QAAQ,CAAC,CAkCnB;AAID;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,YAAY,CAChC,EAAE,EAAE,EAAE,EACN,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,eAAe,EACtB,MAAM,EAAE,mBAAmB,GAC1B,OAAO,CAAC,QAAQ,CAAC,CA+FnB;AAID,wBAAsB,WAAW,CAC/B,EAAE,EAAE,EAAE,EACN,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,eAAe,EACtB,MAAM,EAAE,mBAAmB,EAC3B,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,QAAQ,CAAC,CAqBnB;AAED,6EAA6E;AAC7E,wBAAsB,cAAc,CAClC,EAAE,EAAE,EAAE,EACN,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,eAAe,EACtB,MAAM,EAAE,mBAAmB,EAC3B,WAAW,EAAE,MAAM,GAAG,SAAS,GAC9B,OAAO,CAAC,QAAQ,CAAC,CA0BnB;AAID;;;;;;;;GAQG;AACH,wBAAsB,UAAU,CAC9B,EAAE,EAAE,EAAE,EACN,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,eAAe,EACtB,MAAM,EAAE,mBAAmB,EAC3B,MAAM,EAAE,gBAAgB,GAAG,SAAS,GACnC,OAAO,CAAC,QAAQ,CAAC,CAgBnB;AAED;;;;;;GAMG;AACH,wBAAsB,SAAS,CAC7B,EAAE,EAAE,EAAE,EACN,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,eAAe,EACtB,MAAM,EAAE,mBAAmB,EAC3B,MAAM,EAAE,OAAO,GACd,OAAO,CAAC,QAAQ,CAAC,CAYnB;AAID;;;;;;;;;;;;;GAaG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,QAAQ,CAOlF;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,gBAAgB,CAe5E"}