@event4u/agent-switch 1.5.0 → 1.6.0

package/README.md

@@ -1,7 +1,17 @@
+<p align="center"><a href="https://event4u.app"><img alt="agent-switch" src=".github/assets/banner.png"></a></p>
+
 # agent-switch
 
+<p align="center">
+  <a href="https://www.npmjs.com/package/@event4u/agent-switch"><img alt="npm" src="https://img.shields.io/npm/v/@event4u/agent-switch?style=flat-square&color=orange"></a>
+  <a href="https://event4u-app.github.io/agent-switch/"><img alt="Documentation" src="https://img.shields.io/badge/docs-event4u--app.github.io-orange?style=flat-square"></a>
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-orange?style=flat-square"></a>
+</p>
+
 Switch between multiple Claude Code accounts on macOS, Linux, and Windows with a single shell command — no repeated login/logout, no browser round-trips after the initial setup.
 
+📖 **[Read the documentation →](https://event4u-app.github.io/agent-switch/)**
+
 ```
 $ asw work        # switch active account
 $ claude         # runs on the "work" account
@@ -19,7 +29,7 @@ Most naive switchers snapshot the macOS Keychain entry (`Claude Code-credentials
 
 ## Install
 
-**npm / npx** (any OS — needs Node ≥ 18). The package is published as
+**npm / npx** (any OS — needs Node ≥ 20). The package is published as
 `@event4u/agent-switch` (the bare name `agent-switch` on npm is an unrelated
 project):
 

package/dist/index.js

@@ -14,7 +14,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { spawn, spawnSync } from "node:child_process";
-import { HOME, browserDir, configDir, die, ensureRoot, identity, listAllProfiles, listProfiles, migrateLegacyLayout, profileDir, profileExists, readJson, requireProfile, activeFor, setActive, labelFor, setLabel, clearLabel, renameProfile, isProfileLabel, PROFILE_LABELS, readAutoSwitch, readAutoSwitchAll, setAutoSwitch, readSwitchStrategy, setSwitchStrategy, readOsNotifications, setOsNotifications, readProviders, setProviderSurface, ROOT, } from "./profiles.js";
+import { HOME, browserDir, configDir, die, ensureRoot, identity, listAllProfiles, listProfiles, migrateLegacyLayout, profileDir, profileExists, readJson, requireProfile, activeFor, setActive, labelFor, setLabel, clearLabel, renameProfile, isProfileLabel, PROFILE_LABELS, readAutoSwitch, readAutoSwitchAll, setAutoSwitch, readSwitchStrategy, setSwitchStrategy, readOsNotifications, setOsNotifications, readProviders, setProviderSurface, readBinaryPath, readBinaryPaths, setBinaryPath, ROOT, } from "./profiles.js";
 import { PROVIDER_IDS, provider, isProviderInstalled, resolveBinary } from "./providers.js";
 import { parseArgs, parseRun, resolveProviderValue } from "./args.js";
 import { extractBrief, writeBrief, sweepBriefs, seedPrompt } from "./handoff.js";
@@ -59,9 +59,9 @@ function launch(p, name, args) {
         ensureAgyKeychain(home);
         env.CFFIXED_USER_HOME = home;
     }
-    const res = spawnSync(resolveBinary(p.binary), args, { env, stdio: "inherit" });
+    const res = spawnSync(resolveBinary(p.binary, readBinaryPath(p.id)), args, { env, stdio: "inherit" });
     if (res.error && res.error.code === "ENOENT") {
-        die(`\`${p.binary}\` binary not found on PATH. Install ${p.id} first.`);
+        die(`\`${p.binary}\` not found. Install ${p.id}, or link its binary: agent-switch providers link --provider ${p.id} --path <path> (Providers tab in the GUI).`);
     }
     return res.status ?? 1;
 }
