@fargowealth/fargo-ai-cli 0.4.2 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.5.0
+
+- Fargo CLI is now Agent-neutral; PKCE login records Codex, Claude Code,
+  Cursor, or WorkBuddy through `--agent`.
+- Added one-shot `fargo mcp tools` and `fargo mcp call` commands for any
+  shell-capable Agent.
+- Added deterministic LEGO source snapshot upload, list, and download commands
+  with `.legoignore`, secure defaults, SHA-256 manifests, and a 50 MB ZIP limit.
+- WorkBuddy installation remains supported as an adapter over the common CLI.
+
 ## 0.4.2
 
 - Windows no longer calls `chmod` while reading or writing credentials; `%APPDATA%` continues to provide the inherited NTFS user ACL without a sandbox-blocked metadata write.

package/README.md

@@ -1,27 +1,100 @@
-# Fargo CLI for WorkBuddy
+# Fargo AI CLI
 
-`fargo-cli` is the compatibility bridge that connects WorkBuddy to the hosted Fargo AI MCP server. It uses OAuth Authorization Code + PKCE over an ephemeral loopback callback and exposes the remote MCP over local stdio.
+`fargo` is the Agent-neutral command-line client for Fargo AI. Codex, Claude
+Code, Cursor, WorkBuddy, and any Agent that can execute shell commands share
+the same Fargo identity, hosted MCP contracts, and LEGO project operations.
+
+Requires Node.js 20.19 or newer.
+
+## Install or upgrade
 
 ```sh
-npx -y @fargowealth/fargo-ai-cli@latest workbuddy install --open-browser=always --output=jsonl
-npx -y @fargowealth/fargo-ai-cli@latest auth status --output=json
-npx -y @fargowealth/fargo-ai-cli@latest auth logout --output=json
+npm install -g @fargowealth/fargo-ai-cli@0.5.0
+fargo version
 ```
 
-The login opens the shared Fargo AI consent page and returns to `http://127.0.0.1:<random-port>/oauth/callback/...`. The CLI binds only to IPv4 loopback, validates OAuth `state`, uses PKCE S256, closes the listener after the callback, and never prints private OAuth credentials.
+Use the native remote Fargo MCP connection as the default online tool surface.
+Authenticate the CLI separately only when an Agent needs to package or upload
+files from its local workspace:
 
-## Credential storage
+```sh
+fargo auth login --agent codex
+fargo auth login --agent claude-code
+fargo auth login --agent cursor
+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 OAuth state, uses PKCE S256, closes the listener after callback, and
+never prints access or refresh credentials.
 
-- **WorkBuddy on macOS:** `~/.fargo/credentials.json`. WorkBuddy's sandbox blocks both the `security` CLI and native Keychain Services. The CLI therefore uses a private file by default and never asks for Full Disk Access.
-- **WorkBuddy on Windows:** `%APPDATA%\Fargo AI\credentials.json`. WorkBuddy may also restrict DPAPI access, so the CLI uses a user-profile credential file and does not depend on DPAPI.
-- **WorkBuddy on Linux:** `~/.fargo/credentials.json`.
+## MCP boundary
 
-On macOS and Linux, the credential directory is forced to `0700` and the credential file to `0600`. Windows inherits the current user's NTFS ACL from `%APPDATA%`. Writes use an `fsync`-backed temporary file followed by atomic replacement, symbolic-link reads are rejected, and refresh-token rotation is serialized across local CLI processes.
+- MCP is the default for online Fargo resources, status, deployment,
+  publication, rollback, and other business operations.
+- CLI is used when the operation needs the Agent's local filesystem or binary
+  transfer: source walking, exclusions, ZIP creation, hashing, upload, and
+  download.
+- A future `fargo lego deploy --source .` command may compose the two, but it
+  will remain a client-side workflow over the same server deployment contract.
 
-The local file contains an OAuth refresh credential. Do not copy, upload, commit, print, or include it in logs. Use `npx -y @fargowealth/fargo-ai-cli@latest auth logout` to remove it when a device is no longer trusted, and revoke the connection from Fargo AI.
+Agents without native MCP support can use the CLI fallback:
 
-Device Authorization Grant remains available only as an explicit fallback:
+```sh
+fargo mcp tools
+fargo mcp call lego_get_app --args '{"appId":"app_xxx"}'
+fargo mcp call lego_get_app --args-file ./arguments.json
+```
+
+`fargo mcp serve` remains the local stdio bridge for hosts such as WorkBuddy
+that require one. Codex, Claude Code, and Cursor should prefer the remote MCP
+URL and its native OAuth support.
+
+## LEGO source snapshots
 
 ```sh
