@fargowealth/fargo-ai-cli 0.1.0

package/README.md

@@ -0,0 +1,13 @@
+# Fargo CLI
+
+`fargo-cli` provides WorkBuddy with Device Authorization Grant login and a local stdio bridge to the hosted Fargo AI MCP server.
+
+```sh
+npm install --global @fargowealth/fargo-ai-cli
+fargo auth device --open-browser=always --output=jsonl
+fargo auth status --output=json
+fargo mcp serve
+fargo auth logout
+```
+
+OAuth credentials are stored in macOS Keychain, protected with Windows DPAPI, or written to an owner-only file on Linux.

package/bin/fargo.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runCli } from "../src/cli.mjs";
+
+await runCli(process.argv.slice(2));

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@fargowealth/fargo-ai-cli",
+  "version": "0.1.0",
+  "description": "Fargo AI authentication and stdio MCP bridge for WorkBuddy",
+  "type": "module",
+  "bin": {
+    "fargo": "bin/fargo.mjs",
+    "fargo-cli": "bin/fargo.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/auth.mjs

@@ -0,0 +1,83 @@
+import { spawn } from "node:child_process";
+import { CLI_VERSION, DEFAULT_AUTH_URL, DEFAULT_MCP_URL, DEVICE_CODE_GRANT_TYPE, OAUTH_CLIENT_ID, OAUTH_SCOPE } from "./constants.mjs";
+
+export async function startDeviceAuthorization(options = {}) {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const authUrl = options.authUrl ?? process.env.FARGO_AUTH_URL ?? DEFAULT_AUTH_URL;
+  const mcpUrl = options.mcpUrl ?? process.env.FARGO_MCP_URL ?? DEFAULT_MCP_URL;
+  const response = await fetchImpl(`${authUrl}/v1/mcp/oauth/device_authorization`, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded", "User-Agent": `fargo-cli/${CLI_VERSION} WorkBuddy` },
+    body: new URLSearchParams({ client_id: OAUTH_CLIENT_ID, resource: mcpUrl, scope: OAUTH_SCOPE })
+  });
+  return readOAuthResponse(response);
+}
+
+export async function pollDeviceAuthorization(device, store, options = {}) {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const sleep = options.sleep ?? ((milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)));
+  const authUrl = options.authUrl ?? process.env.FARGO_AUTH_URL ?? DEFAULT_AUTH_URL;
+  let interval = Math.max(1, Number(device.interval) || 5);
+  const expiresAt = Date.now() + Math.max(1, Number(device.expires_in) || 600) * 1000;
+  while (Date.now() < expiresAt) {
+    await sleep(interval * 1000);
+    const response = await fetchImpl(`${authUrl}/v1/mcp/oauth/token`, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded", "User-Agent": `fargo-cli/${CLI_VERSION} WorkBuddy` },
+      body: new URLSearchParams({ grant_type: DEVICE_CODE_GRANT_TYPE, client_id: OAUTH_CLIENT_ID, device_code: device.device_code })
+    });
+    const payload = await response.json().catch(() => ({}));
+    if (response.ok) {
+      const credential = credentialFromToken(payload, authUrl);
+      await store.save(credential);
+      return credential;
+    }
+    if (payload.error === "authorization_pending") continue;
+    if (payload.error === "slow_down") { interval += 5; continue; }
+    throw new Error(payload.error_description || payload.message || payload.error || `Token request failed (${response.status})`);
+  }
+  throw new Error("Device authorization expired");
+}
+
+export async function refreshCredential(store, credential, options = {}) {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const authUrl = credential.auth_url ?? options.authUrl ?? process.env.FARGO_AUTH_URL ?? DEFAULT_AUTH_URL;
+  const response = await fetchImpl(`${authUrl}/v1/mcp/oauth/token`, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded", "User-Agent": `fargo-cli/${CLI_VERSION} WorkBuddy` },
+    body: new URLSearchParams({ grant_type: "refresh_token", client_id: OAUTH_CLIENT_ID, refresh_token: credential.refresh_token })
+  });
+  const payload = await readOAuthResponse(response);
+  const refreshed = credentialFromToken(payload, authUrl);
+  await store.save(refreshed);
+  return refreshed;
+}
+
+export async function currentCredential(store, options = {}) {
+  let credential = await store.load();
+  if (!credential) return undefined;
+  if (!credential.access_token || Number(credential.expires_at) <= Date.now() + 60_000) {
+    credential = await refreshCredential(store, credential, options);
+  }
+  return credential;
+}
+
+export function openBrowser(url, platform = process.platform) {
+  const command = platform === "darwin" ? "open" : platform === "win32" ? "cmd.exe" : "xdg-open";
+  const args = platform === "win32" ? ["/d", "/s", "/c", "start", "", url] : [url];
+  const child = spawn(command, args, { detached: true, stdio: "ignore", windowsHide: true });
+  child.unref();
+}
+
+function credentialFromToken(payload, authUrl) {
+  if (typeof payload.access_token !== "string" || typeof payload.refresh_token !== "string") {
+    throw new Error("OAuth token response did not contain rotating credentials");
+  }
+  return { ...payload, auth_url: authUrl, obtained_at: Date.now(), expires_at: Date.now() + Math.max(1, Number(payload.expires_in) || 3600) * 1000 };
+}
+
+async function readOAuthResponse(response) {
+  const payload = await response.json().catch(() => ({}));
+  if (!response.ok) throw new Error(payload.error_description || payload.message || payload.error || `OAuth request failed (${response.status})`);
+  return payload;
+}