@@ -952,7 +952,7 @@ function sessionsRmCodex(sessionId, flags, purge, json) {
     const action = purge ? "delete" : "archive";
     const p = provider("codex");
     const env = { ...process.env, [p.envVar]: cfg };
-    const r = spawnSync(resolveBinary(p.binary), codexSessionCommand(action, sessionId), { env, encoding: "utf8" });
+    const r = spawnSync(resolveBinary(p.binary, readBinaryPath(p.id)), codexSessionCommand(action, sessionId), { env, encoding: "utf8" });
     const out = `${r.stdout ?? ""}${r.stderr ?? ""}`.trim();
     if (/no .*session.*found/i.test(out))
         die(`codex could not find session ${sessionId} in "${profile}": ${out}`);
@@ -990,7 +990,7 @@ function cmdSessionsRestore(providerId, providerExplicit, handle, flags = {}) {
         const profile = requireProfile("codex", flags.from, "sessions restore --from");
         const p = provider("codex");
         const env = { ...process.env, [p.envVar]: configDir("codex", profile) };
-        const r = spawnSync(resolveBinary(p.binary), codexSessionCommand("unarchive", handle), { env, encoding: "utf8" });
+        const r = spawnSync(resolveBinary(p.binary, readBinaryPath(p.id)), codexSessionCommand("unarchive", handle), { env, encoding: "utf8" });
         const out = `${r.stdout ?? ""}${r.stderr ?? ""}`.trim();
         if (/no .*session.*found/i.test(out))
             die(`codex could not find an archived session ${handle} in "${profile}": ${out}`);
@@ -1351,22 +1351,41 @@ function cmdProviders(providerId, providerExplicit, mode, flags = {}) {
         console.log(`${providerId}: cli ${cfg.cli ? "on" : "off"}, ui ${cfg.ui ? "on" : "off"}.`);
         return;
     }
+    // Link the provider's CLI binary when it isn't on PATH — the user points us at
+    // it (from the GUI Providers tab or here). `unlink` reverts to PATH resolution.
+    if (mode === "link") {
+        const binPath = typeof flags.path === "string" ? flags.path : undefined;
+        if (!binPath)
+            die(`usage: agent-switch providers link --provider ${providerId} --path <path-to-binary>`);
+        if (!fs.existsSync(binPath))
+            die(`no file at "${binPath}" — pass the full path to the ${provider(providerId).binary} binary.`);
+        setBinaryPath(providerId, binPath);
+        console.log(`Linked ${providerId} binary → ${binPath}`);
+        return;
+    }
+    if (mode === "unlink") {
+        setBinaryPath(providerId, null);
+        console.log(`Unlinked ${providerId} binary (back to PATH resolution).`);
+        return;
+    }
     if (mode === undefined || mode === "status") {
         const all = readProviders();
+        const links = readBinaryPaths();
         if (flags.json) {
-            // The GUI needs every provider's enabled surfaces AND whether its binary
-            // is installed (so it can show but not enable a missing provider) at once.
-            const enriched = Object.fromEntries(PROVIDER_IDS.map((p) => [p, { ...all[p], installed: isProviderInstalled(p) }]));
+            // The GUI needs every provider's enabled surfaces, whether its binary is
+            // usable (installed on PATH or linked), and any linked path — so it can
+            // show, link, and enable a provider that isn't on PATH — all at once.
+            const enriched = Object.fromEntries(PROVIDER_IDS.map((p) => [p, { ...all[p], installed: isProviderInstalled(p, links[p]), binaryPath: links[p] ?? null }]));
             console.log(JSON.stringify(enriched));
             return;
         }
         for (const p of providerExplicit ? [providerId] : PROVIDER_IDS) {
-            const inst = isProviderInstalled(p) ? "installed" : "not installed";
+            const inst = isProviderInstalled(p, links[p]) ? (links[p] ? `linked: ${links[p]}` : "installed") : "not installed";
             console.log(`${p}: cli ${all[p].cli ? "on" : "off"}, ui ${all[p].ui ? "on" : "off"} (${inst}).`);
         }
         return;
     }
-    die("usage: agent-switch providers enable|disable|status [--provider P] [--surface cli|ui] [--json]");
+    die("usage: agent-switch providers enable|disable|link|unlink|status [--provider P] [--surface cli|ui] [--path <bin>] [--json]");
 }
 /**
  * Remove agent-switch's own footprint. Deletes every profile (incl. Claude

package/dist/profiles.js

@@ -147,27 +147,36 @@ function normalizeProvidersMap(raw) {
         out[p] = normalizeSurfaces(r[p], p);
     return out;
 }
+function normalizeBinaryPaths(raw) {
+    const r = (raw ?? {});
+    const out = {};
+    for (const p of PROVIDER_IDS)
+        if (typeof r[p] === "string" && r[p])
+            out[p] = r[p];
+    return out;
+}
 export function readState() {
     try {
         const raw = JSON.parse(fs.readFileSync(STATE_FILE, "utf8"));
         const labels = normalizeLabels(raw?.labels);
         const autoSwitch = normalizeAutoSwitchMap(raw?.autoSwitch);
         const providers = normalizeProvidersMap(raw?.providers);
+        const binaryPaths = normalizeBinaryPaths(raw?.binaryPaths);
         const switchStrategy = raw?.switchStrategy === "rotation-first" ? "rotation-first" : DEFAULT_SWITCH_STRATEGY;
         const osNotifications = raw?.osNotifications === true;
         // v1: { active: "<name>" } — a single Claude profile.
         if (typeof raw?.active === "string") {
-            return { active: { ...emptyActive(), claude: raw.active }, labels, autoSwitch, providers, switchStrategy, osNotifications };
+            return { active: { ...emptyActive(), claude: raw.active }, labels, autoSwitch, providers, binaryPaths, switchStrategy, osNotifications };
         }
         if (raw?.active && typeof raw.active === "object") {
-            return { active: { ...emptyActive(), ...raw.active }, labels, autoSwitch, providers, switchStrategy, osNotifications };
+            return { active: { ...emptyActive(), ...raw.active }, labels, autoSwitch, providers, binaryPaths, switchStrategy, osNotifications };
         }
-        return { active: emptyActive(), labels, autoSwitch, providers, switchStrategy, osNotifications };
+        return { active: emptyActive(), labels, autoSwitch, providers, binaryPaths, switchStrategy, osNotifications };
     }
     catch {
         /* absent / unparsable → default */
     }