-npx -y @fargowealth/fargo-ai-cli@latest auth device --open-browser=always --output=jsonl
+fargo lego snapshot upload --app app_xxx --source . --dry-run
+fargo lego snapshot upload --app app_xxx --source . --version v1
+fargo lego snapshot list --app app_xxx
+fargo lego snapshot download --app app_xxx --snapshot snap_xxx
 ```
+
+The CLI applies secure defaults plus `.legoignore`, skips symbolic links,
+creates a deterministic ZIP, calculates SHA-256 digests, and uploads the bytes
+over an authenticated HTTP data path. Archive bytes are not embedded in MCP
+JSON-RPC. The default archive limit is 50 MB.
+
+The ZIP includes `.fargo-snapshot/manifest.json`. Dependencies, VCS data,
+generated output, caches, secrets, previous archives, large video/audio, and
+design-source files are excluded by default. Add project-specific gitignore
+syntax to `.legoignore`.
+
+## WorkBuddy adapter
+
+```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 available only as an explicit
+WorkBuddy fallback:
+
+```sh
+fargo auth device --open-browser=always --output=jsonl
+```
+
+## Credential storage
+
+- macOS and Linux: `~/.fargo/credentials.json`
+- Windows: `%APPDATA%\Fargo AI\credentials.json`
+
+On macOS and Linux, the directory is forced to `0700` and the credential file
+to `0600`. Windows inherits the current user's NTFS ACL from `%APPDATA%`.
+Writes use an `fsync`-backed temporary file followed by atomic replacement,
+symbolic-link reads are rejected, and refresh-token rotation is serialized
+across local CLI processes.
+
+The file contains an OAuth refresh credential. Never copy, upload, commit, or
+print it. Use `fargo auth logout` to remove it and revoke the Fargo connection
+when a device is no longer trusted.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fargowealth/fargo-ai-cli",
-  "version": "0.4.2",
-  "description": "Fargo AI OAuth and stdio MCP bridge for WorkBuddy",
+  "version": "0.5.0",
+  "description": "Agent-neutral Fargo AI CLI, MCP client, and LEGO project tooling",
   "type": "module",
   "bin": {
     "fargo": "bin/fargo.mjs",
@@ -16,6 +16,10 @@
   "engines": {
     "node": ">=20.19.0"
   },
+  "dependencies": {
+    "fflate": "^0.8.2",
+    "ignore": "^7.0.6"
+  },
   "license": "UNLICENSED",
   "publishConfig": {
     "access": "public"

package/src/api-client.mjs

@@ -0,0 +1,42 @@
+import { CLI_VERSION } from "./constants.mjs";
+import { currentCredential, refreshCurrentCredential } from "./auth.mjs";
+
+export async function authenticatedRequest(store, url, init = {}, options = {}) {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  let credential = await currentCredential(store, { ...options, fetchImpl });
+  if (!credential?.access_token) {
+    throw new Error("Fargo CLI is not authenticated. Run 'fargo auth login' first");
+  }
+
+  let response = await send(credential);
+  if (response.status === 401) {
+    credential = await refreshCurrentCredential(store, credential, { ...options, fetchImpl });
+    if (!credential?.access_token) {
+      throw new Error("Fargo CLI authentication expired. Run 'fargo auth login' again");
+    }
+    response = await send(credential);
+  }
+  return response;
+
+  function send(activeCredential) {
+    const headers = new Headers(init.headers);
+    headers.set("Authorization", `Bearer ${activeCredential.access_token}`);
+    headers.set("User-Agent", `fargo-cli/${CLI_VERSION}`);
+    return fetchImpl(url, { ...init, headers });
+  }
+}
+
+export async function responsePayload(response) {
+  const text = await response.text();
+  let payload;
+  try {
+    payload = text.trim() ? JSON.parse(text) : {};
+  } catch {
+    payload = { message: text.trim() };
+  }
+  if (!response.ok) {
+    const message = payload?.message || payload?.error || `Fargo API returned HTTP ${response.status}`;
+    throw new Error(message);
+  }
+  return payload;
+}

package/src/auth.mjs

@@ -1,6 +1,6 @@
 import { spawn } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
-import { CLI_VERSION, DEFAULT_AUTH_URL, DEFAULT_MCP_URL, DEVICE_CODE_GRANT_TYPE, OAUTH_CLIENT_ID, OAUTH_SCOPE } from "./constants.mjs";
+import { CLI_VERSION, DEFAULT_AUTH_URL, DEFAULT_MCP_URL, DEVICE_CODE_GRANT_TYPE, OAUTH_CLIENT_ID, OAUTH_SCOPE, SUPPORTED_AGENT_TYPES } from "./constants.mjs";
 import { createLoopbackReceiver } from "./loopback-receiver.mjs";
 
 export async function authorizePkce(store, options = {}) {
@@ -12,6 +12,8 @@ export async function authorizePkce(store, options = {}) {
   const verifier = random(32).toString("base64url");
   const state = random(32).toString("base64url");
   const challenge = createHash("sha256").update(verifier).digest("base64url");
+  const agentType = normalizeAgentType(options.agentType ?? process.env.FARGO_AGENT ?? "codex");
+  const clientName = agentClientName(agentType);
   const receiver = await (options.loopbackReceiverFactory ?? createLoopbackReceiver)({
     expectedState: state,
     randomBytes: random,
@@ -21,10 +23,10 @@ export async function authorizePkce(store, options = {}) {
   try {
     const registrationResponse = await fetchImpl(metadata.registration_endpoint, {
       method: "POST",
-      headers: { "Content-Type": "application/json", "User-Agent": `fargo-cli/${CLI_VERSION} WorkBuddy` },
+      headers: { "Content-Type": "application/json", "User-Agent": `fargo-cli/${CLI_VERSION}` },
       body: JSON.stringify({
-        agent_type: "workbuddy",
-        client_name: "Fargo CLI for WorkBuddy",
+        agent_type: agentType,
+        client_name: clientName,
         grant_types: ["authorization_code", "refresh_token"],
         redirect_uris: [receiver.redirectUri],
         response_types: ["code"],
@@ -63,7 +65,7 @@ export async function authorizePkce(store, options = {}) {
 
     const tokenResponse = await fetchImpl(metadata.token_endpoint, {
       method: "POST",
-      headers: { "Content-Type": "application/x-www-form-urlencoded", "User-Agent": `fargo-cli/${CLI_VERSION} WorkBuddy` },
+      headers: { "Content-Type": "application/x-www-form-urlencoded", "User-Agent": `fargo-cli/${CLI_VERSION}` },
       body: new URLSearchParams({
         client_id: registration.client_id,
         code,
@@ -74,6 +76,7 @@ export async function authorizePkce(store, options = {}) {
     });
     const payload = await readOAuthResponse(tokenResponse);
     const credential = credentialFromToken(payload, authUrl, {
+      agent_type: agentType,
       authorization_method: "authorization_code_pkce",
       client_id: registration.client_id,
       resource_url: mcpUrl,
@@ -92,7 +95,7 @@ export async function startDeviceAuthorization(options = {}) {
   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` },
+    headers: { "Content-Type": "application/x-www-form-urlencoded", "User-Agent": `fargo-cli/${CLI_VERSION}` },
     body: new URLSearchParams({ client_id: OAUTH_CLIENT_ID, resource: mcpUrl, scope: OAUTH_SCOPE })
   });
   return readOAuthResponse(response);
@@ -108,12 +111,13 @@ export async function pollDeviceAuthorization(device, store, options = {}) {
     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` },
+      headers: { "Content-Type": "application/x-www-form-urlencoded", "User-Agent": `fargo-cli/${CLI_VERSION}` },
       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, {
+        agent_type: "workbuddy",
         authorization_method: "device_flow",
         client_id: OAUTH_CLIENT_ID,
         resource_url: options.mcpUrl ?? process.env.FARGO_MCP_URL ?? DEFAULT_MCP_URL,
@@ -136,11 +140,12 @@ export async function refreshCredential(store, credential, options = {}) {
   const tokenEndpoint = credential.token_endpoint ?? `${authUrl}/v1/mcp/oauth/token`;
   const response = await fetchImpl(tokenEndpoint, {
     method: "POST",
-    headers: { "Content-Type": "application/x-www-form-urlencoded", "User-Agent": `fargo-cli/${CLI_VERSION} WorkBuddy` },
+    headers: { "Content-Type": "application/x-www-form-urlencoded", "User-Agent": `fargo-cli/${CLI_VERSION}` },
     body: new URLSearchParams({ grant_type: "refresh_token", client_id: clientId, refresh_token: credential.refresh_token })
   });
   const payload = await readOAuthResponse(response);
   const refreshed = credentialFromToken(payload, authUrl, {
+    agent_type: credential.agent_type,
     authorization_method: credential.authorization_method,
     client_id: clientId,
     resource_url: credential.resource_url,
@@ -194,6 +199,34 @@ export function browserLaunchCommand(url, platform = process.platform) {
   return { command: platform === "darwin" ? "open" : "xdg-open", args: [url] };
 }
 
+export function normalizeAgentType(value) {
+  const normalized = String(value ?? "").trim().toLowerCase().replaceAll("_", "-");
+  const aliases = {
+    cc: "claude-code",
+    claude: "claude-code",
+    "claude-code": "claude-code",
+    codex: "codex",
+    cursor: "cursor",
+    workbuddy: "workbuddy",
+    "work-buddy": "workbuddy"
+  };
+  const agentType = aliases[normalized];
+  if (!agentType || !SUPPORTED_AGENT_TYPES.includes(agentType)) {
+    throw new Error(`Unsupported Agent '${value}'. Expected: ${SUPPORTED_AGENT_TYPES.join(", ")}`);
+  }
+  return agentType;
+}
+
+function agentClientName(agentType) {
+  const labels = {
+    "claude-code": "Claude Code",
+    codex: "Codex",
+    cursor: "Cursor",
+    workbuddy: "WorkBuddy"
+  };
+  return `Fargo CLI for ${labels[agentType]}`;
+}
+
 function credentialFromToken(payload, authUrl, metadata = {}) {
   if (typeof payload.access_token !== "string" || typeof payload.refresh_token !== "string") {
     throw new Error("OAuth token response did not contain rotating credentials");
@@ -209,7 +242,7 @@ async function readOAuthResponse(response) {
 
 async function discoverOAuthMetadata(authUrl, fetchImpl) {
   const response = await fetchImpl(`${authUrl.replace(/\/+$/, "")}/.well-known/oauth-authorization-server`, {
-    headers: { "Accept": "application/json", "User-Agent": `fargo-cli/${CLI_VERSION} WorkBuddy` }
+    headers: { "Accept": "application/json", "User-Agent": `fargo-cli/${CLI_VERSION}` }
   });
   const metadata = await readOAuthResponse(response);
   for (const field of ["authorization_endpoint", "registration_endpoint", "token_endpoint"]) {

package/src/cli.mjs

@@ -1,6 +1,10 @@
+import { lstat, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
 import { createCredentialStore } from "./credential-store.mjs";
 import { authorizePkce, currentCredential, openBrowser, pollDeviceAuthorization, startDeviceAuthorization } from "./auth.mjs";
 import { CLI_VERSION } from "./constants.mjs";
+import { downloadLegoSourceSnapshot, listLegoSourceSnapshots, uploadLegoSourceSnapshot } from "./lego-snapshots.mjs";
+import { callMcpTool, listMcpTools } from "./mcp-client.mjs";
 import { runMcpProxy } from "./mcp-proxy.mjs";
 import { installWorkBuddyMcp } from "./workbuddy-install.mjs";
 
@@ -23,7 +27,7 @@ export async function runCli(args, options = {}) {
     }
     if (args[0] === "auth" && args[1] === "status") {
       const credential = await store.load();
-      stdout.write(`${JSON.stringify({ logged_in: Boolean(credential?.refresh_token), method: credential?.authorization_method ?? (credential?.refresh_token ? "oauth" : null), credential_store: store.kind, expires_at: credential?.expires_at ?? null })}\n`);
+      stdout.write(`${JSON.stringify({ logged_in: Boolean(credential?.refresh_token), method: credential?.authorization_method ?? (credential?.refresh_token ? "oauth" : null), agent_type: credential?.agent_type ?? null, credential_store: store.kind, expires_at: credential?.expires_at ?? null })}\n`);
       return;
     }
     if (args[0] === "auth" && (args[1] === "logout" || args[1] === "revoke")) {
@@ -36,6 +40,21 @@ export async function runCli(args, options = {}) {
       await runMcpProxy(store, options);
       return;
     }
+    if (args[0] === "mcp" && args[1] === "tools") {
+      stdout.write(`${JSON.stringify(await listMcpTools(store, options))}\n`);
+      return;
+    }
+    if (args[0] === "mcp" && args[1] === "call") {
+      const toolName = args[2]?.trim();
+      if (!toolName || toolName.startsWith("-")) throw new Error("Usage: fargo mcp call <tool> [--args JSON | --args-file PATH]");
+      const toolArgs = await readToolArgs(args);
+      stdout.write(`${JSON.stringify(await callMcpTool(store, toolName, toolArgs, options))}\n`);
+      return;
+    }
+    if (args[0] === "lego" && args[1] === "snapshot") {
+      await runLegoSnapshotCommand(args, stdout, store, options);
+      return;
+    }
     if (args[0] === "workbuddy" && args[1] === "install") {
       let credential = await store.load();
       if (credential) {
@@ -49,11 +68,11 @@ export async function runCli(args, options = {}) {
       if (credential?.authorization_method !== "authorization_code_pkce") {
         credential = undefined;
       }
-      if (!credential?.refresh_token) await authorizeWithPkce(args, stdout, store, options);
+      if (!credential?.refresh_token) await authorizeWithPkce(args, stdout, store, { ...options, agentType: "workbuddy" });
       stdout.write(`${JSON.stringify(await installWorkBuddyMcp(options))}\n`);
       return;
     }
-    throw new Error("Usage: fargo auth login|device|status|logout | fargo workbuddy install | fargo mcp serve | fargo version");
+    throw new Error("Usage: fargo auth login|device|status|logout | fargo mcp serve|tools|call | fargo lego snapshot upload|list|download | fargo workbuddy install | fargo version");
   } catch (error) {
     stderr.write(`fargo: ${error instanceof Error ? error.message : "unknown error"}\n`);
     if (options.throwOnError) throw error;
@@ -65,6 +84,7 @@ async function authorizeWithPkce(args, stdout, store, options) {
   const browserMode = optionValue(args, "--open-browser") ?? "auto";
   await authorizePkce(store, {
     ...options,
+    agentType: options.agentType ?? optionValue(args, "--agent") ?? process.env.FARGO_AGENT ?? "codex",
     openBrowser: browserMode !== "never" && options.openBrowser !== false,
     async onAuthorization(details) {
       stdout.write(`${JSON.stringify({
@@ -79,6 +99,71 @@ async function authorizeWithPkce(args, stdout, store, options) {
   stdout.write(`${JSON.stringify({ type: "authorization_complete", logged_in: true, method: "authorization_code_pkce" })}\n`);
 }
 
+async function runLegoSnapshotCommand(args, stdout, store, options) {
+  const action = args[2];
+  const appId = requiredOption(args, "--app");
+  if (action === "upload") {
+    const result = await uploadLegoSourceSnapshot(store, {
+      appId,
+      dryRun: args.includes("--dry-run"),
+      source: optionValue(args, "--source") ?? ".",
+      version: optionValue(args, "--version")
+    }, options);
+    stdout.write(`${JSON.stringify(result)}\n`);
+    return;
+  }
+  if (action === "list") {
+    stdout.write(`${JSON.stringify(await listLegoSourceSnapshots(store, appId, options))}\n`);
+    return;
+  }
+  if (action === "download") {
+    const snapshotId = requiredOption(args, "--snapshot");
+    const result = await downloadLegoSourceSnapshot(store, { appId, snapshotId }, options);
+    const outputPath = resolve(optionValue(args, "--output") ?? result.fileName);
+    if (!args.includes("--force") && await pathExists(outputPath)) {
+      throw new Error(`Output file already exists: ${outputPath}. Pass --force to replace it`);
+    }
+    await mkdir(dirname(outputPath), { recursive: true });
+    await writeFile(outputPath, result.archive);
+    stdout.write(`${JSON.stringify({ archiveSha256: result.archiveSha256, outputPath, sizeBytes: result.archive.byteLength, snapshotId })}\n`);
+    return;
+  }
+  throw new Error("Usage: fargo lego snapshot upload|list|download --app <appId>");
+}
+
+async function readToolArgs(args) {
+  const inline = optionValue(args, "--args");
+  const file = optionValue(args, "--args-file");
+  if (inline && file) throw new Error("Use only one of --args or --args-file");
+  const text = file ? await readFile(resolve(file), "utf8") : inline ?? "{}";
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    throw new Error("MCP tool arguments must be valid JSON");
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("MCP tool arguments must be a JSON object");
+  }
+  return value;
+}
+
+async function pathExists(path) {
+  try {
+    await lstat(path);
+    return true;
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+function requiredOption(args, name) {
+  const value = optionValue(args, name)?.trim();
+  if (!value) throw new Error(`Missing required option ${name}`);
+  return value;
+}
+
 async function authorizeDevice(args, stdout, store, options) {
   const device = await startDeviceAuthorization(options);
   stdout.write(`${JSON.stringify({

package/src/constants.mjs

@@ -1,6 +1,8 @@
-export const CLI_VERSION = "0.4.2";
+export const CLI_VERSION = "0.5.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_API_URL = "https://mcp.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:forum:write fargo:hub:read fargo:lego:read fargo:lego:write fargo:knowledge:read fargo:knowledge:write fargo:knowledge:share";
+export const SUPPORTED_AGENT_TYPES = ["codex", "claude-code", "cursor", "workbuddy"];

package/src/credential-store.mjs

@@ -10,10 +10,10 @@ export function createCredentialStore(options = {}) {
   const home = options.home ?? homedir();
   const storeKind = env.FARGO_CREDENTIAL_STORE;
   if (storeKind === "keychain") {
-    throw new Error("FARGO_CREDENTIAL_STORE=keychain is not supported by the WorkBuddy CLI; use file on macOS");
+    throw new Error("FARGO_CREDENTIAL_STORE=keychain is not supported by Fargo CLI; use file on macOS");
   }
   if (storeKind === "dpapi") {
-    throw new Error("FARGO_CREDENTIAL_STORE=dpapi is not supported by the WorkBuddy CLI; use file on Windows");
+    throw new Error("FARGO_CREDENTIAL_STORE=dpapi is not supported by Fargo CLI; use file on Windows");
   }
   if (storeKind && storeKind !== "file") {
     throw new Error(`Unsupported FARGO_CREDENTIAL_STORE: ${storeKind}`);

package/src/lego-snapshots.mjs

@@ -0,0 +1,75 @@
+import { DEFAULT_API_URL } from "./constants.mjs";
+import { authenticatedRequest, responsePayload } from "./api-client.mjs";
+import { createSourceSnapshot } from "./source-snapshot.mjs";
+
+export async function uploadLegoSourceSnapshot(store, input, options = {}) {
+  const snapshot = await createSourceSnapshot(input.source ?? ".", options.snapshotOptions);
+  if (input.dryRun) {
+    return { dryRun: true, snapshot: snapshotSummary(snapshot) };
+  }
+
+  const url = snapshotCollectionUrl(input.appId, options);
+  if (input.version) url.searchParams.set("version", input.version);
+  const response = await authenticatedRequest(store, url, {
+    method: "POST",
+    headers: {
+      Accept: "application/json",
+      "Content-Type": "application/zip",
+      "Content-Length": String(snapshot.archive.byteLength),
+      "X-Fargo-Source-Archive-Sha256": snapshot.archiveSha256,
+      "X-Fargo-Source-Content-Sha256": snapshot.contentSha256,
+      "X-Fargo-Source-File-Count": String(snapshot.fileCount),
+      "X-Fargo-Source-Size": String(snapshot.sourceSizeBytes)
+    },
+    body: snapshot.archive
+  }, options);
+  const payload = await responsePayload(response);
+  return {
+    ...payload,
+    local: snapshotSummary(snapshot)
+  };
+}
+
+export async function listLegoSourceSnapshots(store, appId, options = {}) {
+  const response = await authenticatedRequest(store, snapshotCollectionUrl(appId, options), {
+    headers: { Accept: "application/json" }
+  }, options);
+  return responsePayload(response);
+}
+
+export async function downloadLegoSourceSnapshot(store, input, options = {}) {
+  const base = snapshotCollectionUrl(input.appId, options);
+  base.pathname = `${base.pathname}/${encodeURIComponent(input.snapshotId)}/download`;
+  const response = await authenticatedRequest(store, base, {
+    headers: { Accept: "application/zip" }
+  }, options);
+  if (!response.ok) await responsePayload(response);
+  return {
+    archive: new Uint8Array(await response.arrayBuffer()),
+    archiveSha256: response.headers.get("x-fargo-source-archive-sha256") ?? undefined,
+    fileName: responseFileName(response) ?? `${input.appId}-${input.snapshotId}.zip`
+  };
+}
+
+function snapshotCollectionUrl(appId, options) {
+  const apiUrl = (options.apiUrl ?? process.env.FARGO_API_URL ?? DEFAULT_API_URL).replace(/\/+$/, "");
+  return new URL(`${apiUrl}/api/lego/apps/${encodeURIComponent(appId)}/source-snapshots`);
+}
+
+function snapshotSummary(snapshot) {
+  return {
+    archiveName: snapshot.archiveName,
+    archiveSha256: snapshot.archiveSha256,
+    archiveSizeBytes: snapshot.archive.byteLength,
+    contentSha256: snapshot.contentSha256,
+    fileCount: snapshot.fileCount,
+    root: snapshot.root,
+    skippedSymlinkCount: snapshot.skippedSymlinkCount,
+    sourceSizeBytes: snapshot.sourceSizeBytes
+  };
+}
+
+function responseFileName(response) {
+  const disposition = response.headers.get("content-disposition") ?? "";
+  return disposition.match(/filename="([^"]+)"/i)?.[1];
+}

package/src/loopback-receiver.mjs

@@ -25,7 +25,7 @@ export async function createLoopbackReceiver(options = {}) {
     }
     if (settled) {
       response.writeHead(409, secureHtmlHeaders());
-      response.end(completionPage(false, "这次授权回调已经处理，请返回 WorkBuddy。"));
+      response.end(completionPage(false, "这次授权回调已经处理，请返回发起授权的 Agent。"));
       return;
     }
     settled = true;

package/src/mcp-client.mjs

@@ -0,0 +1,34 @@
+import { DEFAULT_MCP_URL } from "./constants.mjs";
+import { authenticatedRequest, responsePayload } from "./api-client.mjs";
+
+export async function listMcpTools(store, options = {}) {
+  const result = await mcpRequest(store, "tools/list", {}, options);
+  return result;
+}
+
+export async function callMcpTool(store, name, args, options = {}) {
+  return mcpRequest(store, "tools/call", { name, arguments: args }, options);
+}
+
+async function mcpRequest(store, method, params, options) {
+  const mcpUrl = options.mcpUrl ?? process.env.FARGO_MCP_URL ?? DEFAULT_MCP_URL;
+  const response = await authenticatedRequest(store, mcpUrl, {
+    method: "POST",
+    headers: {
+      Accept: "application/json",
+      "Content-Type": "application/json",
+      "MCP-Protocol-Version": "2025-06-18"
+    },
+    body: JSON.stringify({
+      jsonrpc: "2.0",
+      id: crypto.randomUUID(),
+      method,
+      params
+    })
+  }, options);
+  const rpc = await responsePayload(response);
+  if (rpc.error) {
+    throw new Error(rpc.error.message || "Fargo MCP request failed");
+  }
+  return rpc.result ?? {};
+}

package/src/mcp-proxy.mjs

@@ -34,7 +34,7 @@ export async function runMcpProxy(store, options = {}) {
       "Authorization": `Bearer ${credential.access_token}`,
       "Content-Type": "application/json",
       "MCP-Protocol-Version": "2025-11-25",
-      "User-Agent": `fargo-cli/${CLI_VERSION} WorkBuddy`
+      "User-Agent": `fargo-cli/${CLI_VERSION}`
     };
     if (sessionId) headers["Mcp-Session-Id"] = sessionId;
     const response = await fetchImpl(mcpUrl, { method: "POST", headers, body: JSON.stringify(message) });

package/src/source-snapshot.mjs

@@ -0,0 +1,184 @@
+import { createHash } from "node:crypto";
+import { lstat, opendir, readFile } from "node:fs/promises";
+import { basename, join, resolve, sep } from "node:path";
+import { strToU8, zipSync } from "fflate";
+import ignore from "ignore";
+
+export const MAX_ARCHIVE_BYTES = 50_000_000;
+export const MAX_FILE_BYTES = 20_000_000;
+export const MAX_FILE_COUNT = 10_000;
+export const MAX_SOURCE_BYTES = 100_000_000;
+
+export const DEFAULT_IGNORE_RULES = [
+  ".git/",
+  "node_modules/",
+  "dist/",
+  "build/",
+  ".next/",
+  ".nuxt/",
+  ".cache/",
+  ".turbo/",
+  ".wrangler/",
+  "coverage/",
+  ".fargo-snapshot/",
+  ".DS_Store",
+  "Thumbs.db",
+  "*.log",
+  "*.zip",
+  "*.tar",
+  "*.tar.gz",
+  "*.tgz",
+  ".env",
+  ".env.*",
+  "!.env.example",
+  "!.env.sample",
+  "!.env.template",
+  ".npmrc",
+  ".pypirc",
+  "*.pem",
+  "*.key",
+  "id_rsa*",
+  "credentials*.json",
+  "*.mp4",
+  "*.mov",
+  "*.avi",
+  "*.mkv",
+  "*.webm",
+  "*.mp3",
+  "*.wav",
+  "*.flac",
+  "*.psd",
+  "*.sketch"
+];
+
+const FIXED_ZIP_DATE = new Date(1980, 0, 1, 0, 0, 0, 0);
+const MANIFEST_PATH = ".fargo-snapshot/manifest.json";
+
+export async function createSourceSnapshot(sourceDirectory, options = {}) {
+  const root = resolve(sourceDirectory || ".");
+  const rootStat = await lstat(root).catch(() => undefined);
+  if (!rootStat?.isDirectory()) {
+    throw new Error(`Snapshot source is not a directory: ${root}`);
+  }
+
+  const matcher = ignore().add(DEFAULT_IGNORE_RULES);
+  const customRules = await readOptionalText(join(root, ".legoignore"));
+  if (customRules) matcher.add(customRules);
+
+  const sourceFiles = [];
+  const skippedSymlinks = [];
+  await walk(root, "");
+  sourceFiles.sort((left, right) => compareText(left.path, right.path));
+  if (sourceFiles.length === 0) {
+    throw new Error("No source files remain after applying snapshot exclusions");
+  }
+
+  const files = [];
+  let sourceSizeBytes = 0;
+  const contentHash = createHash("sha256");
+  const archiveEntries = {};
+  for (const file of sourceFiles) {
+    const bytes = await readFile(file.absolutePath);
+    const sha256 = digest(bytes);
+    sourceSizeBytes += bytes.byteLength;
+    if (sourceSizeBytes > (options.maxSourceBytes ?? MAX_SOURCE_BYTES)) {
+      throw new Error(`Snapshot source exceeds ${formatBytes(options.maxSourceBytes ?? MAX_SOURCE_BYTES)}; add generated or media files to .legoignore`);
+    }
+    const item = { path: file.path, sha256, sizeBytes: bytes.byteLength };
+    files.push(item);
+    contentHash.update(item.path).update("\0").update(String(item.sizeBytes)).update("\0").update(item.sha256).update("\n");
+    archiveEntries[item.path] = [bytes, { level: 6, mtime: FIXED_ZIP_DATE }];
+  }
+
+  const contentSha256 = contentHash.digest("hex");
+  const manifest = {
+    schemaVersion: 1,
+    kind: "fargo-lego-source-snapshot",
+    archiveFormat: "zip",
+    contentSha256,
+    fileCount: files.length,
+    sourceSizeBytes,
+    files
+  };
+  archiveEntries[MANIFEST_PATH] = [strToU8(`${JSON.stringify(manifest, null, 2)}\n`), { level: 6, mtime: FIXED_ZIP_DATE }];
+  const archive = zipSync(archiveEntries, { level: 6, mtime: FIXED_ZIP_DATE });
+  const maxArchiveBytes = options.maxArchiveBytes ?? MAX_ARCHIVE_BYTES;
+  if (archive.byteLength > maxArchiveBytes) {
+    throw new Error(`Snapshot archive is ${formatBytes(archive.byteLength)}, above the ${formatBytes(maxArchiveBytes)} limit; update .legoignore`);
+  }
+
+  return {
+    archive,
+    archiveName: `${safeFileName(basename(root))}-${contentSha256.slice(0, 12)}.zip`,
+    archiveSha256: digest(archive),
+    contentSha256,
+    fileCount: files.length,
+    manifest,
+    root,
+    skippedSymlinkCount: skippedSymlinks.length,
+    sourceSizeBytes
+  };
+
+  async function walk(absoluteDirectory, relativeDirectory) {
+    const directory = await opendir(absoluteDirectory);
+    const entries = [];
+    for await (const entry of directory) entries.push(entry);
+    entries.sort((left, right) => compareText(left.name, right.name));
+
+    for (const entry of entries) {
+      const relativePath = normalizePath(relativeDirectory ? `${relativeDirectory}/${entry.name}` : entry.name);
+      const absolutePath = join(absoluteDirectory, entry.name);
+      if (entry.isSymbolicLink()) {
+        skippedSymlinks.push(relativePath);
+        continue;
+      }
+      if (entry.isDirectory()) {
+        if (!matcher.ignores(`${relativePath}/`)) await walk(absolutePath, relativePath);
+        continue;
+      }
+      if (!entry.isFile() || matcher.ignores(relativePath)) continue;
+      if (relativePath === MANIFEST_PATH) continue;
+
+      const stat = await lstat(absolutePath);
+      const maxFileBytes = options.maxFileBytes ?? MAX_FILE_BYTES;
+      if (stat.size > maxFileBytes) {
+        throw new Error(`Source file '${relativePath}' is ${formatBytes(stat.size)}, above the ${formatBytes(maxFileBytes)} per-file limit; add it to .legoignore or raise the limit explicitly`);
+      }
+      sourceFiles.push({ absolutePath, path: relativePath });
+      if (sourceFiles.length > (options.maxFileCount ?? MAX_FILE_COUNT)) {
+        throw new Error(`Snapshot contains more than ${options.maxFileCount ?? MAX_FILE_COUNT} files; check dependency and build-output exclusions`);
+      }
+    }
+  }
+}
+
+function digest(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function compareText(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function normalizePath(value) {
+  return value.split(sep).join("/").replace(/^\.\//, "");
+}
+
+async function readOptionalText(path) {
+  try {
+    return await readFile(path, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return "";
+    throw error;
+  }
+}
+
+function safeFileName(value) {
+  return value.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "source";
+}
+
+export function formatBytes(value) {
+  if (value < 1_000) return `${value} B`;
+  if (value < 1_000_000) return `${(value / 1_000).toFixed(1)} KB`;
+  return `${(value / 1_000_000).toFixed(1)} MB`;
+}