@floh-solutions/pharos-cli 0.23.0 → 0.25.0

package/dist/session.js

@@ -1,30 +1,132 @@
 import { AdoClient, WikiApi } from "@floh-solutions/ado-core";
 import { WriteBudget } from "./budget.js";
+import { HalfLinkJournal } from "./half-link.js";
 import { EXIT_OK, emit, refusal, usageError } from "./output.js";
 export class Session {
-    client;
-    wiki;
     budget;
     apply;
     previewOnly;
     pretty;
+    /**
+     * Adoptions this machine started and did not finish — see `half-link.ts`.
+     *
+     * Built from the invocation's environment rather than reached for inside the
+     * command, so a run whose env names no `HOME` has no journal instead of
+     * quietly writing into whichever home directory the process happens to have.
+     */
+    halfLinks;
+    #env;
+    #organization;
+    #project;
     #wikiHint;
+    #client;
+    #wikiApi;
     #resolvedWiki;
+    #github;
     constructor(options) {
         this.budget = options.budget;
         this.apply = options.apply;
         this.previewOnly = options.previewOnly;
         this.pretty = options.pretty;
+        this.#env = options.env;
+        this.#organization = options.organization;
+        this.#project = options.project;
         this.#wikiHint = options.wiki;
-        this.client =
-            options.client
-                ?? AdoClient.fromEnv(options.env, {
-                    ...(options.organization === undefined ? {} : { organization: options.organization }),
-                    ...(options.project === undefined ? {} : { project: options.project }),
-                    // Every write goes through here, whoever issued it.
-                    fetch: options.budget.wrap((input, init) => globalThis.fetch(input, init)),
-                });
-        this.wiki = new WikiApi(this.client.http);
+        this.#client = options.client;
+        this.#github = options.github;
+        this.halfLinks = new HalfLinkJournal(options.env);
+    }
+    /**
+     * The Azure DevOps client — **resolved on first use, not in the constructor.**
+     *
+     * It was built eagerly, and that made `ADO_PAT` the price of entry to the
+     * whole CLI: `pharos comment list contoso/widgets#45` reads a GitHub issue
+     * through `gh-core` with the `gh` credential and never touches Azure DevOps,
+     * and it answered `{"kind":"config","message":"ADO_PAT is not set…"}` (#839).
+     * Somebody with `gh` signed in and no Azure DevOps PAT — a state
+     * `pharos doctor` reports as fine, and which the separate Keychain entries
+     * exist to make possible — could not use a single GitHub verb.
+     *
+     * {@link github} was made lazy for exactly this reason (#782) and this half
+     * was not. The fix belongs here rather than in the `comment` dispatch: any
+     * verb family that grows a GitHub target inherits it, and a special case in
+     * one command is a special case the next one has to remember.
+     *
+     * **Resolution failure is deferred, never softened.** The `AdoConfigError`
+     * still names the missing variable and still exits 2 — it arrives when
+     * something actually needs Azure DevOps, which is where it is an answer
+     * rather than an obstacle. See {@link approve} for the one place that
+     * ordering has to be forced.
+     */
+    get client() {
+        this.#client ??= AdoClient.fromEnv(this.#env, {
+            ...(this.#organization === undefined ? {} : { organization: this.#organization }),
+            ...(this.#project === undefined ? {} : { project: this.#project }),
+            // Every write goes through here, whoever issued it.
+            fetch: this.budget.wrap((input, init) => globalThis.fetch(input, init)),
+        });
+        return this.#client;
+    }
+    /** The wiki API, over {@link client}'s transport — and lazy for its sake. */
+    get wiki() {
+        this.#wikiApi ??= new WikiApi(this.client.http);
+        return this.#wikiApi;
+    }
+    /**
+     * The GitHub client, resolved once, from `~/.config/pharos/repos.json`.
+     *
+     * Three things about this are deliberate.
+     *
+     * **Its fetch is wrapped by the same {@link WriteBudget} the Azure DevOps
+     * client uses.** `--max-writes 0` promises that an invocation cannot change
+     * anything, and that promise is worthless if it covers one platform of a
+     * two-platform verb: `pharos issue adopt` posts a comment on GitHub, and a cap
+     * that let that through would be a cap in name only. `gh-core`'s transport
+     * already recognises a refusal thrown by a fetch wrapper and rethrows it
+     * unretried rather than reporting it as a dead socket.
+     *
+     * **It is loaded lazily, and imported dynamically.** Twenty-seven of the
+     * twenty-eight verbs here never touch GitHub, and `gh-core` reaches for
+     * `node:child_process` at import time to talk to `gh`. `doctor` does the same
+     * thing for the same reason.
+     *
+     * **There is no repository default.** `GitHubClient` has no current repo and
+     * no current account by construction (plan §2) — every call names both, and an
+     * unbound repository is an error naming `repos.json` rather than a guess at
+     * whichever `gh` account happens to be active.
+     */
+    async github() {
+        if (this.#github !== undefined)
+            return this.#github;
+        const { GhTokenSource, GitHubClient } = await import("@floh-solutions/gh-core");
+        this.#github = await GitHubClient.fromConfig({
+            env: this.#env,
+            // The invocation's environment, not `process.env` — `gh` is spawned with
+            // it (`GhTokenSource` scrubs the ambient GH_TOKEN out on the way), and the
+            // PATH it is found on is the PATH this run was given. Same reason `doctor`
+            // hands it the path it resolved.
+            tokens: new GhTokenSource({ env: this.#env }),
+            fetch: this.budget.wrap((input, init) => globalThis.fetch(input, init)),
+        });
+        return this.#github;
+    }
+    /**
+     * The web address of a work item — what a person clicks, not what the API
+     * reads.
+     *
+     * `WorkItem.url` is the REST url and opening it in a browser gives JSON, so a
+     * comment on a public GitHub issue carrying it would be worse than carrying
+     * nothing. `_links.html.href` is what Azure DevOps itself calls the human
+     * address; it is only present when the read asked for links, so the composed
+     * form is the fallback rather than the other way round.
+     */
+    workItemUrl(item) {
+        const html = item._links?.["html"]?.href;
+        if (typeof html === "string" && html !== "")
+            return html;
+        const organization = encodeURIComponent(this.client.organization);
+        const project = encodeURIComponent(this.client.project ?? "");
+        return `${this.client.http.baseUrl}/${organization}/${project}/_workitems/edit/${item.id}`;
     }
     /**
      * The wiki to act on, resolved once.
@@ -96,9 +198,28 @@ export class Session {
  * is how a half-finished job gets reported as done (`docs/pharos-cli-plan.md`
  * §2.5). `--dry-run` exits 0 because there the preview IS the deliverable.
  *
+ * ## The credential is checked before the gate, and that ordering is the point
+ *
+ * {@link Session.client} resolves on first use (#839), and every arm below
+ * runs *before* the verb touches it. So on a machine with no `ADO_PAT`,
+ * `pharos comment delete 210 5` would answer "Refusing to delete comment 5 on
+ * #210 without --yes" — a refusal that invites a retry with `--yes` which then
+ * fails on the credential anyway. Two refusals, the useful one second.
+ *
+ * Touching the client here puts the credential failure back in front, exactly
+ * where it was when the client was eager. A `--dry-run` preview of an Azure
+ * DevOps write is refused for the same reason: a preview of something this
+ * machine cannot do is a preview of nothing.
+ *
+ * A GitHub action says so and is exempt — that is the whole bug this ordering
+ * has to avoid recreating.
+ *
  * @returns `undefined` to proceed with the write, or the exit code to return.
  */
 export function approve(io, session, action) {
+    // Raises `AdoConfigError` naming the missing variable, or does nothing.
+    if (action.platform !== "github")
+        void session.client;
     if (session.previewOnly) {
         emit(io, { applied: false, dryRun: true, ...action.would });
         return EXIT_OK;

package/dist/session.js.map

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

package/dist/target.d.ts

@@ -1,9 +1,11 @@
+import { type IssueCoordinate } from "@floh-solutions/gh-core";
 /**
- * What a comment verb is addressing: a work item, or a wiki page.
+ * What a comment verb is addressing: a work item, a wiki page, or a GitHub
+ * issue.
  *
- * The two comment surfaces are different APIs with different quirks, but from
- * where an agent stands they are one idea — "the discussion about this thing" —
- * so `pharos comment` takes either and the target says which.
+ * Three comment surfaces, three APIs with different quirks, but from where an
+ * agent stands they are one idea — "the discussion about this thing" — so
+ * `pharos comment` takes any of them and the target says which.
  *
  * **The rule is that a wiki page is an absolute path, and that is not a
  * convention invented here.** The Azure DevOps wiki API answers 404 for a page
@@ -12,6 +14,20 @@
  * spelling that disambiguates is also the only spelling that works, and a
  * target that omits it is rejected with the reason rather than quietly fixed —
  * somebody passing `Plans/Foo` has a bug somewhere upstream worth finding.
+ *
+ * **A GitHub issue is `owner/name#45`** — the form plan §8 already chose for
+ * `pharos issue`, so one spelling addresses an issue everywhere in this CLI.
+ * The three grammars cannot collide: a work item is all digits, a wiki page
+ * opens with `/`, and a repository name may contain neither a `#` nor a second
+ * `/`. `gh-core` owns the parse (it also accepts `owner/name/45` and a full
+ * issue URL, because all three get pasted), so there is no second grammar here.
+ *
+ * **A GitHub target carries no account, deliberately.** The account is resolved
+ * from `repos.json` at the point of use — plan §2's whole finding is that
+ * letting anything else decide returns a cheerful 200 from the wrong
+ * repository. A `Target` is what the caller *said*; the binding is what this
+ * machine is configured to do about it, and conflating them is how the wrong
+ * one gets used.
  */
 export type Target = {
     kind: "workItem";
@@ -19,7 +35,27 @@ export type Target = {
 } | {
     kind: "wikiPage";
     path: string;
+} | {
+    kind: "githubIssue";
+    issue: IssueCoordinate;
 };
+/**
+ * The two Azure DevOps surfaces, as their own type.
+ *
+ * Named rather than left implicit because the arms that handle them are written
+ * as "work item, else wiki page" — which was total when there were two kinds
+ * and silently stopped being when GitHub arrived. Taking this type makes the
+ * compiler carry that guarantee instead of a reader having to.
+ */
+export type AdoTarget = Extract<Target, {
+    kind: "workItem";
+} | {
+    kind: "wikiPage";
+}>;
+/** A GitHub issue target, for the arms that only accept one. */
+export type GitHubTarget = Extract<Target, {
+    kind: "githubIssue";
+}>;
 export declare function parseTarget(raw: string): Target;
 export declare function describeTarget(target: Target): string;
 //# sourceMappingURL=target.d.ts.map

package/dist/target.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"target.d.ts","sourceRoot":"","sources":["../src/target.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,MAAM,GACd;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvC,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAsB/C;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAErD"}
+{"version":3,"file":"target.d.ts","sourceRoot":"","sources":["../src/target.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwB,KAAK,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAIrF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,MAAM,MAAM,GACd;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,eAAe,CAAA;CAAE,CAAC;AAEpD;;;;;;;GAOG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,CAAC,CAAC;AAErF,gEAAgE;AAChE,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC,CAAC;AAEpE,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAyB/C;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CASrD"}

package/dist/target.js

@@ -1,3 +1,4 @@
+import { parseIssueCoordinate } from "@floh-solutions/gh-core";
 import { usageError } from "./output.js";
 export function parseTarget(raw) {
     const value = raw.trim();
@@ -13,11 +14,21 @@ export function parseTarget(raw) {
         }
         return { kind: "wikiPage", path: value };
     }
+    const issue = parseIssueCoordinate(value);
+    if (issue !== undefined)
+        return { kind: "githubIssue", issue };
     throw usageError(`Cannot tell what "${raw}" is. A work item is its number (210); a wiki page is an absolute `
-        + `path (/Plans/Foo). The leading slash is required by the wiki API itself, not by this tool `
-        + `— it answers 404 without one.`, { target: raw });
+        + `path (/Plans/Foo); a GitHub issue is owner/name#45. The leading slash on a wiki page is `
+        + `required by the wiki API itself, not by this tool — it answers 404 without one.`, { target: raw });
 }
 export function describeTarget(target) {
-    return target.kind === "workItem" ? `#${target.id}` : target.path;
+    switch (target.kind) {
+        case "workItem":
+            return `#${target.id}`;
+        case "wikiPage":
+            return target.path;
+        case "githubIssue":
+            return `${target.issue.repo}#${target.issue.number}`;
+    }
 }
 //# sourceMappingURL=target.js.map

package/dist/target.js.map

@@ -1 +1 @@
-{"version":3,"file":"target.js","sourceRoot":"","sources":["../src/target.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAqBzC,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAEzB,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QACzB,IAAI,EAAE,IAAI,CAAC;YAAE,MAAM,UAAU,CAAC,IAAI,GAAG,0BAA0B,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;QAClF,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC;IAClC,CAAC;IAED,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1B,IAAI,KAAK,KAAK,GAAG,EAAE,CAAC;YAClB,MAAM,UAAU,CAAC,8CAA8C,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;QACpF,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IAC3C,CAAC;IAED,MAAM,UAAU,CACd,qBAAqB,GAAG,oEAAoE;UACxF,4FAA4F;UAC5F,+BAA+B,EACnC,EAAE,MAAM,EAAE,GAAG,EAAE,CAChB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,MAAc;IAC3C,OAAO,MAAM,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC;AACpE,CAAC"}
+{"version":3,"file":"target.js","sourceRoot":"","sources":["../src/target.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAwB,MAAM,yBAAyB,CAAC;AAErF,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAkDzC,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAEzB,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QACzB,IAAI,EAAE,IAAI,CAAC;YAAE,MAAM,UAAU,CAAC,IAAI,GAAG,0BAA0B,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;QAClF,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC;IAClC,CAAC;IAED,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1B,IAAI,KAAK,KAAK,GAAG,EAAE,CAAC;YAClB,MAAM,UAAU,CAAC,8CAA8C,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;QACpF,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IAC3C,CAAC;IAED,MAAM,KAAK,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;IAC1C,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC;IAE/D,MAAM,UAAU,CACd,qBAAqB,GAAG,oEAAoE;UACxF,0FAA0F;UAC1F,iFAAiF,EACrF,EAAE,MAAM,EAAE,GAAG,EAAE,CAChB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,MAAc;IAC3C,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,UAAU;YACb,OAAO,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;QACzB,KAAK,UAAU;YACb,OAAO,MAAM,CAAC,IAAI,CAAC;QACrB,KAAK,aAAa;YAChB,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;IACzD,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floh-solutions/pharos-cli",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "Azure DevOps from a headless shell, for an agent: the whole context of a task in one call, and the wiki/comment verbs Microsoft's MCP server does not ship.",
   "license": "UNLICENSED",
   "author": "FLOH Solutions",
@@ -25,7 +25,8 @@
   },
   "dependencies": {
     "@floh-solutions/ado-core": "0.9.1",
-    "@floh-solutions/plan-to-board": "0.1.1"
+    "@floh-solutions/plan-to-board": "0.1.1",
+    "@floh-solutions/gh-core": "0.2.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.2",