@fargowealth/fargo-ai-cli 0.7.2 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.8.0
+
+- Replaced regex-based D1 migration checks with token-structured parsing that
+  handles comments, literals, identifiers, parentheses, and statement shape.
+- Require `--table-prefix` for every schema and controlled data migration plan
+  and apply; table names, index names, index targets, and foreign-key references
+  must all remain under that App prefix.
+- Preserve the separate approval requirement for controlled data mutations;
+  the hosted service independently derives and verifies the authoritative App
+  prefix before executing the migration as an atomic D1 batch.
+
+## 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.8.0
 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
@@ -143,9 +146,9 @@ Deployment artifacts preserve binary bytes and include
 ## LEGO D1 migrations
 
 ```sh
-# Schema-only migrations keep the existing flow
-fargo lego d1 migrate plan --app app_xxx --dir migrations
-fargo lego d1 migrate apply --app app_xxx --dir migrations
+# Schema-only migrations also require the authoritative local prefix assertion
+fargo lego d1 migrate plan --app app_xxx --dir migrations --table-prefix app_code_
+fargo lego d1 migrate apply --app app_xxx --dir migrations --table-prefix app_code_
 
 # Controlled data migrations: review the reported impact first
 fargo lego d1 migrate plan \
@@ -167,22 +170,26 @@ production registry; `apply` stops on content drift and submits only pending
 files. The plan reports statement types, data-mutation types, target tables,
 and whether separate data-migration approval is required.
 
-Schema DDL remains the default. The opt-in data mode accepts `INSERT ... VALUES`
-with optional `ON CONFLICT`, plus `UPDATE` and `DELETE` only when they contain a
-`WHERE` clause. Data targets must use the server-derived App table prefix;
+Schema DDL remains the default. Every migration command requires
+`--table-prefix`; the token parser applies it to table names, index names, index
+targets, and foreign-key references before MCP is contacted. The opt-in data
+mode accepts `INSERT ... VALUES` with optional `ON CONFLICT`, plus `UPDATE` and
+`DELETE` only when they contain a `WHERE` clause. Data targets must use the server-derived App table prefix;
 system tables, cross-table queries, `PRAGMA`, `ATTACH`, and `DROP` remain
-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.
+blocked. The service independently derives the authoritative prefix and rejects
+a mismatched client assertion. Each migration file executes as one transactional
+D1 batch, server-side and independently from 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.8.0",
   "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;
@@ -112,26 +112,17 @@ export async function runCli(args, options = {}) {
         stdout.write(`${JSON.stringify(await applyLegoMigrations(store, input, options))}\n`);
         return;
       }
-      throw new Error("Usage: fargo lego d1 migrate plan|apply --app <appId> [--dir migrations] [--table-prefix app_prefix_] [--allow-data-migrations]");
+      throw new Error("Usage: fargo lego d1 migrate plan|apply --app <appId> --table-prefix <app_prefix_> [--dir migrations] [--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.8.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";

package/src/lego-migrations.mjs

@@ -3,6 +3,7 @@ import { lstat, opendir, readFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { callMcpTool } from "./mcp-client.mjs";
 import { mcpToolPayload } from "./mcp-result.mjs";
+import { analyzeMigrationStatement, parseMigrationStatements } from "./migration-sql.mjs";
 
 const MAX_MIGRATION_BYTES = 80_000;
 const MAX_MIGRATION_FILES = 500;
@@ -163,166 +164,3 @@ export function analyzeLegoMigrationSql(sql, fileName = "migration.sql", options
 }
 
 export const validateLegoMigrationSql = analyzeLegoMigrationSql;
-
-function parseMigrationStatements(sql) {
-  const statements = [];
-  let current = "";
-  let quote;
-  let blockComment = false;
-  let lineComment = false;
-
-  for (let index = 0; index < sql.length; index += 1) {
-    const char = sql[index];
-    const next = sql[index + 1];
-    if (blockComment) {
-      if (char === "*" && next === "/") {
-        blockComment = false;
-        index += 1;
-      }
-      continue;
-    }
-    if (lineComment) {
-      if (char === "\n") lineComment = false;
-      continue;
-    }
-    if (!quote && char === "/" && next === "*") {
-      blockComment = true;
-      current += " ";
-      index += 1;
-      continue;
-    }
-    if (!quote && char === "-" && next === "-") {
-      lineComment = true;
-      current += " ";
-      index += 1;
-      continue;
-    }
-    if ((char === "'" || char === '"') && sql[index - 1] !== "\\") {
-      quote = quote === char ? undefined : quote ?? char;
-    }
-    if (!quote && char === ";") {
-      const statement = current.trim();
-      if (statement) statements.push(statement);
-      current = "";
-      continue;
-    }
-    current += char;
-  }
-  if (blockComment) throw new Error("Migration SQL contains an unterminated block comment");
-
-  const trailing = current.trim();
-  if (trailing) statements.push(trailing);
-  return statements;
-}
-
-function analyzeMigrationStatement(statement, options = {}) {
-  const normalized = statement.replace(/\s+/g, " ").trim();
-  const createTable = normalized.match(/^CREATE\s+TABLE\s+IF\s+NOT\s+EXISTS\s+([a-zA-Z_][a-zA-Z0-9_]*)\s*\(/i);
-  if (createTable?.[1]) {
-    assertMigrationIdentifier(createTable[1]);
-    assertOwnedReferences(normalized, options.tablePrefix);
-    return { category: "schema", table: createTable[1], type: "create_table" };
-  }
-
-  const createIndex = normalized.match(/^CREATE\s+INDEX\s+IF\s+NOT\s+EXISTS\s+([a-zA-Z_][a-zA-Z0-9_]*)\s+ON\s+([a-zA-Z_][a-zA-Z0-9_]*)\s*\(/i);
-  if (createIndex?.[1] && createIndex[2]) {
-    assertMigrationIdentifier(createIndex[1]);
-    assertMigrationIdentifier(createIndex[2]);
-    return { category: "schema", table: createIndex[2], type: "create_index" };
-  }
-
-  const alterTable = normalized.match(/^ALTER\s+TABLE\s+([a-zA-Z_][a-zA-Z0-9_]*)\s+ADD\s+COLUMN\s+([a-zA-Z_][a-zA-Z0-9_]*)\b/i);
-  if (alterTable?.[1]) {
-    assertMigrationIdentifier(alterTable[1]);
-    assertOwnedReferences(normalized, options.tablePrefix);
-    return { category: "schema", table: alterTable[1], type: "alter_table" };
-  }
-
-  const structure = stripQuotedSql(normalized);
-  if (/^(?:INSERT\s+INTO|UPDATE|DELETE\s+FROM)\s+[a-zA-Z_][a-zA-Z0-9_]*\s*\./i.test(structure)) {
-    throw new Error("Data migrations cannot use qualified table names");
-  }
-  const insert = structure.match(/^INSERT\s+INTO\s+([a-zA-Z_][a-zA-Z0-9_]*)\b/i);
-  if (insert?.[1]) {
-    assertOwnedDataTable(insert[1], options.tablePrefix);
-    assertNoCrossResourceDataQuery(structure, "insert");
-    if (!/\bVALUES\s*\(/i.test(structure)) throw new Error("INSERT data migrations must use VALUES");
-    if (/\bON\s+CONFLICT\b/i.test(structure) && !/\bDO\s+(?:NOTHING|UPDATE\s+SET)\b/i.test(structure)) {
-      throw new Error("INSERT ON CONFLICT must use DO NOTHING or DO UPDATE SET");
-    }
-    return { category: "data", table: insert[1], type: "insert" };
-  }
-
-  const update = structure.match(/^UPDATE\s+([a-zA-Z_][a-zA-Z0-9_]*)\s+SET\s+/i);
-  if (update?.[1]) {
-    assertOwnedDataTable(update[1], options.tablePrefix);
-    if (!/\bWHERE\b/i.test(structure)) throw new Error("UPDATE data migrations must include WHERE");
-    assertNoCrossResourceDataQuery(structure, "update");
-    return { category: "data", table: update[1], type: "update" };
-  }
-
-  const deleteFrom = structure.match(/^DELETE\s+FROM\s+([a-zA-Z_][a-zA-Z0-9_]*)\b/i);
-  if (deleteFrom?.[1]) {
-    assertOwnedDataTable(deleteFrom[1], options.tablePrefix);
-    if (!/\bWHERE\b/i.test(structure)) throw new Error("DELETE data migrations must include WHERE");
-    assertNoCrossResourceDataQuery(structure, "delete");
-    return { category: "data", table: deleteFrom[1], type: "delete" };
-  }
-  throw new Error("Statement type is not allowed");
-}
-
-function assertMigrationIdentifier(identifier) {
-  if (identifier.toLowerCase().startsWith("sqlite_")) {
-    throw new Error("reserved_migration_identifier");
-  }
-}
-
-function assertOwnedDataTable(identifier, tablePrefix) {
-  assertMigrationIdentifier(identifier);
-  const prefix = String(tablePrefix ?? "").trim().toLowerCase();
-  if (prefix && !identifier.toLowerCase().startsWith(prefix)) {
-    throw new Error(`Data table ${identifier} is outside App prefix ${prefix}`);
-  }
-}
-
-function assertOwnedReferences(statement, tablePrefix) {
-  for (const match of statement.matchAll(/\bREFERENCES\s+([a-zA-Z_][a-zA-Z0-9_]*)\b/gi)) {
-    if (match[1]) assertOwnedDataTable(match[1], tablePrefix);
-  }
-}
-
-function assertNoCrossResourceDataQuery(statement, kind) {
-  const forbidden = kind === "delete"
-    ? /\b(?:SELECT|WITH|JOIN|ATTACH|DETACH|PRAGMA|DROP)\b/i
-    : /\b(?:SELECT|WITH|JOIN|FROM|ATTACH|DETACH|PRAGMA|DROP)\b/i;
-  if (forbidden.test(statement)) {
-    throw new Error("Data migrations cannot query other tables or use administrative SQL");
-  }
-}
-
-function stripQuotedSql(value) {
-  let result = "";
-  let quote;
-  for (let index = 0; index < value.length; index += 1) {
-    const char = value[index];
-    if (quote) {
-      if (char === quote) {
-        if (value[index + 1] === quote) {
-          result += "  ";
-          index += 1;
-          continue;
-        }
-        quote = undefined;
-      }
-      result += " ";
-      continue;
-    }
-    if (char === "'" || char === '"') {
-      quote = char;
-      result += " ";
-      continue;
-    }
-    result += char;
-  }
-  return result;
-}

package/src/migration-sql.mjs

@@ -0,0 +1,476 @@
+const ADMINISTRATIVE_KEYWORDS = new Set([
+  "ANALYZE",
+  "ATTACH",
+  "DETACH",
+  "DROP",
+  "PRAGMA",
+  "REINDEX",
+  "VACUUM"
+]);
+const CROSS_TABLE_QUERY_KEYWORDS = new Set(["JOIN", "SELECT", "WITH"]);
+const ALTER_DEFINITION_STATEMENT_KEYWORDS = new Set(["ALTER", "CREATE", "DELETE", "INSERT", "UPDATE"]);
+
+export function parseMigrationStatements(sql) {
+  const statements = [];
+  let current = "";
+  let quote;
+  let bracketIdentifier = false;
+  let blockComment = false;
+  let lineComment = false;
+
+  for (let index = 0; index < sql.length; index += 1) {
+    const char = sql[index];
+    const next = sql[index + 1];
+    if (blockComment) {
+      if (char === "*" && next === "/") {
+        blockComment = false;
+        index += 1;
+      }
+      continue;
+    }
+    if (lineComment) {
+      if (char === "\n") {
+        lineComment = false;
+        current += "\n";
+      }
+      continue;
+    }
+    if (!quote && !bracketIdentifier && char === "/" && next === "*") {
+      blockComment = true;
+      current += " ";
+      index += 1;
+      continue;
+    }
+    if (!quote && !bracketIdentifier && char === "-" && next === "-") {
+      lineComment = true;
+      current += " ";
+      index += 1;
+      continue;
+    }
+    if (!quote && char === "[") {
+      bracketIdentifier = true;
+    } else if (bracketIdentifier && char === "]") {
+      bracketIdentifier = false;
+    } else if (!bracketIdentifier && (char === "'" || char === "\"" || char === "`")) {
+      if (quote === char && next === char) {
+        current += char + next;
+        index += 1;
+        continue;
+      }
+      quote = quote === char ? undefined : quote ?? char;
+    }
+    if (!quote && !bracketIdentifier && char === ";") {
+      const statement = current.trim();
+      if (statement) statements.push(statement);
+      current = "";
+      continue;
+    }
+    current += char;
+  }
+
+  if (blockComment) throw new Error("Migration SQL contains an unterminated block comment");
+  if (quote || bracketIdentifier) throw new Error("Migration SQL contains an unterminated literal or identifier");
+  const trailing = current.trim();
+  if (trailing) statements.push(trailing);
+  return statements;
+}
+
+export function analyzeMigrationStatement(statement, options = {}) {
+  const tablePrefix = normalizeRequiredPrefix(options.tablePrefix);
+  const tokens = tokenizeSql(statement);
+  if (tokens.length === 0) throw new Error("Statement type is not allowed");
+  rejectAdministrativeKeywords(tokens);
+
+  if (isKeyword(tokens[0], "CREATE")) return validateCreate(tokens, tablePrefix);
+  if (isKeyword(tokens[0], "ALTER")) return validateAlterTable(tokens, tablePrefix);
+  if (isKeyword(tokens[0], "INSERT")) return validateInsert(tokens, tablePrefix);
+  if (isKeyword(tokens[0], "UPDATE")) return validateUpdate(tokens, tablePrefix);
+  if (isKeyword(tokens[0], "DELETE")) return validateDelete(tokens, tablePrefix);
+  throw new Error("Statement type is not allowed");
+}
+
+function validateCreate(tokens, tablePrefix) {
+  const cursor = new TokenCursor(tokens);
+  cursor.expectKeyword("CREATE");
+  if (cursor.matchKeyword("TABLE")) {
+    cursor.expectKeyword("IF");
+    cursor.expectKeyword("NOT");
+    cursor.expectKeyword("EXISTS");
+    const table = cursor.readIdentifier();
+    assertOwnedMigrationIdentifier(table, tablePrefix);
+    cursor.expectSymbol("(");
+    const closing = matchingParenIndex(tokens, cursor.position - 1);
+    if (closing !== tokens.length - 1 || closing === cursor.position) throw unsupportedStatement();
+    const definition = tokens.slice(cursor.position, closing);
+    assertOwnedReferences(definition, tablePrefix);
+    assertNoQueryKeywords(definition);
+    return { category: "schema", table, type: "create_table" };
+  }
+  if (cursor.matchKeyword("INDEX")) {
+    cursor.expectKeyword("IF");
+    cursor.expectKeyword("NOT");
+    cursor.expectKeyword("EXISTS");
+    const indexName = cursor.readIdentifier();
+    assertOwnedMigrationIdentifier(indexName, tablePrefix);
+    cursor.expectKeyword("ON");
+    const table = cursor.readIdentifier();
+    assertOwnedMigrationIdentifier(table, tablePrefix);
+    cursor.expectSymbol("(");
+    const closing = matchingParenIndex(tokens, cursor.position - 1);
+    if (closing === cursor.position) throw unsupportedStatement();
+    const trailing = tokens.slice(closing + 1);
+    if (trailing.length > 0 && (!isKeyword(trailing[0], "WHERE") || trailing.length === 1)) {
+      throw unsupportedStatement();
+    }
+    assertNoQueryKeywords(tokens.slice(cursor.position, closing));
+    assertNoQueryKeywords(trailing);
+    return { category: "schema", table, type: "create_index" };
+  }
+  throw unsupportedStatement();
+}
+
+function validateAlterTable(tokens, tablePrefix) {
+  const cursor = new TokenCursor(tokens);
+  cursor.expectKeyword("ALTER");
+  cursor.expectKeyword("TABLE");
+  const table = cursor.readIdentifier();
+  assertOwnedMigrationIdentifier(table, tablePrefix);
+  cursor.expectKeyword("ADD");
+  cursor.expectKeyword("COLUMN");
+  cursor.readIdentifier();
+  if (cursor.done()) throw unsupportedStatement();
+  const definition = tokens.slice(cursor.position);
+  assertOwnedReferences(definition, tablePrefix);
+  assertNoQueryKeywords(definition);
+  if (definition.some((token) => token.kind === "word" && ALTER_DEFINITION_STATEMENT_KEYWORDS.has(token.upper))) {
+    throw unsupportedStatement();
+  }
+  return { category: "schema", table, type: "alter_table" };
+}
+
+function validateInsert(tokens, tablePrefix) {
+  const cursor = new TokenCursor(tokens);
+  cursor.expectKeyword("INSERT");
+  cursor.expectKeyword("INTO");
+  const table = cursor.readIdentifier();
+  assertOwnedMigrationIdentifier(table, tablePrefix);
+  rejectQualifiedTarget(cursor);
+  assertNoDataQueryKeywords(tokens.slice(cursor.position));
+  if (cursor.peekSymbol("(")) cursor.skipBalancedGroup();
+  cursor.expectKeyword("VALUES", "INSERT data migrations must use VALUES");
+  if (!cursor.peekSymbol("(")) throw new Error("INSERT data migrations must use VALUES");
+  cursor.skipBalancedGroup();
+  while (cursor.matchSymbol(",")) {
+    if (!cursor.peekSymbol("(")) throw new Error("INSERT data migrations must use VALUES");
+    cursor.skipBalancedGroup();
+  }
+  if (cursor.done()) return { category: "data", table, type: "insert" };
+  cursor.expectKeyword("ON", "INSERT ON CONFLICT must use DO NOTHING or DO UPDATE SET");
+  cursor.expectKeyword("CONFLICT", "INSERT ON CONFLICT must use DO NOTHING or DO UPDATE SET");
+  if (cursor.peekSymbol("(")) cursor.skipBalancedGroup();
+  if (cursor.matchKeyword("WHERE")) {
+    const doIndex = findTopLevelKeyword(tokens, "DO", cursor.position);
+    if (doIndex <= cursor.position) throw new Error("INSERT ON CONFLICT must use DO NOTHING or DO UPDATE SET");
+    cursor.position = doIndex;
+  }
+  cursor.expectKeyword("DO", "INSERT ON CONFLICT must use DO NOTHING or DO UPDATE SET");
+  if (cursor.matchKeyword("NOTHING")) {
+    if (!cursor.done()) throw new Error("INSERT ON CONFLICT must use DO NOTHING or DO UPDATE SET");
+    return { category: "data", table, type: "insert" };
+  }
+  cursor.expectKeyword("UPDATE", "INSERT ON CONFLICT must use DO NOTHING or DO UPDATE SET");
+  cursor.expectKeyword("SET", "INSERT ON CONFLICT must use DO NOTHING or DO UPDATE SET");
+  if (cursor.done()) throw new Error("INSERT ON CONFLICT must use DO NOTHING or DO UPDATE SET");
+  return { category: "data", table, type: "insert" };
+}
+
+function validateUpdate(tokens, tablePrefix) {
+  const cursor = new TokenCursor(tokens);
+  cursor.expectKeyword("UPDATE");
+  const table = cursor.readIdentifier();
+  assertOwnedMigrationIdentifier(table, tablePrefix);
+  rejectQualifiedTarget(cursor);
+  cursor.expectKeyword("SET");
+  assertNoDataQueryKeywords(tokens.slice(cursor.position));
+  const whereIndex = findTopLevelKeyword(tokens, "WHERE", cursor.position);
+  if (whereIndex < 0 || whereIndex === tokens.length - 1) throw new Error("UPDATE data migrations must include WHERE");
+  if (whereIndex === cursor.position) throw unsupportedStatement();
+  return { category: "data", table, type: "update" };
+}
+
+function validateDelete(tokens, tablePrefix) {
+  const cursor = new TokenCursor(tokens);
+  cursor.expectKeyword("DELETE");
+  cursor.expectKeyword("FROM");
+  const table = cursor.readIdentifier();
+  assertOwnedMigrationIdentifier(table, tablePrefix);
+  rejectQualifiedTarget(cursor);
+  assertNoDataQueryKeywords(tokens.slice(cursor.position));
+  const whereIndex = findTopLevelKeyword(tokens, "WHERE", cursor.position);
+  if (whereIndex < 0 || whereIndex === tokens.length - 1) throw new Error("DELETE data migrations must include WHERE");
+  if (whereIndex !== cursor.position) throw unsupportedStatement();
+  return { category: "data", table, type: "delete" };
+}
+
+function tokenizeSql(statement) {
+  const tokens = [];
+  for (let index = 0; index < statement.length;) {
+    const char = statement[index];
+    if (isWhitespace(char)) {
+      index += 1;
+      continue;
+    }
+    if (isIdentifierStart(char)) {
+      const start = index;
+      index += 1;
+      while (index < statement.length && isIdentifierPart(statement[index])) index += 1;
+      const text = statement.slice(start, index);
+      tokens.push({ kind: "word", text, upper: text.toUpperCase() });
+      continue;
+    }
+    if (isDigit(char) || (char === "." && isDigit(statement[index + 1]))) {
+      const end = readNumberEnd(statement, index);
+      tokens.push({ kind: "number", text: statement.slice(index, end) });
+      index = end;
+      continue;
+    }
+    if (char === "'") {
+      const start = index;
+      index += 1;
+      let terminated = false;
+      while (index < statement.length) {
+        if (statement[index] === "'" && statement[index + 1] === "'") {
+          index += 2;
+          continue;
+        }
+        if (statement[index] === "'") {
+          index += 1;
+          terminated = true;
+          break;
+        }
+        index += 1;
+      }
+      if (!terminated) throw new Error("Migration SQL contains an unterminated literal");
+      tokens.push({ kind: "string", text: statement.slice(start, index) });
+      continue;
+    }
+    if (char === "\"" || char === "`" || char === "[") {
+      throw new Error("Quoted migration identifiers are not allowed");
+    }
+    if (isSymbolStart(char)) {
+      const pair = statement.slice(index, index + 2);
+      const symbol = isTwoCharacterSymbol(pair) ? pair : char;
+      tokens.push({ kind: "symbol", text: symbol });
+      index += symbol.length;
+      continue;
+    }
+    throw new Error("Migration SQL contains an unsupported token");
+  }
+  assertBalancedParentheses(tokens);
+  return tokens;
+}
+
+class TokenCursor {
+  position = 0;
+
+  constructor(tokens) {
+    this.tokens = tokens;
+  }
+
+  done() {
+    return this.position >= this.tokens.length;
+  }
+
+  expectKeyword(keyword, message = "Statement type is not allowed") {
+    if (!this.matchKeyword(keyword)) throw new Error(message);
+  }
+
+  expectSymbol(symbol) {
+    if (!this.matchSymbol(symbol)) throw unsupportedStatement();
+  }
+
+  matchKeyword(keyword) {
+    if (!isKeyword(this.tokens[this.position], keyword)) return false;
+    this.position += 1;
+    return true;
+  }
+
+  matchSymbol(symbol) {
+    if (!this.peekSymbol(symbol)) return false;
+    this.position += 1;
+    return true;
+  }
+
+  peekSymbol(symbol) {
+    const token = this.tokens[this.position];
+    return token?.kind === "symbol" && token.text === symbol;
+  }
+
+  readIdentifier() {
+    const token = this.tokens[this.position];
+    if (token?.kind !== "word") throw unsupportedStatement();
+    this.position += 1;
+    return token.text;
+  }
+
+  skipBalancedGroup() {
+    if (!this.peekSymbol("(")) throw unsupportedStatement();
+    this.position = matchingParenIndex(this.tokens, this.position) + 1;
+  }
+}
+
+function normalizeRequiredPrefix(value) {
+  const prefix = String(value ?? "").trim().toLowerCase();
+  if (!prefix) throw new Error("App D1 migration preflight requires --table-prefix");
+  return prefix;
+}
+
+function assertOwnedMigrationIdentifier(identifier, tablePrefix) {
+  const normalized = identifier.toLowerCase();
+  if (normalized.startsWith("sqlite_")) throw new Error("reserved_migration_identifier");
+  if (!normalized.startsWith(tablePrefix)) {
+    throw new Error(`Migration identifier ${identifier} is outside App prefix ${tablePrefix}`);
+  }
+}
+
+function assertOwnedReferences(tokens, tablePrefix) {
+  for (let index = 0; index < tokens.length; index += 1) {
+    if (!isKeyword(tokens[index], "REFERENCES")) continue;
+    const referenced = tokens[index + 1];
+    if (referenced?.kind !== "word") throw unsupportedStatement();
+    assertOwnedMigrationIdentifier(referenced.text, tablePrefix);
+    if (tokens[index + 2]?.kind === "symbol" && tokens[index + 2]?.text === ".") {
+      throw new Error("Data migrations cannot query other tables or use administrative SQL");
+    }
+  }
+}
+
+function rejectQualifiedTarget(cursor) {
+  if (cursor.peekSymbol(".")) throw new Error("Data migrations cannot use qualified table names");
+}
+
+function rejectAdministrativeKeywords(tokens) {
+  if (tokens.some((token) => token.kind === "word" && ADMINISTRATIVE_KEYWORDS.has(token.upper))) {
+    throw unsupportedStatement();
+  }
+}
+
+function assertNoQueryKeywords(tokens) {
+  if (tokens.some((token) => token.kind === "word" && CROSS_TABLE_QUERY_KEYWORDS.has(token.upper))) {
+    throw new Error("Migrations cannot query other tables");
+  }
+}
+
+function assertNoDataQueryKeywords(tokens) {
+  if (tokens.some((token) => token.kind === "word" && (token.upper === "FROM" || CROSS_TABLE_QUERY_KEYWORDS.has(token.upper)))) {
+    throw new Error("Data migrations cannot query other tables or use administrative SQL");
+  }
+}
+
+function assertBalancedParentheses(tokens) {
+  let depth = 0;
+  for (const token of tokens) {
+    if (token.kind !== "symbol") continue;
+    if (token.text === "(") depth += 1;
+    if (token.text === ")") depth -= 1;
+    if (depth < 0) throw new Error("Migration SQL contains unbalanced parentheses");
+  }
+  if (depth !== 0) throw new Error("Migration SQL contains unbalanced parentheses");
+}
+
+function matchingParenIndex(tokens, openingIndex) {
+  if (tokens[openingIndex]?.kind !== "symbol" || tokens[openingIndex]?.text !== "(") throw unsupportedStatement();
+  let depth = 0;
+  for (let index = openingIndex; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (token.kind !== "symbol") continue;
+    if (token.text === "(") depth += 1;
+    if (token.text === ")") depth -= 1;
+    if (depth === 0) return index;
+  }
+  throw new Error("Migration SQL contains unbalanced parentheses");
+}
+
+function findTopLevelKeyword(tokens, keyword, start) {
+  let depth = 0;
+  for (let index = start; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (token.kind === "symbol" && token.text === "(") {
+      depth += 1;
+      continue;
+    }
+    if (token.kind === "symbol" && token.text === ")") {
+      depth -= 1;
+      continue;
+    }
+    if (depth === 0 && isKeyword(token, keyword)) return index;
+  }
+  return -1;
+}
+
+function readNumberEnd(value, start) {
+  let index = start;
+  if (value[index] === "0" && (value[index + 1] === "x" || value[index + 1] === "X") && isHexDigit(value[index + 2])) {
+    index += 3;
+    while (isHexDigit(value[index])) index += 1;
+    return index;
+  }
+  if (value[index] === ".") index += 1;
+  while (isDigit(value[index])) index += 1;
+  if (value[index] === ".") {
+    index += 1;
+    while (isDigit(value[index])) index += 1;
+  }
+  if (value[index] === "e" || value[index] === "E") {
+    let exponent = index + 1;
+    if (value[exponent] === "+" || value[exponent] === "-") exponent += 1;
+    if (isDigit(value[exponent])) {
+      index = exponent + 1;
+      while (isDigit(value[index])) index += 1;
+    }
+  }
+  return index;
+}
+
+function isIdentifierStart(char) {
+  if (!char) return false;
+  const code = char.charCodeAt(0);
+  return char === "_" || (code >= 65 && code <= 90) || (code >= 97 && code <= 122);
+}
+
+function isIdentifierPart(char) {
+  return isIdentifierStart(char) || isDigit(char);
+}
+
+function isDigit(char) {
+  if (!char) return false;
+  const code = char.charCodeAt(0);
+  return code >= 48 && code <= 57;
+}
+
+function isHexDigit(char) {
+  if (!char) return false;
+  const code = char.charCodeAt(0);
+  return isDigit(char) || (code >= 65 && code <= 70) || (code >= 97 && code <= 102);
+}
+
+function isWhitespace(char) {
+  return char === " " || char === "\t" || char === "\n" || char === "\r" || char === "\f" || char === "\v";
+}
+
+function isSymbolStart(char) {
+  return Boolean(char && "(),.=+-*/%<>!|&~".includes(char));
+}
+
+function isTwoCharacterSymbol(value) {
+  return value === "<=" || value === ">=" || value === "!=" || value === "<>" || value === "=="
+    || value === "||" || value === "<<" || value === ">>";
+}
+
+function isKeyword(token, keyword) {
+  return token?.kind === "word" && token.upper === keyword;
+}
+
+function unsupportedStatement() {
+  return new Error("Statement type is not allowed");
+}

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