package/src/cli.mjs

@@ -0,0 +1,59 @@
+import { createCredentialStore } from "./credential-store.mjs";
+import { currentCredential, openBrowser, pollDeviceAuthorization, startDeviceAuthorization } from "./auth.mjs";
+import { CLI_VERSION } from "./constants.mjs";
+import { runMcpProxy } from "./mcp-proxy.mjs";
+
+export async function runCli(args, options = {}) {
+  const stdout = options.stdout ?? process.stdout;
+  const stderr = options.stderr ?? process.stderr;
+  const store = options.store ?? createCredentialStore(options.storeOptions);
+  try {
+    if (args[0] === "version" || args[0] === "--version" || args[0] === "-v") {
+      stdout.write(`fargo-cli version ${CLI_VERSION}\n`);
+      return;
+    }
+    if (args[0] === "auth" && args[1] === "device") {
+      const device = await startDeviceAuthorization(options);
+      stdout.write(`${JSON.stringify({
+        type: "device_authorization",
+        user_code: device.user_code,
+        verification_uri: device.verification_uri,
+        verification_uri_complete: device.verification_uri_complete,
+        expires_in: device.expires_in,
+        interval: device.interval
+      })}\n`);
+      const browserMode = optionValue(args, "--open-browser") ?? "auto";
+      if (browserMode !== "never" && options.openBrowser !== false) (options.browserOpener ?? openBrowser)(device.verification_uri_complete || device.verification_uri);
+      await pollDeviceAuthorization(device, store, options);
+      stdout.write(`${JSON.stringify({ type: "authorization_complete", logged_in: true, method: "oauth" })}\n`);
+      return;
+    }
+    if (args[0] === "auth" && args[1] === "status") {
+      const credential = await store.load();
+      stdout.write(`${JSON.stringify({ logged_in: Boolean(credential?.refresh_token), method: credential?.refresh_token ? "oauth" : null, credential_store: store.kind, expires_at: credential?.expires_at ?? null })}\n`);
+      return;
+    }
+    if (args[0] === "auth" && (args[1] === "logout" || args[1] === "revoke")) {
+      await store.clear();
+      stdout.write(`${JSON.stringify({ logged_in: false, method: null })}\n`);
+      return;
+    }
+    if (args[0] === "mcp" && args[1] === "serve") {
+      await currentCredential(store, options);
+      await runMcpProxy(store, options);
+      return;
+    }
+    throw new Error("Usage: fargo auth device|status|logout | fargo mcp serve | fargo version");
+  } catch (error) {
+    stderr.write(`fargo: ${error instanceof Error ? error.message : "unknown error"}\n`);
+    if (options.throwOnError) throw error;
+    process.exitCode = 1;
+  }
+}
+
+function optionValue(args, name) {
+  const inline = args.find((value) => value.startsWith(`${name}=`));
+  if (inline) return inline.slice(name.length + 1);
+  const index = args.indexOf(name);
+  return index >= 0 ? args[index + 1] : undefined;
+}

