@fargowealth/fargo-ai-cli 0.7.1 → 0.7.3

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # 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
+  contract and an executable full-stack example.
+- Worker deploys now fail early for manual `.fargo-assets/`, frontend
+  `index.html` files inside `--deploy-dir`, overlapping module/assets
+  directories, and asset options missing `--assets-dir`.
+- Dry-run deployment summaries now show manifest schema version and separate
+  Worker-module and Static Asset file counts.
+
 ## 0.7.1
 
 - Added Worker Static Assets packaging with explicit asset directory, binding,

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.1
+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
@@ -108,6 +111,18 @@ boolean flag when only selected routes should invoke the Worker first. The
 hosted LEGO publisher uploads the assets and attaches the binding; Cloudflare
 credentials remain server-side.
 
+`.fargo-assets/` is an internal archive directory reserved for Fargo CLI. Do
+not create it, copy frontend files into it, or place browser output inside the
+Worker `--deploy-dir`. Always provide the original frontend build directory
+through `--assets-dir`; the CLI packages it under `.fargo-assets/` and emits the
+required schema v2 metadata. Worker deploys fail early when they contain a
+manual `.fargo-assets/`, a root `index.html`, overlapping deploy/assets
+directories, or asset options without `--assets-dir`.
+
+Run `fargo lego deploy --help` for the complete option list and a full-stack
+Worker example. A dry run reports the manifest schema version and separate
+Worker-module and Static Asset file counts.
+
 Pass `--source-exclude <gitignore-pattern>` once or multiple times when a
 release command must make additional source exclusions explicit. Secure
 defaults already exclude `node_modules/`, build output, credentials, and common