-    return { active: emptyActive(), labels: {}, autoSwitch: emptyAutoSwitch(), providers: emptyProviders(), switchStrategy: DEFAULT_SWITCH_STRATEGY, osNotifications: false };
+    return { active: emptyActive(), labels: {}, autoSwitch: emptyAutoSwitch(), providers: emptyProviders(), binaryPaths: {}, switchStrategy: DEFAULT_SWITCH_STRATEGY, osNotifications: false };
 }
 export function readSwitchStrategy() {
     return readState().switchStrategy;
@@ -292,6 +301,24 @@ export function setProviderSurface(providerId, surface, enabled) {
     writeState(state);
     return state.providers[providerId];
 }
+// ---------- linked binary paths (provider CLI not on PATH) ----------
+/** The user-linked absolute path to a provider's CLI binary, or null. */
+export function readBinaryPath(providerId) {
+    return readState().binaryPaths[providerId] ?? null;
+}
+/** All linked binary paths (for `providers status` / the GUI tab). */
+export function readBinaryPaths() {
+    return readState().binaryPaths;
+}
+/** Link (set) or unlink (null) a provider's CLI binary path. */
+export function setBinaryPath(providerId, binPath) {
+    const state = readState();
+    if (binPath)
+        state.binaryPaths[providerId] = binPath;
+    else
+        delete state.binaryPaths[providerId];
+    writeState(state);
+}
 // ---------- layout migration: v1 <ROOT>/<name> → <ROOT>/claude/<name> ----------
 /**
  * One-time migration of v1 Claude profiles (`<ROOT>/<name>/config`) into the

package/dist/providers.js

@@ -143,12 +143,15 @@ function localBinary(binary) {
     return path.join(os.homedir(), ".local", "bin", binary);
 }
 /**
- * Resolve a CLI binary to an invocable command: its bare name when it is on
- * PATH, otherwise its ~/.local/bin path when the binary lives there (GUI apps
- * often run with a minimal PATH that omits it), otherwise the bare name so the
- * caller surfaces a clean "not found" error.
+ * Resolve a CLI binary to an invocable command: a user-linked path when set and
+ * present (the CLI is not on PATH but the user pointed us at it), otherwise its
+ * bare name when it is on PATH, otherwise its ~/.local/bin path when the binary
+ * lives there (GUI apps often run with a minimal PATH that omits it), otherwise
+ * the bare name so the caller surfaces a clean "not found" error.
  */
-export function resolveBinary(binary) {
+export function resolveBinary(binary, linked) {
+    if (linked && fs.existsSync(linked))
+        return linked;
     const probe = spawnSync(binary, ["--version"], { stdio: "ignore", timeout: 5000 });
     if (probe.error?.code !== "ENOENT")
         return binary;
@@ -156,12 +159,15 @@ export function resolveBinary(binary) {
     return fs.existsSync(local) ? local : binary;
 }
 /**
- * Best-effort: is this provider's CLI binary installed? Probes `<binary>
- * --version` on PATH and treats only ENOENT as not-installed (a non-zero exit or
- * a timeout still means the binary exists), then falls back to the ~/.local/bin
- * install location. Used to gate enabling a provider the user hasn't installed.
+ * Best-effort: is this provider's CLI binary usable? True when a user-linked
+ * path is set and present, else when `<binary> --version` resolves on PATH
+ * (only ENOENT counts as not-installed — a non-zero exit or a timeout still
+ * means the binary exists), else when it lives in ~/.local/bin. Used to gate
+ * enabling a provider the user hasn't installed (or hasn't linked).
  */
-export function isProviderInstalled(id) {
+export function isProviderInstalled(id, linked) {
+    if (linked && fs.existsSync(linked))
+        return true;
     const bin = PROVIDERS[id].binary;
     const probe = spawnSync(bin, ["--version"], { stdio: "ignore", timeout: 5000 });
     if (probe.error?.code !== "ENOENT")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@event4u/agent-switch",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Switch between multiple Claude Code accounts on macOS, Linux, and Windows via isolated CLAUDE_CONFIG_DIR profiles",
   "repository": {
     "type": "git",