package/src/constants.mjs

@@ -0,0 +1,6 @@
+export const CLI_VERSION = "0.1.0";
+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_MCP_URL = "https://mcp.fargowealth.app/mcp";
+export const OAUTH_CLIENT_ID = "fargo-cli-workbuddy";
+export const OAUTH_SCOPE = "fargo:forum:read fargo:hub:read fargo:lego:read fargo:knowledge:read";

package/src/credential-store.mjs

@@ -0,0 +1,100 @@
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { spawn } from "node:child_process";
+
+const KEYCHAIN_SERVICE = "com.fargowealth.fargo-cli.oauth";
+
+export function createCredentialStore(options = {}) {
+  const platform = options.platform ?? process.platform;
+  const env = options.env ?? process.env;
+  const home = options.home ?? homedir();
+  const run = options.run ?? runCommand;
+  const filePath = env.FARGO_CREDENTIAL_PATH ?? join(home, ".fargo", "credentials.json");
+  const forceFile = env.FARGO_CREDENTIAL_STORE === "file";
+
+  if (!forceFile && platform === "darwin") {
+    const account = env.USER || env.LOGNAME || "fargo-user";
+    return {
+      kind: "macos-keychain",
+      async load() {
+        const result = await run("security", ["find-generic-password", "-a", account, "-s", KEYCHAIN_SERVICE, "-w"], { allowFailure: true });
+        if (result.code !== 0 || !result.stdout.trim()) return undefined;
+        return parseCredential(result.stdout.trim());
+      },
+      async save(value) {
+        const serialized = JSON.stringify(value);
+        const result = await run("security", ["add-generic-password", "-a", account, "-s", KEYCHAIN_SERVICE, "-w", serialized, "-U"], { allowFailure: true });
+        if (result.code !== 0) throw new Error("Unable to save Fargo credentials in macOS Keychain");
+      },
+      async clear() {
+        await run("security", ["delete-generic-password", "-a", account, "-s", KEYCHAIN_SERVICE], { allowFailure: true });
+      }
+    };
+  }
+
+  if (!forceFile && platform === "win32") {
+    const protectedPath = env.FARGO_CREDENTIAL_PATH ?? join(env.APPDATA || home, "Fargo AI", "credentials.bin");
+    return {
+      kind: "windows-dpapi",
+      async load() {
+        const script = "$p=$env:FARGO_CREDENTIAL_PATH;if(!(Test-Path -LiteralPath $p)){exit 3};$e=[IO.File]::ReadAllBytes($p);$b=[Security.Cryptography.ProtectedData]::Unprotect($e,$null,[Security.Cryptography.DataProtectionScope]::CurrentUser);[Console]::Out.Write([Text.Encoding]::UTF8.GetString($b))";
+        const result = await run("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], { allowFailure: true, env: { ...env, FARGO_CREDENTIAL_PATH: protectedPath } });
+        if (result.code !== 0 || !result.stdout.trim()) return undefined;
+        return parseCredential(result.stdout.trim());
+      },
+      async save(value) {
+        const script = "$p=$env:FARGO_CREDENTIAL_PATH;$d=Split-Path -Parent $p;[IO.Directory]::CreateDirectory($d)|Out-Null;$s=[Console]::In.ReadToEnd();$b=[Text.Encoding]::UTF8.GetBytes($s);$e=[Security.Cryptography.ProtectedData]::Protect($b,$null,[Security.Cryptography.DataProtectionScope]::CurrentUser);[IO.File]::WriteAllBytes($p,$e)";
+        const result = await run("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], { allowFailure: true, env: { ...env, FARGO_CREDENTIAL_PATH: protectedPath }, stdin: JSON.stringify(value) });
+        if (result.code !== 0) throw new Error("Unable to save Fargo credentials with Windows DPAPI");
+      },
+      async clear() {
+        await rm(protectedPath, { force: true });
+      }
+    };
+  }
+
+  return {
+    kind: "private-file",
+    async load() {
+      try {
+        return parseCredential(await readFile(filePath, "utf8"));
+      } catch (error) {
+        if (error?.code === "ENOENT") return undefined;
+        throw error;
+      }
+    },
+    async save(value) {
+      await mkdir(dirname(filePath), { recursive: true, mode: 0o700 });
+      await writeFile(filePath, `${JSON.stringify(value)}\n`, { mode: 0o600 });
+    },
+    async clear() {
+      await rm(filePath, { force: true });
+    }
+  };
+}
+
+function parseCredential(value) {
+  const parsed = JSON.parse(value);
+  if (!parsed || typeof parsed !== "object" || typeof parsed.refresh_token !== "string") {
+    throw new Error("Saved Fargo credential is invalid");
+  }
+  return parsed;
+}
+
+function runCommand(command, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { env: options.env ?? process.env, stdio: ["pipe", "pipe", "pipe"], windowsHide: true });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.setEncoding("utf8").on("data", (chunk) => { stdout += chunk; });
+    child.stderr.setEncoding("utf8").on("data", (chunk) => { stderr += chunk; });
+    child.on("error", reject);
+    child.on("close", (code) => {
+      const result = { code: code ?? 1, stderr, stdout };
+      if (!options.allowFailure && result.code !== 0) reject(new Error(stderr.trim() || `${command} failed`));
+      else resolve(result);
+    });
+    child.stdin.end(options.stdin ?? "");
+  });
+}

