@floh-solutions/pharos-cli 0.22.0 → 0.24.0

package/dist/output.js

@@ -1,4 +1,5 @@
 import { AdoAuthError, AdoConcurrencyError, AdoConfigError, AdoError, AdoNetworkError, AdoNotFoundError, AdoRateLimitError, adviceFor, deletionAdvice, namesAResourcePermission, } from "@floh-solutions/ado-core";
+import { GhUnavailableError, GitHubAccountError, GitHubAuthError, GitHubConfigError, GitHubError, GitHubIdentityMismatchError, GitHubNetworkError, GitHubNotFoundError, GitHubRateLimitError, GitHubValidationError, PullRequestNotAnIssueError, } from "@floh-solutions/gh-core";
 /**
  * The output contract.
  *
@@ -99,6 +100,20 @@ export function reportError(io, error) {
     io.stderr(JSON.stringify({ error: body }, undefined, 2));
     return code;
 }
+/**
+ * The same classification `reportError` uses, without emitting anything.
+ *
+ * For the one shape that needs it: a verb that has **already written one half of
+ * something** when the second half fails. `pharos issue adopt` creates the work
+ * item and then comments on the issue, so a failure at the second step must
+ * report the first step's result rather than only the error — otherwise the work
+ * item exists and nothing anywhere names it. Re-classifying by hand there would
+ * be a second, drifting copy of this table.
+ */
+export function failureOf(error) {
+    const { body, code } = describe(error);
+    return { kind: body["kind"] ?? "internal", code, body };
+}
 function describe(error) {
     if (error instanceof CliError) {
         return {
@@ -114,6 +129,9 @@ function describe(error) {
             code: error.exitCode,
         };
     }
+    const github = describeGitHub(error);
+    if (github !== undefined)
+        return github;
     if (error instanceof AdoConcurrencyError) {
         return {
             body: {
@@ -206,6 +224,159 @@ function describe(error) {
         code: EXIT_FAILED,
     };
 }
+/**
+ * The GitHub half of the same table, and the reason it is not optional.
+ *
+ * Without it every failure from `gh-core` falls through to `kind: "internal"`
+ * with exit 1 — so "this repository is not in repos.json" (fix the file, never
+ * retry), "`gh` is not installed" (fix the machine), and "you are over the
+ * hourly budget" (wait exactly this long and repeat) all arrive looking like one
+ * unexplained crash. Exit 1 additionally *invites* a retry, which is wrong for
+ * two of those three.
+ *
+ * Every body here carries `platform: "github"`, because on this bridge a verb
+ * touches two platforms in one invocation and "which side said no" is the first
+ * thing an agent needs. Its absence means Azure DevOps or this CLI, which is
+ * what it already meant.
+ *
+ * `undefined` when the error is not GitHub's, so the caller falls through.
+ */
+function describeGitHub(error) {
+    // A repo that is not in repos.json, an account `gh` has no token for, a
+    // missing `gh`: all configuration, all exit 2. Retrying is pure noise, and the
+    // messages `gh-core` raises already name the file or the command to run.
+    if (error instanceof GitHubConfigError) {
+        return { body: { kind: "config", platform: "github", message: error.message }, code: EXIT_USAGE };
+    }
+    if (error instanceof GitHubAccountError) {
+        return {
+            body: {
+                kind: "auth",
+                platform: "github",
+                message: error.message,
+                account: error.account,
+                hint: `gh holds no usable token for "${error.account}". Sign that account in with `
+                    + `\`gh auth login\`, or fix the binding with \`pharos setup --repo <owner/name> `
+                    + "--gh-account <login>`. `pharos doctor` reports both.",
+            },
+            code: EXIT_USAGE,
+        };
+    }
+    if (error instanceof GhUnavailableError) {
+        return {
+            body: {
+                kind: "config",
+                platform: "github",
+                message: error.message,
+                hint: "Install it with `pharos setup --install gh`, then `pharos doctor`.",
+            },
+            code: EXIT_USAGE,
+        };
+    }
+    // **A 200 from the wrong identity** — plan §2's whole reason for existing. Not
+    // a transport failure and not retryable: the configuration says one thing and
+    // the credential answered as somebody else.
+    if (error instanceof GitHubIdentityMismatchError) {
+        return {
+            body: {
+                kind: "config",
+                platform: "github",
+                message: error.message,
+                account: error.account,
+                expected: error.expected,
+                actual: error.actual,
+                hint: "The account this repository is bound to is not the one that answered. Check repos.json "
+                    + "and confirm with `pharos doctor --verify`.",
+            },
+            code: EXIT_USAGE,
+        };
+    }
+    if (error instanceof PullRequestNotAnIssueError) {
+        return {
+            body: {
+                kind: "usage",
+                platform: "github",
+                message: error.message,
+                repo: error.repo,
+                number: error.number,
+            },
+            code: EXIT_USAGE,
+        };
+    }
+    if (error instanceof GitHubRateLimitError) {
+        return {
+            body: {
+                kind: "rateLimit",
+                platform: "github",
+                message: error.message,
+                status: error.status,
+                retryAfterMs: error.retryAfterMs,
+                // A primary limit is the hourly 5,000 and can be most of an hour out; a
+                // secondary one is a burst and clears in seconds. Same advice, wildly
+                // different wait, so the caller is told which it is.
+                primary: error.primary,
+                requestId: error.requestId,
+                hint: "Wait retryAfterMs and repeat the identical call.",
+            },
+            code: EXIT_FAILED,
+        };
+    }
+    if (error instanceof GitHubAuthError) {
+        return { body: githubBody("auth", error), code: EXIT_USAGE };
+    }
+    if (error instanceof GitHubNotFoundError) {
+        return {
+            body: {
+                ...githubBody("notFound", error),
+                // GitHub answers 404 rather than 403 for a private repository you may
+                // not see — confirming it existed would be the leak. So "no such issue"
+                // and "wrong account" are one status code, and the account is the first
+                // thing to check rather than the last.
+                hint: "On GitHub a 404 is also how \"not visible to this account\" is spelled. Check the "
+                    + "binding with `pharos doctor --verify` before concluding the issue does not exist.",
+            },
+            code: EXIT_FAILED,
+        };
+    }
+    if (error instanceof GitHubValidationError) {
+        return {
+            // 422: understood and refused. Repeating it unchanged cannot work, which
+            // is exactly what exit 2 means here.
+            body: { ...githubBody("github", error), errors: error.errors },
+            code: EXIT_USAGE,
+        };
+    }
+    if (error instanceof GitHubError) {
+        return { body: githubBody("github", error), code: EXIT_FAILED };
+    }
+    if (error instanceof GitHubNetworkError) {
+        return {
+            body: {
+                kind: "network",
+                platform: "github",
+                message: error.message,
+                method: error.method,
+                url: error.url,
+            },
+            code: EXIT_FAILED,
+        };
+    }
+    return undefined;
+}
+function githubBody(kind, error) {
+    return {
+        kind,
+        platform: "github",
+        message: error.message,
+        status: error.status,
+        method: error.method,
+        url: error.url,
+        // GitHub's handle for a request, and the only one their support accepts —
+        // the same role `activityId` plays on the Azure DevOps side.
+        requestId: error.requestId,
+        ...(error.documentationUrl === undefined ? {} : { documentationUrl: error.documentationUrl }),
+    };
+}
 /**
  * An Azure DevOps failure, with **what to do about it** where that is known.
  *

package/dist/output.js.map

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

package/dist/session.d.ts

@@ -1,5 +1,7 @@
 import { AdoClient, WikiApi } from "@floh-solutions/ado-core";
+import type { GitHubClient } from "@floh-solutions/gh-core";
 import { WriteBudget } from "./budget.js";
+import { HalfLinkJournal } from "./half-link.js";
 import { type ExitCode, type Io } from "./output.js";
 /**
  * One invocation's world: the client, the budget it spends against, the wiki it
@@ -19,6 +21,8 @@ export interface SessionOptions {
     pretty: boolean;
     /** Injected by tests; production passes nothing and gets a real client. */
     client?: AdoClient | undefined;
+    /** Injected by tests; production passes nothing and gets one from `repos.json`. */
+    github?: GitHubClient | undefined;
 }
 export declare class Session {
     #private;
@@ -28,7 +32,53 @@ export declare class Session {
     readonly apply: boolean;
     readonly previewOnly: boolean;
     readonly pretty: boolean;
+    /**
+     * 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.
+     */
+    readonly halfLinks: HalfLinkJournal;
     constructor(options: SessionOptions);
+    /**
+     * 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.
+     */
+    github(): Promise<GitHubClient>;
+    /**
+     * 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: {
+        id: number;
+        _links?: Record<string, unknown>;
+    }): string;
     /**
      * The wiki to act on, resolved once.
      *

package/dist/session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,OAAO,EAAgB,MAAM,0BAA0B,CAAC;AAE5E,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAsC,KAAK,QAAQ,EAAE,KAAK,EAAE,EAAE,MAAM,aAAa,CAAC;AAEzF;;;GAGG;AAEH,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,sEAAsE;IACtE,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,MAAM,EAAE,WAAW,CAAC;IACpB,kDAAkD;IAClD,KAAK,EAAE,OAAO,CAAC;IACf,gFAAgF;IAChF,WAAW,EAAE,OAAO,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;CAChC;AAED,qBAAa,OAAO;;IAClB,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;gBAKb,OAAO,EAAE,cAAc;IAkBnC;;;;;;;;;OASG;IACG,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;IAIvC,wEAAwE;IAClE,cAAc,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CAiDrF;AAED,2EAA2E;AAC3E,MAAM,WAAW,iBAAiB;IAChC,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,mFAAmF;IACnF,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,iBAAiB,GAAG,QAAQ,GAAG,SAAS,CAYjG"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,OAAO,EAAgB,MAAM,0BAA0B,CAAC;AAC5E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAE5D,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAsC,KAAK,QAAQ,EAAE,KAAK,EAAE,EAAE,MAAM,aAAa,CAAC;AAEzF;;;GAGG;AAEH,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,sEAAsE;IACtE,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,MAAM,EAAE,WAAW,CAAC;IACpB,kDAAkD;IAClD,KAAK,EAAE,OAAO,CAAC;IACf,gFAAgF;IAChF,WAAW,EAAE,OAAO,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAC/B,mFAAmF;IACnF,MAAM,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;CACnC;AAED,qBAAa,OAAO;;IAClB,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;gBAOxB,OAAO,EAAE,cAAc;IAqBnC;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC;IAerC;;;;;;;;;OASG;IACH,WAAW,CAAC,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,MAAM;IAQ3E;;;;;;;;;OASG;IACG,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;IAIvC,wEAAwE;IAClE,cAAc,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CAiDrF;AAED,2EAA2E;AAC3E,MAAM,WAAW,iBAAiB;IAChC,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,mFAAmF;IACnF,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,iBAAiB,GAAG,QAAQ,GAAG,SAAS,CAYjG"}

package/dist/session.js

@@ -1,5 +1,6 @@
 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;
@@ -8,14 +9,27 @@ export class Session {
     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;
     #wikiHint;
     #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.#wikiHint = options.wiki;
+        this.#github = options.github;
+        this.halfLinks = new HalfLinkJournal(options.env);
         this.client =
             options.client
                 ?? AdoClient.fromEnv(options.env, {
@@ -26,6 +40,62 @@ export class Session {
                 });
         this.wiki = new WikiApi(this.client.http);
     }
+    /**
+     * 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.
      *

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floh-solutions/pharos-cli",
-  "version": "0.22.0",
+  "version": "0.24.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",
@@ -24,8 +24,9 @@
     "node": ">=22"
   },
   "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.1.0",
+    "@floh-solutions/ado-core": "0.9.1"
   },
   "devDependencies": {
     "@types/node": "^22.10.2",