@floh-solutions/pharos-cli 0.29.0 → 0.30.0

package/dist/delegate/sessions.js

@@ -0,0 +1,220 @@
+import { execFile } from "node:child_process";
+import { realpath } from "node:fs/promises";
+import { basename } from "node:path";
+import { promisify } from "node:util";
+import { hostOfCommand } from "./hosts.js";
+const run = promisify(execFile);
+/**
+ * `ps -axo pid,ppid,tty,comm`, parsed.
+ *
+ * The command column is taken as everything after the third column because
+ * it contains spaces — `/Applications/ChatGPT.app/…/Codex (Service)` is one
+ * command. The header line does not match the numeric shape and is dropped.
+ */
+export function parsePs(text) {
+    const rows = [];
+    for (const line of text.split("\n")) {
+        const match = /^\s*(\d+)\s+(\d+)\s+(\S+)\s+(.+?)\s*$/.exec(line);
+        if (match === null)
+            continue;
+        const tty = match[3];
+        rows.push({
+            pid: Number(match[1]),
+            ppid: Number(match[2]),
+            tty: tty === "??" || tty === "-" ? null : tty.startsWith("/dev/") ? tty : `/dev/${tty}`,
+            comm: match[4],
+        });
+    }
+    return rows;
+}
+/**
+ * `claude agents --json`, parsed tolerantly: an array of objects with a numeric
+ * `pid` and a string `cwd` is all that is required, so a field Claude Code
+ * adds or drops in a later release changes nothing here.
+ */
+export function parseClaudeAgents(json) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(parsed))
+        return [];
+    const agents = [];
+    for (const entry of parsed) {
+        if (typeof entry !== "object" || entry === null)
+            continue;
+        const record = entry;
+        if (typeof record["pid"] !== "number" || typeof record["cwd"] !== "string")
+            continue;
+        agents.push({
+            pid: record["pid"],
+            cwd: record["cwd"],
+            ...(typeof record["kind"] === "string" ? { kind: record["kind"] } : {}),
+            ...(typeof record["sessionId"] === "string" ? { sessionId: record["sessionId"] } : {}),
+            ...(typeof record["name"] === "string" ? { name: record["name"] } : {}),
+            ...(typeof record["status"] === "string" ? { status: record["status"] } : {}),
+            ...(typeof record["startedAt"] === "number" ? { startedAt: record["startedAt"] } : {}),
+        });
+    }
+    return agents;
+}
+/** `lsof -a -p PID -d cwd -Fn` prints `p<pid>`, `fcwd`, `n<path>`; the path is what we want. */
+export function parseLsofCwd(text) {
+    for (const line of text.split("\n")) {
+        if (line.startsWith("n"))
+            return line.slice(1).trim() || null;
+    }
+    return null;
+}
+/** The ancestors of a pid, nearest first, stopping at launchd or a cycle. */
+export function ancestry(pid, rows) {
+    const byPid = new Map(rows.map((row) => [row.pid, row]));
+    const chain = [];
+    const seen = new Set();
+    let current = byPid.get(pid)?.ppid;
+    while (current !== undefined && current > 1 && !seen.has(current)) {
+        seen.add(current);
+        const row = byPid.get(current);
+        if (row === undefined)
+            break;
+        chain.push(row);
+        current = row.ppid;
+    }
+    return chain;
+}
+/** The first ancestor that is a known host, or null. */
+export function hostOfPid(pid, rows) {
+    for (const ancestor of ancestry(pid, rows)) {
+        const host = hostOfCommand(ancestor.comm);
+        if (host !== null)
+            return host;
+    }
+    return null;
+}
+export function systemProbes(env, claudePath) {
+    return {
+        ps: async () => (await run("/bin/ps", ["-axo", "pid,ppid,tty,comm"], { timeout: 10_000, maxBuffer: 8 * 1024 * 1024 })).stdout,
+        claudeAgents: async () => {
+            if (claudePath === null)
+                return "[]";
+            // Bounded and given the caller's env: the same rule as every probe in
+            // `doctor` — it must ask the machine the report describes.
+            const { stdout } = await run(claudePath, ["agents", "--json"], {
+                timeout: 20_000,
+                maxBuffer: 4 * 1024 * 1024,
+                env,
+            });
+            return stdout;
+        },
+        lsofCwd: async (pid) => (await run("/usr/sbin/lsof", ["-a", "-p", String(pid), "-d", "cwd", "-Fn"], { timeout: 10_000 })).stdout,
+    };
+}
+/**
+ * Every session of `agent` whose working directory is `folder`, with its host.
+ *
+ * Working directories are compared after `realpath` on both sides, so a
+ * symlinked checkout and its target read as one folder. A session whose cwd
+ * cannot be resolved is compared as printed.
+ */
+export async function findSessions(agent, folder, probes) {
+    const rows = parsePs(await probes.ps());
+    const target = await canonical(folder);
+    const sessions = [];
+    if (agent === "claude") {
+        let agents = [];
+        try {
+            agents = parseClaudeAgents(await probes.claudeAgents());
+        }
+        catch (error) {
+            // A `claude` that cannot list its sessions leaves us unable to tell an
+            // idle session from none at all — the caller launches, and says so.
+            return { sessions, incomplete: true, detail: `\`claude agents --json\` could not be read: ${messageOf(error)}` };
+        }
+        for (const found of agents) {
+            if ((await canonical(found.cwd)) !== target)
+                continue;
+            sessions.push({
+                agent,
+                pid: found.pid,
+                cwd: found.cwd,
+                name: found.name ?? null,
+                status: found.status === "idle" || found.status === "busy" ? found.status : null,
+                tty: rows.find((row) => row.pid === found.pid)?.tty ?? null,
+                host: hostOfPid(found.pid, rows),
+            });
+        }
+        return { sessions, incomplete: false, detail: null };
+    }
+    // Codex: the TUI process is `codex`; `codex-code-mode-host` and the ChatGPT
+    // app's bundled helpers are not sessions, and the host walk drops the app's
+    // own `codex` because ChatGPT.app is not a host anybody can delegate to.
+    let lsofFailed = 0;
+    for (const row of rows) {
+        if (basename(row.comm) !== "codex")
+            continue;
+        let cwd = null;
+        try {
+            cwd = parseLsofCwd(await probes.lsofCwd(row.pid));
+        }
+        catch {
+            // One codex whose cwd could not be read is one that might be on this
+            // folder and go unseen. Counted so the caller can say detection was partial.
+            lsofFailed += 1;
+            continue;
+        }
+        if (cwd === null || (await canonical(cwd)) !== target)
+            continue;
+        sessions.push({
+            agent,
+            pid: row.pid,
+            cwd,
+            name: null,
+            // Codex does not say. `null` is "not known", never a guess at idle.
+            status: null,
+            tty: row.tty,
+            host: hostOfPid(row.pid, rows),
+        });
+    }
+    return {
+        sessions,
+        incomplete: lsofFailed > 0,
+        detail: lsofFailed > 0 ? `the working directory of ${lsofFailed} codex process(es) could not be read (\`lsof\`)` : null,
+    };
+}
+/**
+ * Which session to send to, among those in the requested host.
+ *
+ * Idle beats busy: a prompt typed into a busy session queues behind the turn
+ * in progress, which works but is a worse experience than a session that is
+ * waiting for exactly this. Among equals the lowest pid — the longest-lived,
+ * which is usually the one the person thinks of as "the" session.
+ */
+export function chooseSession(sessions, host) {
+    // **A controlling tty is required to type into a session, so a tty-less one
+    // is not a send target.** `claude agents --json` lists sessions with no tty,
+    // and the Codex VS Code extension's own app-server is a tty-less `codex`;
+    // choosing one makes a host answer `sent` while the route can only launch.
+    // Navarch is the exception — its workers reach the app over the socket, not a
+    // tty — but delegation to Navarch is refused upstream, so this is defensive.
+    const mine = sessions.filter((session) => session.host === host && (host === "navarch" || session.tty !== null));
+    if (mine.length === 0)
+        return null;
+    const rank = (session) => session.status === "idle" ? 0 : session.status === null ? 1 : 2;
+    return [...mine].sort((a, b) => rank(a) - rank(b) || a.pid - b.pid)[0];
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+async function canonical(path) {
+    const trimmed = path.length > 1 ? path.replace(/\/+$/, "") : path;
+    try {
+        return await realpath(trimmed);
+    }
+    catch {
+        return trimmed;
+    }
+}
+//# sourceMappingURL=sessions.js.map

package/dist/delegate/sessions.js.map

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

package/dist/delegate/vsix.d.ts

@@ -0,0 +1,122 @@
+import { type HostId } from "./hosts.js";
+/**
+ * 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 declare const BRIDGE_EXTENSION_ID = "floh-solutions.pharos";
+/** `anthropic.claude-code` and `openai.chatgpt` — the ids the extension folders and manifest carry. */
+export declare const CLAUDE_EXTENSION_ID = "anthropic.claude-code";
+export declare 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 declare function bundledVsixPath(env?: NodeJS.ProcessEnv): string;
+/** The manifest the bridge's build writes beside the `.vsix`. */
+export declare function bundledManifestPath(env?: NodeJS.ProcessEnv): string;
+export interface VsixManifest {
+    publisher: string | null;
+    name: string | null;
+    version: string | null;
+}
+export interface BundledBridge {
+    path: string;
+    bytes: number;
+    /** Publisher, name and version — from the JSON manifest, else from the zip. */
+    manifest: VsixManifest;
+    /** What the JSON manifest says the bytes should hash to; null without one. */
+    sha256: string | null;
+    /** Where the version came from. */
+    via: "manifest" | "vsix";
+}
+/** The bridge this CLI ships, or null when the `.vsix` is not there. Never throws. */
+export declare function bundledBridge(env?: NodeJS.ProcessEnv): Promise<BundledBridge | null>;
+/**
+ * `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 declare function vsixManifest(bytes: Buffer): VsixManifest;
+/** One file's contents out of a zip, by exact name, or null. */
+export declare function zipEntry(bytes: Buffer, name: string): Buffer | null;
+export interface InstalledExtension {
+    id: string;
+    version: string;
+    path: string;
+}
+/** `~/.vscode[-insiders]/extensions` for a VS Code flavour; null for any other host. */
+export declare function extensionsDirectory(host: HostId, env?: NodeJS.ProcessEnv): string | null;
+/**
+ * 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 declare function installedExtensions(host: HostId, env?: NodeJS.ProcessEnv): Promise<InstalledExtension[] | null>;
+/** `anthropic.claude-code-2.1.228-darwin-arm64` → id and version. Null for anything else. */
+export declare function parseExtensionFolder(name: string): {
+    id: string;
+    version: string;
+} | null;
+export interface BridgeInstallOutcome {
+    ok: boolean;
+    /** The last command run, so a transcript shows what happened. */
+    command: string | null;
+    detail: string;
+    /** Per flavour: which got it, which did not, and why. */
+    flavours: {
+        host: HostId;
+        ok: boolean;
+        detail: string;
+    }[];
+}
+/**
+ * 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 declare function installBridge(options?: {
+    env?: NodeJS.ProcessEnv;
+    onCommand?: (command: string) => void;
+}): Promise<BridgeInstallOutcome>;
+//# sourceMappingURL=vsix.d.ts.map

package/dist/delegate/vsix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vsix.d.ts","sourceRoot":"","sources":["../../src/delegate/vsix.ts"],"names":[],"mappings":"AASA,OAAO,EAA6B,KAAK,MAAM,EAAE,MAAM,YAAY,CAAC;AAIpE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,eAAO,MAAM,mBAAmB,0BAA0B,CAAC;AAE3D,uGAAuG;AACvG,eAAO,MAAM,mBAAmB,0BAA0B,CAAC;AAC3D,eAAO,MAAM,kBAAkB,mBAAmB,CAAC;AAEnD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAM5E;AAED,iEAAiE;AACjE,wBAAgB,mBAAmB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAEhF;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,QAAQ,EAAE,YAAY,CAAC;IACvB,8EAA8E;IAC9E,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,mCAAmC;IACnC,GAAG,EAAE,UAAU,GAAG,MAAM,CAAC;CAC1B;AAED,sFAAsF;AACtF,wBAAsB,aAAa,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CA8BvG;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,CAcxD;AAMD,gEAAgE;AAChE,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA6CnE;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wFAAwF;AACxF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,GAAG,IAAI,CAIrG;AAED;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,MAAM,EACZ,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAAC,kBAAkB,EAAE,GAAG,IAAI,CAAC,CAmCtC;AAED,6FAA6F;AAC7F,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAOzF;AAED,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,OAAO,CAAC;IACZ,iEAAiE;IACjE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC3D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CACjC,OAAO,GAAE;IACP,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAClC,GACL,OAAO,CAAC,oBAAoB,CAAC,CAoF/B"}