@@ -163,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.1",
+  "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,13 +8,21 @@ 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;
   const stderr = options.stderr ?? process.stderr;
   const store = options.store ?? createCredentialStore(options.storeOptions);
   try {
+    if (isHelpOption(args) && args[0] === "lego" && args[1] === "deploy") {
+      stdout.write(LEGO_DEPLOY_HELP);
+      return;
+    }
+    if ((isHelpOption(args) && args.length === 1) || (args[0] === "help" && args.length === 1)) {
+      stdout.write(ROOT_HELP);
+      return;
+    }
     if (args[0] === "version" || args[0] === "--version" || args[0] === "-v") {
       stdout.write(`fargo-cli version ${CLI_VERSION}\n`);
       return;
@@ -59,6 +67,8 @@ export async function runCli(args, options = {}) {
     }
     if (args[0] === "lego" && args[1] === "deploy") {
       const appId = requiredOption(args, "--app");
+      const assetsDirectory = optionValue(args, "--assets-dir")?.trim();
+      assertAssetsDirectoryProvided(args, assetsDirectory);
       const deployDir = requiredOption(args, "--deploy-dir");
       const target = requiredOption(args, "--target");
       const version = requiredVersionOption(args, "--version", 80);
@@ -68,7 +78,7 @@ export async function runCli(args, options = {}) {
       const result = await deployLocalLegoApp(store, {
         appId,
         assetsBinding: optionValue(args, "--assets-binding"),
-        assetsDirectory: optionValue(args, "--assets-dir"),
+        assetsDirectory,
         assetsHtmlHandling: optionValue(args, "--assets-html-handling"),
         assetsNotFoundHandling: optionValue(args, "--assets-not-found-handling"),
         assetsRunWorkerFirst: workerFirstRoutes.length > 0 ? workerFirstRoutes : args.includes("--assets-run-worker-first"),
@@ -104,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;
@@ -129,6 +130,100 @@ export async function runCli(args, options = {}) {
   }
 }
 
+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
+  lego d1 migrate plan|apply
+  workbuddy install
+  version
+
+Run "fargo lego deploy --help" for deployment options.
+`;
+
+const LEGO_DEPLOY_HELP = `Usage: fargo lego deploy [options]
+
+Required:
+  --app <appId>                 LEGO App ID
+  --deploy-dir <directory>      Built Pages files or Worker modules
+  --target <pages|worker>       Deployment target
+  --version <version>           Release version
+  --name <name>                 Release name
+  --notes <text>                Release notes (or --notes-file <path>)
+
+Source and execution:
+  --source <directory>          Source snapshot root (default: .)
+  --source-exclude <pattern>    Repeatable source exclusion
+  --entrypoint <path>           Default: index.html for Pages, index.js for Worker
+  --skip-source                 Do not upload a source snapshot
+  --dry-run                     Validate and summarize without network writes
+
+Worker Static Assets:
+  --assets-dir <directory>      Built browser assets; required for Worker frontends
+  --assets-binding <name>       Assets binding (default: ASSETS)
+  --assets-html-handling <mode> auto-trailing-slash, force-trailing-slash,
+                                drop-trailing-slash, or none
+  --assets-not-found-handling <mode>
+                                none, 404-page, or single-page-application
+  --assets-run-worker-first     Run the Worker before static asset routing
+  --assets-run-worker-first-route <glob>
+                                Repeatable Worker-first route
+
+Example:
+  fargo lego deploy --app app_xxx --source . \\
+    --deploy-dir .build/worker --target worker --entrypoint index.js \\
+    --assets-dir dist --assets-binding ASSETS \\
+    --assets-not-found-handling single-page-application \\
+    --assets-run-worker-first --version 1.4.0 --name "Full-stack release" \\
+    --notes-file CHANGELOG.md
+
+.fargo-assets/ is an internal archive directory reserved for Fargo CLI.
+Do not create or copy it manually; always pass browser output with --assets-dir.
+`;
+
+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",
+    "--assets-dir",
+    "--assets-html-handling",
+    "--assets-not-found-handling",
+    "--assets-run-worker-first",
+    "--assets-run-worker-first-route"
+  ];
+  if (!assetsDirectory && assetOptions.some((name) => hasOption(args, name))) {
+    throw new Error("Worker Static Assets options require --assets-dir <directory>; .fargo-assets/ is reserved for Fargo CLI and must not be created manually");
+  }
+}
+
+function hasOption(args, name) {
+  return args.some((value) => value === name || value.startsWith(`${name}=`));
+}
+
 async function authorizeWithPkce(args, stdout, store, options) {
   const browserMode = optionValue(args, "--open-browser") ?? "auto";
   await authorizePkce(store, {

package/src/constants.mjs

@@ -1,4 +1,4 @@
-export const CLI_VERSION = "0.7.1";
+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/deployment-artifact.mjs

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { lstat, opendir, readFile } from "node:fs/promises";
-import { basename, extname, join, resolve, sep } from "node:path";
+import { basename, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { strToU8, zipSync } from "fflate";
 import ignore from "ignore";
 
@@ -38,6 +38,7 @@ export async function createDeploymentArtifact(deployDirectory, options = {}) {
   const target = deploymentTarget(options.target);
   const entrypoint = normalizePath(options.entrypoint || (target === "pages" ? "index.html" : "index.js"));
   const assets = normalizeWorkerAssets(options.assets, target);
+  await assertReservedArchiveDirectoryAbsent(root);
   const matcher = ignore().add(DEFAULT_IGNORE_RULES);
   const customRules = await readOptionalText(join(root, ".legodeployignore"));
   if (customRules) matcher.add(customRules);
@@ -45,12 +46,18 @@ export async function createDeploymentArtifact(deployDirectory, options = {}) {
   const candidates = [];
   const skippedSymlinks = [];
   await walk(root, "", matcher, "");
+  if (target === "worker" && candidates.some((file) => file.path === "index.html")) {
+    throw new Error("Worker deployment output contains browser entry file 'index.html'. Keep Worker modules in --deploy-dir and pass frontend output separately with --assets-dir <directory>");
+  }
   if (assets) {
     const assetsRoot = resolve(assets.sourceDirectory);
     const assetsRootStat = await lstat(assetsRoot).catch(() => undefined);
     if (!assetsRootStat?.isDirectory()) {
       throw new Error(`Worker assets output is not a directory: ${assetsRoot}`);
     }
+    if (directoriesOverlap(root, assetsRoot)) {
+      throw new Error("--deploy-dir and --assets-dir must be separate, non-overlapping directories so browser assets are not uploaded as Worker modules");
+    }
     const assetsMatcher = ignore().add(DEFAULT_IGNORE_RULES);
     const assetsIgnore = await readOptionalText(join(assetsRoot, ".assetsignore"));
     if (assetsIgnore) assetsMatcher.add(assetsIgnore);
@@ -161,6 +168,26 @@ export async function createDeploymentArtifact(deployDirectory, options = {}) {
   }
 }
 
+async function assertReservedArchiveDirectoryAbsent(root) {
+  const reservedPath = join(root, WORKER_ASSET_ARCHIVE_DIRECTORY);
+  const reservedStat = await lstat(reservedPath).catch((error) => {
+    if (error?.code === "ENOENT") return undefined;
+    throw error;
+  });
+  if (reservedStat) {
+    throw new Error("Deployment output contains reserved path '.fargo-assets'. Do not create it manually; pass browser output with --assets-dir <directory> and Fargo CLI will package it");
+  }
+}
+
+function directoriesOverlap(left, right) {
+  return isSameOrInside(left, right) || isSameOrInside(right, left);
+}
+
+function isSameOrInside(parent, candidate) {
+  const path = relative(parent, candidate);
+  return path === "" || (!path.startsWith("..") && !isAbsolute(path));
+}
+
 function normalizeWorkerAssets(value, target) {
   if (!value?.sourceDirectory) return undefined;
   if (target !== "worker") throw new Error("Static assets are supported only for Worker deployments");

package/src/lego-deploy-artifacts.mjs

@@ -27,6 +27,10 @@ export async function uploadLegoDeployArtifact(store, input, options = {}) {
 }
 
 export function deploymentArtifactSummary(artifact) {
+  const assetPrefix = artifact.assets ? `${artifact.assets.directory}/` : undefined;
+  const staticAssetFileCount = assetPrefix
+    ? artifact.manifest.files.filter((file) => file.path.startsWith(assetPrefix)).length
+    : 0;
   return {
     archiveName: artifact.archiveName,
     archiveSha256: artifact.archiveSha256,
@@ -35,9 +39,13 @@ export function deploymentArtifactSummary(artifact) {
     contentSha256: artifact.contentSha256,
     contentSizeBytes: artifact.contentSizeBytes,
     entrypoint: artifact.entrypoint,
+    fileBreakdown: artifact.target === "worker"
+      ? { staticAssets: staticAssetFileCount, workerModules: artifact.fileCount - staticAssetFileCount }
+      : { pagesFiles: artifact.fileCount },
     fileCount: artifact.fileCount,
     root: artifact.root,
     skippedSymlinkCount: artifact.skippedSymlinkCount,
+    schemaVersion: artifact.manifest.schemaVersion,
     target: artifact.target
   };
 }

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);
 }