@fargowealth/fargo-ai-cli 0.7.2 → 0.7.3

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.7.3
+
+- Added one-command Agent installation through `fargo agent install --agent`
+  for WorkBuddy, Claude Code, Codex, and Cursor.
+- The installer completes CLI-managed OAuth + PKCE, writes a local stdio MCP
+  connection, and reuses the same private rotating credential on later runs.
+- Kept `fargo workbuddy install` as a compatibility alias.
+
 ## 0.7.2
 
 - Added `fargo lego deploy --help` with the complete Worker Static Assets

package/README.md

@@ -9,23 +9,25 @@ Requires Node.js 20.19 or newer.
 ## Install or upgrade
 
 ```sh
-npm install -g @fargowealth/fargo-ai-cli@0.7.2
+npm install -g @fargowealth/fargo-ai-cli@0.7.3
 fargo version
 ```
 
-Use native hosted Fargo MCP for ordinary online tools. Authenticate the CLI
-only when an Agent first needs local files:
+Install the Fargo MCP connection with one command for the selected Agent:
 
 ```sh
-fargo auth login --agent codex
-fargo auth login --agent claude-code
-fargo auth login --agent cursor
+npx -y @fargowealth/fargo-ai-cli@latest agent install --agent=codex --open-browser=always --output=jsonl
+npx -y @fargowealth/fargo-ai-cli@latest agent install --agent=claude-code --open-browser=always --output=jsonl
+npx -y @fargowealth/fargo-ai-cli@latest agent install --agent=cursor --open-browser=always --output=jsonl
+npx -y @fargowealth/fargo-ai-cli@latest agent install --agent=workbuddy --open-browser=always --output=jsonl
 fargo auth status
 ```
 
-Aliases `cc` and `claude` resolve to `claude-code`. Login uses OAuth
-Authorization Code + PKCE over an ephemeral IPv4 loopback callback. The CLI
-validates state, uses PKCE S256, closes the listener, and never prints tokens.
+Run only the line for the Agent being configured. The command completes OAuth
+Authorization Code + PKCE over an ephemeral IPv4 loopback callback, writes the
+Agent's user-level local stdio MCP entry, and reports `installed=true`. It is
+normally run once; the rotating credential is then refreshed automatically and
+reused by both MCP and local CLI operations.
 
 ## MCP boundary
 
@@ -34,9 +36,10 @@ validates state, uses PKCE S256, closes the listener, and never prints tokens.
 - CLI owns local walking, exclusions, ZIP creation, hashing, binary transfer,
   deploy composition, and migration-file ordering.
 - CLI has no generic R2 or Cloudflare administration commands.