package/src/mcp-proxy.mjs

@@ -0,0 +1,56 @@
+import { createInterface } from "node:readline";
+import { CLI_VERSION, DEFAULT_MCP_URL } from "./constants.mjs";
+import { currentCredential, refreshCredential } from "./auth.mjs";
+
+export async function runMcpProxy(store, options = {}) {
+  const input = options.input ?? process.stdin;
+  const output = options.output ?? process.stdout;
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const mcpUrl = options.mcpUrl ?? process.env.FARGO_MCP_URL ?? DEFAULT_MCP_URL;
+  let sessionId;
+  let queue = Promise.resolve();
+  const lines = createInterface({ input, crlfDelay: Infinity });
+  for await (const line of lines) {
+    if (!line.trim()) continue;
+    queue = queue.then(async () => {
+      let message;
+      try { message = JSON.parse(line); }
+      catch { return; }
+      try {
+        const responses = await forward(message, false);
+        for (const response of responses) output.write(`${JSON.stringify(response)}\n`);
+      } catch (error) {
+        if (message.id !== undefined) output.write(`${JSON.stringify({ jsonrpc: "2.0", id: message.id, error: { code: -32001, message: error instanceof Error ? error.message : "Fargo MCP proxy failed" } })}\n`);
+      }
+    });
+  }
+  await queue;
+
+  async function forward(message, didRefresh) {
+    let credential = await currentCredential(store, { fetchImpl });
+    if (!credential) throw new Error("Fargo CLI is not authenticated");
+    const headers = {
+      "Accept": "application/json, text/event-stream",
+      "Authorization": `Bearer ${credential.access_token}`,
+      "Content-Type": "application/json",
+      "MCP-Protocol-Version": "2025-11-25",
+      "User-Agent": `fargo-cli/${CLI_VERSION} WorkBuddy`
+    };
+    if (sessionId) headers["Mcp-Session-Id"] = sessionId;
+    const response = await fetchImpl(mcpUrl, { method: "POST", headers, body: JSON.stringify(message) });
+    if (response.status === 401 && !didRefresh) {
+      credential = await refreshCredential(store, credential, { fetchImpl });
+      return forward(message, true);
+    }
+    if (!response.ok && response.status !== 202) throw new Error(`Fargo MCP returned HTTP ${response.status}`);
+    sessionId = response.headers.get("mcp-session-id") || sessionId;
+    if (response.status === 202 || !response.body) return [];
+    const text = await response.text();
+    if (!text.trim()) return [];
+    if (response.headers.get("content-type")?.includes("text/event-stream")) {
+      return text.split(/\r?\n/).filter((line) => line.startsWith("data:")).map((line) => line.slice(5).trim()).filter(Boolean).map(JSON.parse);
+    }
+    const parsed = JSON.parse(text);
+    return Array.isArray(parsed) ? parsed : [parsed];
+  }
+}