@floh-solutions/pharos-cli 0.29.0 → 0.31.0

package/dist/delegate/vsix.js

@@ -0,0 +1,329 @@
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { readdir, readFile, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { inflateRawSync } from "node:zlib";
+import { bundleCli, findApp, HOSTS } from "./hosts.js";
+const run = promisify(execFile);
+/**
+ * The Pharos bridge for VS Code — what this CLI ships, and what a machine has.
+ *
+ * ## Why the CLI carries a `.vsix` at all
+ *
+ * Nothing outside VS Code can put a prompt into a session (measured against
+ * the Claude Code and Codex extensions: no URI handler takes text, and the
+ * `code` CLI runs no terminal command). The bridge — `packages/pharos-vscode`,
+ * publisher `floh-solutions`, name `pharos` — is the thing that can, and it
+ * ships INSIDE the npm package the way `skill/` does, so `pharos setup
+ * --install vscode-bridge` needs no network and no Marketplace listing. A
+ * listing is a later, separate decision and a fourth release route.
+ *
+ * ## Two files, one source of truth
+ *
+ * The bridge's build writes `vscode/pharos-bridge.vsix` and, beside it,
+ * `vscode/pharos-bridge.json` — `{ id, version, vsix, sha256, bytes }`,
+ * derived from the extension's own `package.json`. The JSON is what `doctor`
+ * reads to say which bridge this CLI ships, and the sha256 in it is what the
+ * installer checks the `.vsix` against before handing it to VS Code: the
+ * `convert.ts` rule, that bytes are verified against something already in the
+ * package rather than trusted because they are there. When the JSON is absent
+ * the `.vsix` is unzipped for its `extension/package.json` instead, so an
+ * older build still reports a version.
+ */
+export const BRIDGE_EXTENSION_ID = "floh-solutions.pharos";
+/** `anthropic.claude-code` and `openai.chatgpt` — the ids the extension folders and manifest carry. */
+export const CLAUDE_EXTENSION_ID = "anthropic.claude-code";
+export const CODEX_EXTENSION_ID = "openai.chatgpt";
+/**
+ * Where the bundled `.vsix` is.
+ *
+ * `PHAROS_BRIDGE_VSIX` overrides it — for a developer installing a local
+ * build, and for the tests, which must never install a real extension into
+ * somebody's editor to prove a refusal.
+ */
+export function bundledVsixPath(env = process.env) {
+    const override = env["PHAROS_BRIDGE_VSIX"];
+    if (override !== undefined && override !== "")
+        return override;
+    // Relative to the compiled file, so it resolves from dist/ in a global npm
+    // install as well as from src/ in this checkout — the `skill/` rule.
+    return fileURLToPath(new URL("../../vscode/pharos-bridge.vsix", import.meta.url));
+}
+/** The manifest the bridge's build writes beside the `.vsix`. */
+export function bundledManifestPath(env = process.env) {
+    return join(dirname(bundledVsixPath(env)), "pharos-bridge.json");
+}
+/** The bridge this CLI ships, or null when the `.vsix` is not there. Never throws. */
+export async function bundledBridge(env = process.env) {
+    const path = bundledVsixPath(env);
+    let bytes;
+    try {
+        const info = await stat(path);
+        if (!info.isFile())
+            return null;
+        bytes = await readFile(path);
+    }
+    catch {
+        return null;
+    }
+    try {
+        const raw = await readFile(bundledManifestPath(env), "utf8");
+        const parsed = JSON.parse(raw);
+        const id = typeof parsed["id"] === "string" ? parsed["id"] : null;
+        const dot = id?.indexOf(".") ?? -1;
+        return {
+            path,
+            bytes: bytes.length,
+            manifest: {
+                publisher: id !== null && dot > 0 ? id.slice(0, dot) : null,
+                name: id !== null && dot > 0 ? id.slice(dot + 1) : null,
+                version: typeof parsed["version"] === "string" ? parsed["version"] : null,
+            },
+            sha256: typeof parsed["sha256"] === "string" ? parsed["sha256"].toLowerCase() : null,
+            via: "manifest",
+        };
+    }
+    catch {
+        return { path, bytes: bytes.length, manifest: vsixManifest(bytes), sha256: null, via: "vsix" };
+    }
+}
+/**
+ * `extension/package.json` out of a `.vsix`, which is a zip.
+ *
+ * A zip reader in forty lines rather than a dependency: the package has none
+ * today, and one to read three fields out of a file we produce ourselves
+ * would be a poor trade. Handles the two methods `vsce` writes (stored and
+ * deflate) and nothing else; zip64 is not needed for a bridge this size.
+ */
+export function vsixManifest(bytes) {
+    const empty = { publisher: null, name: null, version: null };
+    const entry = zipEntry(bytes, "extension/package.json");
+    if (entry === null)
+        return empty;
+    try {
+        const parsed = JSON.parse(entry.toString("utf8"));
+        return {
+            publisher: typeof parsed["publisher"] === "string" ? parsed["publisher"] : null,
+            name: typeof parsed["name"] === "string" ? parsed["name"] : null,
+            version: typeof parsed["version"] === "string" ? parsed["version"] : null,
+        };
+    }
+    catch {
+        return empty;
+    }
+}
+const EOCD = 0x06054b50;
+const CENTRAL = 0x02014b50;
+const LOCAL = 0x04034b50;
+/** One file's contents out of a zip, by exact name, or null. */
+export function zipEntry(bytes, name) {
+    // The end-of-central-directory record is at the very end, before an optional
+    // comment of at most 65535 bytes. Scan back for its signature.
+    let eocd = -1;
+    for (let at = bytes.length - 22; at >= Math.max(0, bytes.length - 22 - 65_535); at -= 1) {
+        if (bytes.readUInt32LE(at) === EOCD) {
+            eocd = at;
+            break;
+        }
+    }
+    if (eocd === -1)
+        return null;
+    const entries = bytes.readUInt16LE(eocd + 10);
+    let at = bytes.readUInt32LE(eocd + 16);
+    for (let index = 0; index < entries; index += 1) {
+        if (at + 46 > bytes.length || bytes.readUInt32LE(at) !== CENTRAL)
+            return null;
+        const method = bytes.readUInt16LE(at + 10);
+        const compressedSize = bytes.readUInt32LE(at + 20);
+        const nameLength = bytes.readUInt16LE(at + 28);
+        const extraLength = bytes.readUInt16LE(at + 30);
+        const commentLength = bytes.readUInt16LE(at + 32);
+        const localOffset = bytes.readUInt32LE(at + 42);
+        const entryName = bytes.subarray(at + 46, at + 46 + nameLength).toString("utf8");
+        if (entryName === name) {
+            if (localOffset + 30 > bytes.length || bytes.readUInt32LE(localOffset) !== LOCAL)
+                return null;
+            const localNameLength = bytes.readUInt16LE(localOffset + 26);
+            const localExtraLength = bytes.readUInt16LE(localOffset + 28);
+            const start = localOffset + 30 + localNameLength + localExtraLength;
+            const data = bytes.subarray(start, start + compressedSize);
+            if (method === 0)
+                return Buffer.from(data);
+            if (method === 8) {
+                try {
+                    return inflateRawSync(data);
+                }
+                catch {
+                    return null;
+                }
+            }
+            return null;
+        }
+        at += 46 + nameLength + extraLength + commentLength;
+    }
+    return null;
+}
+/** `~/.vscode[-insiders]/extensions` for a VS Code flavour; null for any other host. */
+export function extensionsDirectory(host, env = process.env) {
+    const spec = HOSTS[host].vscode;
+    if (spec === undefined)
+        return null;
+    return join(env["HOME"] ?? homedir(), spec.extensionsDir);
+}
+/**
+ * What a flavour has installed. `null` when the directory does not exist —
+ * which is "this VS Code has never run", a different fact from "no extensions".
+ *
+ * `extensions.json` is read first because it is what VS Code itself reads:
+ * the reference machine held two `anthropic.claude-code-*` folders side by
+ * side (an update leaves the old one behind), and only the manifest says which
+ * is live. A missing or unreadable manifest falls back to the folder names,
+ * `<publisher>.<name>-<version>[-<platform>]`.
+ */
+export async function installedExtensions(host, env = process.env) {
+    const directory = extensionsDirectory(host, env);
+    if (directory === null)
+        return null;
+    let names;
+    try {
+        names = await readdir(directory);
+    }
+    catch {
+        return null;
+    }
+    try {
+        const raw = await readFile(join(directory, "extensions.json"), "utf8");
+        const parsed = JSON.parse(raw);
+        if (Array.isArray(parsed)) {
+            const listed = [];
+            for (const entry of parsed) {
+                const record = entry;
+                const id = record.identifier?.id;
+                if (typeof id !== "string" || typeof record.version !== "string")
+                    continue;
+                const folder = typeof record.relativeLocation === "string" ? record.relativeLocation : `${id}-${record.version}`;
+                listed.push({ id: id.toLowerCase(), version: record.version, path: join(directory, folder) });
+            }
+            return listed;
+        }
+    }
+    catch {
+        // No manifest, or not the shape expected. The folders still say.
+    }
+    const scanned = [];
+    for (const name of names) {
+        const parsed = parseExtensionFolder(name);
+        if (parsed !== null)
+            scanned.push({ ...parsed, path: join(directory, name) });
+    }
+    return scanned;
+}
+/** `anthropic.claude-code-2.1.228-darwin-arm64` → id and version. Null for anything else. */
+export function parseExtensionFolder(name) {
+    const match = /^([a-z0-9][a-z0-9-]*\.[a-z0-9][a-z0-9-]*)-(\d+\.\d+\.\d+(?:[-.][0-9A-Za-z.-]+)?)$/i.exec(name);
+    if (match === null)
+        return null;
+    let version = match[2];
+    // A platform suffix is not part of the version: strip `-darwin-arm64` and its kin.
+    version = version.replace(/-(darwin|linux|win32|alpine|web|universal)[-0-9A-Za-z]*$/i, "");
+    return { id: match[1].toLowerCase(), version };
+}
+/**
+ * Install the bundled bridge into every VS Code flavour on this machine.
+ *
+ * Through the bundle's OWN `bin/code`, because the `code` command is usually
+ * not on PATH (see {@link bundleCli}). `--force` replaces an older bridge
+ * without a prompt; a headless install that stops to ask is a wizard that
+ * hangs.
+ *
+ * A missing `.vsix` is a refusal with the path, never a stack trace: the
+ * package can legitimately ship without one until the bridge's build has
+ * written it, and `doctor` names that state too. A `.vsix` that does not
+ * match its manifest's checksum is refused the same way — nothing is handed
+ * to VS Code that the package did not vouch for.
+ */
+export async function installBridge(options = {}) {
+    const env = options.env ?? process.env;
+    const bundled = await bundledBridge(env);
+    if (bundled === null) {
+        return {
+            ok: false,
+            command: null,
+            detail: `This pharos ships no bridge — ${bundledVsixPath(env)} is absent. It is produced by the `
+                + "bridge's build (packages/pharos-vscode) and packed into the npm package; a checkout "
+                + "gets it from `pnpm --filter ./packages/pharos-vscode build`, or point "
+                + "PHAROS_BRIDGE_VSIX at one.",
+            flavours: [],
+        };
+    }
+    if (bundled.sha256 !== null) {
+        const digest = createHash("sha256").update(await readFile(bundled.path)).digest("hex");
+        if (digest !== bundled.sha256) {
+            return {
+                ok: false,
+                command: null,
+                detail: `${bundled.path} does not match the checksum in ${bundledManifestPath(env)} — got ${digest}, `
+                    + `expected ${bundled.sha256}. Nothing was installed: the two files were written by `
+                    + "different builds, or one was replaced by hand. Rebuild the bridge so both come from "
+                    + "one build.",
+                flavours: [],
+            };
+        }
+    }
+    const flavours = [];
+    let lastCommand = null;
+    for (const host of ["vscode", "vscode-insiders"]) {
+        const app = await findApp(host, env);
+        if (app === null)
+            continue;
+        const cli = bundleCli(app.path);
+        const args = ["--install-extension", bundled.path, "--force"];
+        const command = `${quoteForDisplay(cli)} ${args.map(quoteForDisplay).join(" ")}`;
+        lastCommand = command;
+        options.onCommand?.(command);
+        try {
+            await run(cli, args, { timeout: 5 * 60_000, maxBuffer: 4 * 1024 * 1024, env });
+            flavours.push({
+                host,
+                ok: true,
+                detail: `Installed ${bundled.manifest.version ?? "the bundled bridge"} into ${HOSTS[host].name}.`,
+            });
+        }
+        catch (error) {
+            flavours.push({
+                host,
+                ok: false,
+                detail: `That command failed: ${error instanceof Error ? error.message : String(error)}`,
+            });
+        }
+    }
+    if (flavours.length === 0) {
+        return {
+            ok: false,
+            command: null,
+            detail: "Neither Visual Studio Code nor Visual Studio Code - Insiders is installed — looked up by "
+                + `bundle id (${HOSTS.vscode.bundleId}, ${HOSTS["vscode-insiders"].bundleId}) through `
+                + "Spotlight and at the usual paths under /Applications and ~/Applications. "
+                + "Install one and run this again.",
+            flavours,
+        };
+    }
+    const ok = flavours.every((flavour) => flavour.ok);
+    return {
+        ok,
+        command: lastCommand,
+        detail: flavours.map((flavour) => `${HOSTS[flavour.host].name}: ${flavour.detail}`).join(" ")
+            + (ok
+                ? " VS Code asks once whether the extension may handle a pharos URI — that is the "
+                    + "trust prompt, not a fault."
+                : ""),
+        flavours,
+    };
+}
+function quoteForDisplay(value) {
+    return /[\s'"$`\\]/.test(value) ? `'${value.replace(/'/g, `'\\''`)}'` : value;
+}
+//# sourceMappingURL=vsix.js.map

package/dist/delegate/vsix.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floh-solutions/pharos-cli",
-  "version": "0.29.0",
+  "version": "0.31.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",
@@ -18,15 +18,16 @@
   },
   "files": [
     "dist",
-    "skill"
+    "skill",
+    "vscode"
   ],
   "engines": {
     "node": ">=22"
   },
   "dependencies": {
     "@floh-solutions/ado-core": "0.11.0",
-    "@floh-solutions/plan-to-board": "0.2.0",
-    "@floh-solutions/gh-core": "0.4.0"
+    "@floh-solutions/gh-core": "0.4.0",
+    "@floh-solutions/plan-to-board": "0.2.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.2",

package/skill/SKILL.md

@@ -119,6 +119,16 @@ bridge map|unmap|digest        edit that mapping (--label is an ID, not a name
                                written back to the work item
 doctor                         what is installed on THIS machine, what is
                                missing, and what each missing thing costs
+delegate                       hand a prompt to a coding agent in Terminal or
+                               VS Code — Pharos.app's verb, not usually yours.
+                               You are on the RECEIVING end: see "When a
+                               prompt begins Fetch Azure DevOps work item".
+                               `--list` names the sessions already on a folder
+                               (id, name, status, host; `recommended` on the
+                               one a plain delegate takes) and `--session <id>`
+                               picks one of them — or `--session new` for a
+                               fresh one. A pick that has gone answers
+                               `session-gone` and starts nothing
 ```
 
 Text input: `--text` / `--file` / `--stdin`. Global: `--pretty` for a human,
@@ -1303,6 +1313,43 @@ no Azure DevOps account, which is every reporter.
 anything you do is recorded against whoever owns `ADO_PAT`. Never suggest
 sharing one.
 
+## When a prompt begins "Fetch Azure DevOps work item #N with the pharos skill"
+
+That is a **delegation from Pharos**, the macOS board app. Somebody right-
+clicked a work item and chose *Ask Agent*; the app found or started this
+session in the folder linked to that project and typed the prompt in. Only the
+**id** was sent — no title, no URL, no description — on purpose: you fetch the
+item yourself, with the CLI already configured for the right organisation, so
+what you read is what is on the board now rather than a copy the app might
+have got wrong.
+
+So the first move is the usual one, and it is the whole context in one call:
+
+```bash
+pharos task <id>            # description, discussion, attachments, relations, linked pages
+pharos download <id> --all --out ./attachments   # then READ them — images too
+```
+
+Read everything it returns, including the discussion and every attachment and
+image (the section on reading attachments above says how, and `pharos doctor`
+says what this machine can open). Then, **which of the two prompts you got
+decides what happens next**:
+
+- It ends with *"so we can then discuss the task"* — the person wants to talk
+  first. Summarise what the item asks for, what is specified and what is not,
+  and what you would do; then **wait**.
+- It carries instructions after the fetch sentence — the person has already
+  decided. Take the item on as instructed, without asking whether to start.
+
+Either way the reply loop is the board's, not the chat's, because the person
+who delegated is watching the work item in Pharos rather than this pane:
+
+```bash
+pharos update <id> --state Doing          # the moment work starts (`pharos types` for the names)
+pharos comment add <id> --file notes.md   # questions, findings, decisions — on the item
+pharos task <id>                          # re-read before acting on an answer
+```
+
 ## When it is not set up
 
 `"kind": "config"` on exit 2 means the environment is missing. Run `pharos

package/vscode/README.md

@@ -0,0 +1,30 @@
+# The Pharos bridge for VS Code, as shipped by the CLI
+
+Two files land here, and neither is committed:
+
+| file | what |
+|---|---|
+| `pharos-bridge.vsix` | the extension `floh-solutions.pharos`, built from `packages/pharos-vscode` |
+| `pharos-bridge.json` | `{ id, version, vsix, sha256, bytes, engines }`, derived from that package's `package.json` by the same build |
+
+```bash
+pnpm --filter ./packages/pharos-vscode build     # from the repo root; writes both files here
+```
+
+They ship inside the npm package because `files` in `package.json` names
+`vscode/` — npm packs a gitignored path when `files` names it — and
+`scripts/prepack.mjs` refuses to pack when either is missing, so the CLI can
+never go out bridge-less by accident.
+
+The CLI reads them in two places:
+
+- `pharos doctor` compares the bridge installed in each VS Code flavour with
+  the `version` in the JSON (`vscode-bridge`, `vscode-insiders-bridge`).
+- `pharos setup --install vscode-bridge` checks the `.vsix` against the
+  JSON's `sha256` and hands it to each installed flavour's own
+  `Contents/Resources/app/bin/code --install-extension`, because the `code`
+  command is usually not on PATH.
+
+`PHAROS_BRIDGE_VSIX=/path/to/other.vsix` overrides the location — for
+installing a local build, and for the tests, which must never install a real
+extension into somebody's editor.

package/vscode/pharos-bridge.json

@@ -0,0 +1,10 @@
+{
+  "id": "floh-solutions.pharos",
+  "version": "0.2.0",
+  "vsix": "pharos-bridge.vsix",
+  "sha256": "1dfde61c1bf0e3bba1ec98e798ae26b05a04415a9e903c8440dca1748c4dccae",
+  "bytes": 23158,
+  "engines": {
+    "vscode": "^1.94.0"
+  }
+}

package/dist/commands/pr.d.ts

@@ -1,56 +0,0 @@
-import { type ExitCode, type Io } from "../output.js";
-import type { Session } from "../session.js";
-/**
- * `pharos pr` — where the trail goes after adoption.
- *
- * ## The gap this closes
- *
- * `pharos issue` joins a GitHub issue to a work item, and `issue trail` follows
- * that join from either end. Both stop at the moment the work becomes code. A
- * session asking *"is this actually done?"* got filing, adoption and a state
- * field, and nothing at all about the branch that answers the question.
- *
- * ## What it composes
- *
- * One call, two platforms, four questions that are otherwise four commands and
- * two credentials:
- *
- * | | otherwise |
- * |---|---|
- * | the pull request and its review verdict | `gh pr view` |
- * | which checks are RED (not the first few) | `gh pr checks` |
- * | which work items it belongs to | a WIQL query, or reading a marker by hand |
- * | whether the two platforms AGREE | nothing — this is the part nobody has |
- *
- * ## The join is two paths, and the implicit one is the one that fires
- *
- * A pull request reaches a work item two ways, and both are read:
- *
- * 1. **Directly** — `AB#4821` in the body. This is what Azure Boards' own GitHub
- *    app reads, and Pharos writes it so that integration lights up free where it
- *    happens to be installed.
- * 2. **Transitively** — `Fixes #45`, where issue #45 has been adopted. GitHub
- *    reports this as `closingIssuesReferences`, and it is the path that actually
- *    occurs: developers write `Fixes #45` constantly and `AB#4821` almost never.
- *
- * Path 2 costs one extra read per closed issue — the issue's comments, which is
- * where the `pharos:v1` trailer lives. `linksFromComments` is `gh-core`'s, the
- * same function `issue trail` and the macOS app use, because "what counts as a
- * link" must have exactly one answer.
- *
- * ## The disagreements are the point
- *
- * Everything above is a read that something else could eventually do. The
- * `disagreements` array is the part **neither platform will ever tell you**:
- * an open pull request against a work item somebody already closed, a merged one
- * against a work item still sitting in To Do. Azure DevOps cannot see the pull
- * request and GitHub does not know the work item exists, so nothing anywhere is
- * in a position to notice. Same shape as `pharos issue drift`, one step further
- * down the pipeline.
- */
-export interface PrCommandOptions {
-    /** Skip resolving `Fixes #N` through to work items. One read per closed issue. */
-    noWorkItems: boolean;
-}
-export declare function runPr(io: Io, session: Session, rest: readonly string[], options: PrCommandOptions): Promise<ExitCode>;
-//# sourceMappingURL=pr.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"pr.d.ts","sourceRoot":"","sources":["../../src/commands/pr.ts"],"names":[],"mappings":"AAOA,OAAO,EAAyC,KAAK,QAAQ,EAAE,KAAK,EAAE,EAAE,MAAM,cAAc,CAAC;AAC7F,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,kFAAkF;IAClF,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,wBAAsB,KAAK,CACzB,EAAE,EAAE,EAAE,EACN,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,QAAQ,CAAC,CA6EnB"}