-- `fargo mcp serve` is the local stdio bridge for WorkBuddy.
-- `fargo mcp tools` and `fargo mcp call` are fallbacks for Agents without a
-  native remote MCP client.
+- `fargo mcp serve` is the local stdio bridge for WorkBuddy, Claude Code,
+  Codex, and Cursor.
+- `fargo mcp tools` and `fargo mcp call` support scripts and one-shot
+  diagnostics without starting an MCP host.
 
 ```sh
 fargo mcp tools
@@ -175,14 +178,16 @@ blocked. `--table-prefix` is a local assertion and the service rejects it if it
 does not match the App's authoritative prefix. Migration execution remains
 server-side and is never coupled to deploy.
 
-## WorkBuddy adapter
+## Compatibility and repair
 
 ```sh
 npx -y @fargowealth/fargo-ai-cli@latest workbuddy install --open-browser=always --output=jsonl
 ```
 
-The installer preserves existing MCP servers and adds the local Fargo stdio
-bridge. Device Authorization Grant remains an explicit fallback:
+The legacy WorkBuddy command is an alias for the unified Agent installer.
+Installers preserve unrelated MCP servers. Rerun the unified command only to
+upgrade or repair a Fargo entry. Device Authorization Grant remains an explicit
+fallback:
 
 ```sh
 fargo auth device --open-browser=always --output=jsonl

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fargowealth/fargo-ai-cli",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "description": "Agent-neutral Fargo AI CLI, MCP client, and LEGO project tooling",
   "type": "module",
   "bin": {

package/src/agent-install.mjs

@@ -0,0 +1,241 @@
+import { constants as fsConstants } from "node:fs";
+import { access, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { spawn } from "node:child_process";
+import { normalizeAgentType } from "./auth.mjs";
+import { CLI_VERSION } from "./constants.mjs";
+
+const PACKAGE_NAME = "@fargowealth/fargo-ai-cli";
+const SERVER_NAME = "fargo-ai";
+
+export async function installAgentMcp(rawAgent, options = {}) {
+  const agent = normalizeAgentType(rawAgent);
+  const platform = options.platform ?? process.platform;
+  const env = options.env ?? process.env;
+  const homeDirectory = options.home ?? homedir();
+  const packageSpec = `${PACKAGE_NAME}@${options.packageVersion ?? CLI_VERSION}`;
+  const npxCommand = options.npxCommand ?? (platform === "darwin"
+    ? await resolveNpxCommand({ env, execPath: options.execPath, platform })
+    : "npx");
+  const server = mcpServerConfig({ agent, env, homeDirectory, npxCommand, packageSpec, platform });
+
+  if (agent === "workbuddy" || agent === "cursor") {
+    return installJsonMcp(agent, server, {
+      ...options,
+      configPath: options.configPath ?? defaultAgentConfigPath(agent, homeDirectory)
+    });
+  }
+
+  return installHostCliMcp(agent, server, options);
+}
+
+export async function installWorkBuddyMcp(options = {}) {
+  return installAgentMcp("workbuddy", options);
+}
+
+export function defaultAgentConfigPath(rawAgent, homeDirectory = homedir()) {
+  const agent = normalizeAgentType(rawAgent);
+  if (agent === "workbuddy") return join(homeDirectory, ".workbuddy-ai", "mcp.json");
+  if (agent === "cursor") return join(homeDirectory, ".cursor", "mcp.json");
+  return undefined;
+}
+
+export async function resolveNpxCommand(options = {}) {
+  const platform = options.platform ?? process.platform;
+  const env = options.env ?? process.env;
+  const execPath = options.execPath ?? process.execPath;
+  const executableName = platform === "win32" ? "npx.cmd" : "npx";
+  const pathDelimiter = platform === "win32" ? ";" : ":";
+  const candidates = [
+    join(dirname(execPath), executableName),
+    ...String(env.PATH ?? env.Path ?? env.path ?? "").split(pathDelimiter).filter(Boolean).map((entry) => join(entry, executableName))
+  ];
+  for (const candidate of candidates) {
+    const absoluteCandidate = isAbsolute(candidate) ? candidate : resolve(candidate);
+    try {
+      await access(absoluteCandidate, platform === "win32" ? fsConstants.F_OK : fsConstants.X_OK);
+      return absoluteCandidate;
+    } catch {
+      // Continue until an executable visible to the GUI host is found.
+    }
+  }
+  throw new Error("Unable to locate an absolute npx executable for the Agent MCP configuration");
+}
+
+function mcpServerConfig({ agent, env, homeDirectory, npxCommand, packageSpec, platform }) {
+  const credentialDirectory = platform === "win32"
+    ? join(env.APPDATA || homeDirectory, "Fargo AI")
+    : join(homeDirectory, ".fargo");
+  const serverEnv = {
+    FARGO_CREDENTIAL_PATH: join(credentialDirectory, "credentials.json"),
+    FARGO_CREDENTIAL_STORE: "file",
+    FARGO_REFRESH_LOCK_PATH: join(credentialDirectory, "oauth-refresh.lock")
+  };
+  if (platform === "darwin") serverEnv.PATH = buildMacPath(npxCommand);
+  if (platform === "win32") {
+    const windowsPath = env.PATH ?? env.Path ?? env.path;
+    if (windowsPath) serverEnv.PATH = windowsPath;
+  }
+  return {
+    agent,
+    args: ["-y", packageSpec, "mcp", "serve"],
+    command: npxCommand,
+    env: serverEnv,
+    packageSpec
+  };
+}
+
+async function installJsonMcp(agent, server, options) {
+  const config = await readConfig(options.configPath, agent);
+  const nextServer = {
+    ...(agent === "workbuddy" ? { type: "stdio" } : {}),
+    command: server.command,
+    args: server.args,
+    ...(agent === "workbuddy" ? { timeout: 60000 } : {}),
+    env: server.env
+  };
+  const previousServer = config.mcpServers?.[SERVER_NAME];
+  const changed = JSON.stringify(previousServer) !== JSON.stringify(nextServer);
+
+  if (changed) {
+    config.mcpServers = { ...(config.mcpServers ?? {}), [SERVER_NAME]: nextServer };
+    await writeConfig(options.configPath, config);
+  }
+
+  return installationResult(agent, server.packageSpec, changed, {
+    config_path: options.configPath,
+    trust_required: agent === "workbuddy"
+  });
+}
+
+async function installHostCliMcp(agent, server, options) {
+  const command = agent === "codex" ? "codex" : "claude";
+  const removeArgs = agent === "codex"
+    ? ["mcp", "remove", SERVER_NAME]
+    : ["mcp", "remove", "--scope", "user", SERVER_NAME];
+  const removeResult = await runHostCommand(command, removeArgs, options);
+  if (removeResult.exitCode !== 0 && !isMissingServer(removeResult)) {
+    throw new Error(`${agentLabel(agent)} could not replace the existing ${SERVER_NAME} MCP entry: ${commandError(removeResult)}`);
+  }
+
+  const environmentArgs = Object.entries(server.env).flatMap(([key, value]) => agent === "codex"
+    ? ["--env", `${key}=${value}`]
+    : ["-e", `${key}=${value}`]);
+  const addArgs = agent === "codex"
+    ? ["mcp", "add", ...environmentArgs, SERVER_NAME, "--", server.command, ...server.args]
+    : ["mcp", "add", "--transport", "stdio", "--scope", "user", SERVER_NAME, ...environmentArgs, "--", server.command, ...server.args];
+  const addResult = await runHostCommand(command, addArgs, options);
+  if (addResult.exitCode !== 0) {
+    throw new Error(`${agentLabel(agent)} could not add the ${SERVER_NAME} CLI MCP entry: ${commandError(addResult)}`);
+  }
+
+  return installationResult(agent, server.packageSpec, true, {
+    configured_by: command,
+    trust_required: false
+  });
+}
+
+async function runHostCommand(command, args, options) {
+  if (options.runCommand) return normalizeCommandResult(await options.runCommand(command, args));
+  return new Promise((resolveResult, reject) => {
+    const child = spawn(command, args, { env: options.env ?? process.env, windowsHide: true });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (chunk) => { stdout += chunk.toString(); });
+    child.stderr?.on("data", (chunk) => { stderr += chunk.toString(); });
+    child.on("error", (error) => {
+      if (error?.code === "ENOENT") {
+        reject(new Error(`Required ${agentCommandLabel(command)} command '${command}' was not found; run the installer from that Agent environment`));
+        return;
+      }
+      reject(error);
+    });
+    child.on("close", (exitCode) => resolveResult({ exitCode: exitCode ?? 1, stderr, stdout }));
+  });
+}
+
+function normalizeCommandResult(result) {
+  return {
+    exitCode: Number(result?.exitCode ?? result?.code ?? 0),
+    stderr: String(result?.stderr ?? ""),
+    stdout: String(result?.stdout ?? "")
+  };
+}
+
+function isMissingServer(result) {
+  return /not found|no .*mcp server|does not exist|unknown server/i.test(`${result.stdout}\n${result.stderr}`);
+}
+
+function commandError(result) {
+  return (result.stderr || result.stdout || `exit ${result.exitCode}`).trim().slice(0, 300);
+}
+
+function installationResult(agent, packageSpec, changed, extra) {
+  return {
+    type: "agent_installation_complete",
+    agent,
+    installed: true,
+    changed,
+    server_name: SERVER_NAME,
+    package: packageSpec,
+    ...extra,
+    next_action: agent === "workbuddy"
+      ? "Open WorkBuddy Custom Connectors, trust and enable fargo-ai, then start a new task."
+      : `Restart ${agentLabel(agent)} or start a new Agent session, then call ping_who_am_i.`
+  };
+}
+
+function agentLabel(agent) {
+  if (agent === "claude-code") return "Claude Code";
+  if (agent === "codex") return "Codex";
+  if (agent === "cursor") return "Cursor";
+  return "WorkBuddy";
+}
+
+function agentCommandLabel(command) {
+  return command === "claude" ? "Claude Code" : "Codex";
+}
+
+function buildMacPath(npxCommand) {
+  return [...new Set([
+    dirname(npxCommand),
+    "/opt/homebrew/bin",
+    "/usr/local/bin",
+    "/usr/bin",
+    "/bin",
+    "/usr/sbin",
+    "/sbin"
+  ])].join(":");
+}
+
+async function readConfig(configPath, agent) {
+  let text;
+  try {
+    text = await readFile(configPath, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return {};
+    throw error;
+  }
+  if (!text.trim()) return {};
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new Error(`${agentLabel(agent)} MCP config is not valid JSON: ${configPath}`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`${agentLabel(agent)} MCP config must contain a JSON object: ${configPath}`);
+  }
+  if (parsed.mcpServers !== undefined && (!parsed.mcpServers || typeof parsed.mcpServers !== "object" || Array.isArray(parsed.mcpServers))) {
+    throw new Error(`${agentLabel(agent)} mcpServers must be a JSON object: ${configPath}`);
+  }
+  return parsed;
+}
+
+async function writeConfig(configPath, config) {
+  await mkdir(dirname(configPath), { recursive: true });
+  const temporaryPath = `${configPath}.${process.pid}.${Date.now()}.tmp`;
+  await writeFile(temporaryPath, `${JSON.stringify(config, null, 2)}\n`, { encoding: "utf8", mode: 0o600, flag: "wx" });
+  await rename(temporaryPath, configPath);
+}

package/src/cli.mjs

@@ -8,7 +8,7 @@ import { deployLocalLegoApp } from "./lego-deploy.mjs";
 import { applyLegoMigrations, planLegoMigrations } from "./lego-migrations.mjs";
 import { callMcpTool, listMcpTools } from "./mcp-client.mjs";
 import { runMcpProxy } from "./mcp-proxy.mjs";
-import { installWorkBuddyMcp } from "./workbuddy-install.mjs";
+import { installAgentMcp } from "./agent-install.mjs";
 
 export async function runCli(args, options = {}) {
   const stdout = options.stdout ?? process.stdout;
@@ -114,24 +114,15 @@ export async function runCli(args, options = {}) {
       }
       throw new Error("Usage: fargo lego d1 migrate plan|apply --app <appId> [--dir migrations] [--table-prefix app_prefix_] [--allow-data-migrations]");
     }
+    if (args[0] === "agent" && args[1] === "install") {
+      await installAgentConnection(args, requiredOption(args, "--agent"), stdout, store, options);
+      return;
+    }
     if (args[0] === "workbuddy" && args[1] === "install") {
-      let credential = await store.load();
-      if (credential) {
-        try {
-          credential = await currentCredential(store, options);
-        } catch {
-          await store.clear();
-          credential = undefined;
-        }
-      }
-      if (credential?.authorization_method !== "authorization_code_pkce") {
-        credential = undefined;
-      }
-      if (!credential?.refresh_token) await authorizeWithPkce(args, stdout, store, { ...options, agentType: "workbuddy" });
-      stdout.write(`${JSON.stringify(await installWorkBuddyMcp(options))}\n`);
+      await installAgentConnection(args, "workbuddy", stdout, store, options);
       return;
     }
-    throw new Error("Usage: fargo auth login|device|status|logout | fargo mcp serve|tools|call | fargo lego snapshot upload|list|download | fargo lego deploy | fargo lego d1 migrate plan|apply | fargo workbuddy install | fargo version");
+    throw new Error("Usage: fargo auth login|device|status|logout | fargo agent install --agent <agent> | fargo mcp serve|tools|call | fargo lego snapshot upload|list|download | fargo lego deploy | fargo lego d1 migrate plan|apply | fargo workbuddy install | fargo version");
   } catch (error) {
     stderr.write(`fargo: ${error instanceof Error ? error.message : "unknown error"}\n`);
     if (options.throwOnError) throw error;
@@ -143,6 +134,7 @@ const ROOT_HELP = `Usage: fargo <command> [options]
 
 Commands:
   auth login|device|status|logout
+  agent install --agent <codex|claude-code|cursor|workbuddy>
   mcp serve|tools|call
   lego snapshot upload|list|download
   lego deploy
@@ -197,6 +189,23 @@ function isHelpOption(args) {
   return args.includes("--help") || args.includes("-h");
 }
 
+async function installAgentConnection(args, agentType, stdout, store, options) {
+  let credential = await store.load();
+  if (credential) {
+    try {
+      credential = await currentCredential(store, options);
+    } catch {
+      await store.clear();
+      credential = undefined;
+    }
+  }
+  if (credential?.authorization_method !== "authorization_code_pkce") credential = undefined;
+  const authorizationReused = Boolean(credential?.refresh_token);
+  if (!authorizationReused) await authorizeWithPkce(args, stdout, store, { ...options, agentType });
+  const installation = await installAgentMcp(agentType, options);
+  stdout.write(`${JSON.stringify({ ...installation, authorization_reused: authorizationReused })}\n`);
+}
+
 function assertAssetsDirectoryProvided(args, assetsDirectory) {
   const assetOptions = [
     "--assets-binding",

package/src/constants.mjs

@@ -1,4 +1,4 @@
-export const CLI_VERSION = "0.7.2";
+export const CLI_VERSION = "0.7.3";
 export const DEVICE_CODE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
 export const DEFAULT_AUTH_URL = "https://auth.fargowealth.app";
 export const DEFAULT_API_URL = "https://mcp.fargowealth.app";

package/src/workbuddy-install.mjs

@@ -1,129 +1,12 @@
-import { constants as fsConstants } from "node:fs";
-import { access, mkdir, readFile, rename, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
-import { dirname, isAbsolute, join, resolve } from "node:path";
-import { CLI_VERSION } from "./constants.mjs";
+import { defaultAgentConfigPath } from "./agent-install.mjs";
 
-const PACKAGE_NAME = "@fargowealth/fargo-ai-cli";
+export {
+  defaultAgentConfigPath,
+  installAgentMcp,
+  installWorkBuddyMcp,
+  resolveNpxCommand
+} from "./agent-install.mjs";
 
-export async function installWorkBuddyMcp(options = {}) {
-  const platform = options.platform ?? process.platform;
-  const env = options.env ?? process.env;
-  const homeDirectory = options.home ?? homedir();
-  const configPath = options.configPath
-    ?? env.FARGO_WORKBUDDY_MCP_CONFIG
-    ?? defaultWorkBuddyConfigPath(homeDirectory);
-  const packageSpec = `${PACKAGE_NAME}@${options.packageVersion ?? CLI_VERSION}`;
-  const config = await readConfig(configPath);
-  const npxCommand = options.npxCommand ?? (platform === "darwin"
-    ? await resolveNpxCommand({ env, execPath: options.execPath, platform })
-    : "npx");
-  const nextServer = {
-    type: "stdio",
-    command: npxCommand,
-    args: ["-y", packageSpec, "mcp", "serve"],
-    timeout: 60000
-  };
-  if (platform === "darwin" || platform === "win32") {
-    const credentialDirectory = platform === "win32"
-      ? join(env.APPDATA || homeDirectory, "Fargo AI")
-      : join(homeDirectory, ".fargo");
-    nextServer.env = {
-      FARGO_CREDENTIAL_PATH: join(credentialDirectory, "credentials.json"),
-      FARGO_CREDENTIAL_STORE: "file",
-      FARGO_REFRESH_LOCK_PATH: join(credentialDirectory, "oauth-refresh.lock")
-    };
-    if (platform === "darwin") nextServer.env.PATH = buildMacPath(npxCommand);
-    if (platform === "win32") {
-      const windowsPath = env.PATH ?? env.Path ?? env.path;
-      if (windowsPath) nextServer.env.PATH = windowsPath;
-    }
-  }
-  const previousServer = config.mcpServers?.["fargo-ai"];
-  const changed = JSON.stringify(previousServer) !== JSON.stringify(nextServer);
-
-  if (changed) {
-    config.mcpServers = { ...(config.mcpServers ?? {}), "fargo-ai": nextServer };
-    await writeConfig(configPath, config);
-  }
-
-  return {
-    type: "workbuddy_installation_complete",
-    installed: true,
-    changed,
-    config_path: configPath,
-    server_name: "fargo-ai",
-    package: packageSpec,
-    trust_required: true,
-    next_action: "Open WorkBuddy MCP management, trust and enable fargo-ai, then reload MCP or start a new task."
-  };
-}
-
-export async function resolveNpxCommand(options = {}) {
-  const platform = options.platform ?? process.platform;
-  const env = options.env ?? process.env;
-  const execPath = options.execPath ?? process.execPath;
-  const executableName = platform === "win32" ? "npx.cmd" : "npx";
-  const pathDelimiter = platform === "win32" ? ";" : ":";
-  const candidates = [
-    join(dirname(execPath), executableName),
-    ...String(env.PATH ?? "").split(pathDelimiter).filter(Boolean).map((entry) => join(entry, executableName))
-  ];
-  for (const candidate of candidates) {
-    const absoluteCandidate = isAbsolute(candidate) ? candidate : resolve(candidate);
-    try {
-      await access(absoluteCandidate, platform === "win32" ? fsConstants.F_OK : fsConstants.X_OK);
-      return absoluteCandidate;
-    } catch {
-      // Keep searching for an executable that will also be visible to the GUI host.
-    }
-  }
-  throw new Error("Unable to locate an absolute npx executable for WorkBuddy");
-}
-
-function buildMacPath(npxCommand) {
-  return [...new Set([
-    dirname(npxCommand),
-    "/opt/homebrew/bin",
-    "/usr/local/bin",
-    "/usr/bin",
-    "/bin",
-    "/usr/sbin",
-    "/sbin"
-  ])].join(":");
-}
-
-export function defaultWorkBuddyConfigPath(homeDirectory = homedir()) {
-  return join(homeDirectory, ".workbuddy-ai", "mcp.json");
-}
-
-async function readConfig(configPath) {
-  let text;
-  try {
-    text = await readFile(configPath, "utf8");
-  } catch (error) {
-    if (error?.code === "ENOENT") return {};
-    throw error;
-  }
-  if (!text.trim()) return {};
-  let parsed;
-  try {
-    parsed = JSON.parse(text);
-  } catch {
-    throw new Error(`WorkBuddy MCP config is not valid JSON: ${configPath}`);
-  }
-  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-    throw new Error(`WorkBuddy MCP config must contain a JSON object: ${configPath}`);
-  }
-  if (parsed.mcpServers !== undefined && (!parsed.mcpServers || typeof parsed.mcpServers !== "object" || Array.isArray(parsed.mcpServers))) {
-    throw new Error(`WorkBuddy mcpServers must be a JSON object: ${configPath}`);
-  }
-  return parsed;
-}
-
-async function writeConfig(configPath, config) {
-  await mkdir(dirname(configPath), { recursive: true });
-  const temporaryPath = `${configPath}.${process.pid}.${Date.now()}.tmp`;
-  await writeFile(temporaryPath, `${JSON.stringify(config, null, 2)}\n`, { encoding: "utf8", mode: 0o600, flag: "wx" });
-  await rename(temporaryPath, configPath);
+export function defaultWorkBuddyConfigPath(homeDirectory) {
+  return defaultAgentConfigPath("workbuddy", homeDirectory);
 }