@fargowealth/fargo-ai-cli 1.2.1 → 1.4.0

package/src/cli.mjs

@@ -9,6 +9,7 @@ import { applyLegoMigrations, planLegoMigrations } from "./lego-migrations.mjs";
 import { callMcpTool, listMcpTools } from "./mcp-client.mjs";
 import { runMcpProxy } from "./mcp-proxy.mjs";
 import { installAgentMcp } from "./agent-install.mjs";
+import { runWebsiteCommand } from "./website-cli.mjs";
 
 export async function runCli(args, options = {}) {
   const stdout = options.stdout ?? process.stdout;
@@ -61,6 +62,10 @@ export async function runCli(args, options = {}) {
       stdout.write(`${JSON.stringify(await callMcpTool(store, toolName, toolArgs, options))}\n`);
       return;
     }
+    if (args[0] === "website") {
+      await runWebsiteCommand(args, stdout, store, options);
+      return;
+    }
     if (args[0] === "lego" && args[1] === "snapshot") {
       await runLegoSnapshotCommand(args, stdout, store, options);
       return;
@@ -126,7 +131,7 @@ export async function runCli(args, options = {}) {
       await installAgentConnection(args, "workbuddy", stdout, store, options);
       return;
     }
-    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");
+    throw new Error("Usage: fargo auth login|device|status|logout | fargo agent install --agent <agent> | fargo mcp serve|tools|call | fargo website validate|release|list|operations|call|connect|sync|connection-status|authorize|authorize-complete|binding | 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;
@@ -140,6 +145,7 @@ Commands:
   auth login|device|status|logout
   agent install --agent <codex|claude-code|cursor|workbuddy>
   mcp serve|tools|call
+  website validate|release|list|operations|call|connect|sync|connection-status|authorize|authorize-complete|binding
   lego snapshot upload|list|download
   lego deploy
   lego d1 migrate plan|apply
@@ -157,8 +163,7 @@ Required:
   --target <pages|worker>       Deployment target
   --version <version>           Release version
   --name <name>                 Release name
-  --notes <text>                One release's notes, maximum 4000 characters
-  --notes-file <path>           Read one release's notes from a file; same limit
+  --notes <text>                Release notes (or --notes-file <path>)
 
 Source and execution:
   --source <directory>          Source snapshot root (default: .)
@@ -189,18 +194,13 @@ Worker Runtime Topology:
   --queue-max-concurrency <n>   Optional maximum concurrent consumers
   --queue-retry-delay <s>       Optional retry delay in seconds
 
-Result and publication:
-  This command creates a ready, unpublished deployment. Production traffic is
-  unchanged. After review and explicit approval, publish the returned deployment
-  with Fargo Pass MCP lego_deployment_release(action=publish).
-
 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 RELEASE_NOTES.md
+    --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.

package/src/constants.mjs

@@ -1,4 +1,4 @@
-export const CLI_VERSION = "1.2.1";
+export const CLI_VERSION = "1.4.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/website-browser-profile.mjs

@@ -0,0 +1,377 @@
+import { spawn } from "node:child_process";
+import { access, chmod, mkdir, readFile, readdir, unlink } from "node:fs/promises";
+import { homedir, platform } from "node:os";
+import { delimiter, join, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+
+export const WEBSITE_BROWSER_PROFILE_SCHEMA_VERSION = "fargo.browser-profile/v1";
+
+export async function captureLocalWebsiteProfile(spec, options = {}) {
+  const captureSpec = parseCaptureSpec(spec);
+  const profileDirectory = resolve(options.profileDirectory ?? defaultLocalWebsiteProfileDirectory(captureSpec.connectorId, {
+    ...options,
+    profileKey: captureSpec.localProfileKey
+  }));
+  await mkdir(profileDirectory, { recursive: true, mode: 0o700 });
+  if (platform() !== "win32") await chmod(profileDirectory, 0o700);
+  const chromePath = await findChromeExecutable(options.chromePath, options);
+  const activePortPath = join(profileDirectory, "DevToolsActivePort");
+  await unlink(activePortPath).catch((error) => {
+    if (error?.code !== "ENOENT") throw error;
+  });
+  const child = spawn(chromePath, [
+    "--remote-debugging-address=127.0.0.1",
+    "--remote-debugging-port=0",
+    `--user-data-dir=${profileDirectory}`,
+    ...(options.headless ? ["--headless=new"] : []),
+    "--no-first-run",
+    "--no-default-browser-check",
+    "--new-window",
+    captureSpec.loginUrl
+  ], { stdio: "ignore" });
+  let client;
+  try {
+    const endpoint = await waitForDevToolsEndpoint(activePortPath, child, options);
+    client = await CdpClient.connect(endpoint);
+    const sessionId = await pageSession(client, captureSpec);
+    if (!options.noPrompt) await waitForLoginConfirmation(captureSpec, options);
+    else await delay(boundedInteger(options.settleMs, 3_000, 0, 60_000));
+    const cookies = await browserCookies(client);
+    const origins = await originStorage(client, sessionId, captureSpec);
+    return buildWebsiteBrowserProfile(captureSpec, { cookies, origins }, options.now?.() ?? new Date());
+  } finally {
+    if (client) await client.call("Browser.close").catch(() => {});
+    await waitForExit(child, 5_000).catch(() => child.kill("SIGTERM"));
+  }
+}
+
+export function buildWebsiteBrowserProfile(spec, state, capturedAt = new Date()) {
+  const captureSpec = parseCaptureSpec(spec);
+  const allowedHosts = captureSpec.allowedOrigins.map((origin) => new URL(origin).hostname.toLowerCase());
+  const cookies = captureSpec.auth.sendCookies
+    ? array(state.cookies).filter((cookie) => cookieAllowed(cookie.domain, allowedHosts)).map(normalizeCookie)
+    : [];
+  const suffixesByOrigin = new Map();
+  for (const source of captureSpec.auth.headerSources) {
+    const suffixes = suffixesByOrigin.get(source.origin) ?? new Set();
+    suffixes.add(source.keySuffix);
+    suffixesByOrigin.set(source.origin, suffixes);
+  }
+  const origins = array(state.origins).flatMap((entry) => {
+    const origin = String(entry.origin || "");
+    const suffixes = suffixesByOrigin.get(origin);
+    if (!suffixes) return [];
+    const localStorage = array(entry.localStorage).filter((item) => (
+      [...suffixes].some((suffix) => String(item.name || "").endsWith(suffix))
+    )).map((item) => ({ name: String(item.name), value: String(item.value) }));
+    return localStorage.length > 0 ? [{ localStorage, origin }] : [];
+  });
+  return {
+    capturedAt: new Date(capturedAt).toISOString(),
+    connectorId: captureSpec.connectorId,
+    cookies,
+    origins,
+    schemaVersion: WEBSITE_BROWSER_PROFILE_SCHEMA_VERSION
+  };
+}
+
+export function defaultLocalWebsiteProfileDirectory(connectorId, options = {}) {
+  const safeId = requiredConnectorId(connectorId);
+  const profileKey = typeof options.profileKey === "string" && /^bgc_[A-Za-z0-9_-]{43}$/.test(options.profileKey)
+    ? options.profileKey
+    : "default";
+  const currentPlatform = options.platform ?? platform();
+  const homeDirectory = options.home ?? homedir();
+  if (currentPlatform === "darwin") {
+    return join(homeDirectory, "Library", "Application Support", "Fargo AI", "Website Profiles", safeId, profileKey);
+  }
+  if (currentPlatform === "win32") {
+    return join(options.appData ?? process.env.APPDATA ?? join(homeDirectory, "AppData", "Roaming"), "Fargo AI", "Website Profiles", safeId, profileKey);
+  }
+  return join(options.xdgConfigHome ?? process.env.XDG_CONFIG_HOME ?? join(homeDirectory, ".config"), "fargo", "website-profiles", safeId, profileKey);
+}
+
+export async function resolveLocalWebsiteProfileDirectory(connectorId, options = {}) {
+  if (options.profileDirectory) return resolve(options.profileDirectory);
+  const fallback = defaultLocalWebsiteProfileDirectory(connectorId, options);
+  const connectorDirectory = resolve(fallback, "..");
+  let entries;
+  try {
+    entries = await readdir(connectorDirectory, { withFileTypes: true });
+  } catch (error) {
+    if (error?.code === "ENOENT") return fallback;
+    throw error;
+  }
+  const connectionProfiles = entries
+    .filter((entry) => entry.isDirectory() && /^bgc_[A-Za-z0-9_-]{43}$/.test(entry.name))
+    .map((entry) => join(connectorDirectory, entry.name));
+  if (connectionProfiles.length === 0) return fallback;
+  if (connectionProfiles.length === 1) return connectionProfiles[0];
+  throw new Error(`Multiple local Profiles exist for ${connectorId}; pass --profile-dir <path>`);
+}
+
+export function documentIsReadyAtOrigin(value, expectedOrigin) {
+  if (!["interactive", "complete"].includes(value?.readyState)) return false;
+  try {
+    return new URL(value.url).origin === expectedOrigin;
+  } catch {
+    return false;
+  }
+}
+
+export function parseCaptureSpec(value) {
+  const source = record(value, "Website Profile capture spec is invalid");
+  if (source.profileSchemaVersion !== WEBSITE_BROWSER_PROFILE_SCHEMA_VERSION) throw new Error("Website Profile schema is not supported");
+  const connectorId = requiredConnectorId(source.connectorId);
+  const allowedOrigins = array(source.allowedOrigins).map(exactHttpsOrigin);
+  if (allowedOrigins.length < 1 || allowedOrigins.length > 12 || new Set(allowedOrigins).size !== allowedOrigins.length) {
+    throw new Error("Website Profile allowed origins are invalid");
+  }
+  const loginUrl = new URL(String(source.loginUrl || ""));
+  if (loginUrl.protocol !== "https:" || !allowedOrigins.includes(loginUrl.origin) || loginUrl.username || loginUrl.password) {
+    throw new Error("Website Profile login URL is invalid");
+  }
+  const auth = record(source.auth, "Website Profile authentication recipe is invalid");
+  const connection = record(source.connection ?? {}, "Website Connection descriptor is invalid");
+  const localProfileKey = typeof connection.connectionId === "string" && /^bgc_[A-Za-z0-9_-]{43}$/.test(connection.connectionId)
+    ? connection.connectionId
+    : undefined;
+  const headerSources = array(auth.headerSources).map((item) => {
+    const binding = record(item, "Website Profile storage selector is invalid");
+    const origin = exactHttpsOrigin(binding.origin);
+    const keySuffix = String(binding.keySuffix || "");
+    if (!allowedOrigins.includes(origin) || !keySuffix || keySuffix.length > 240) {
+      throw new Error("Website Profile storage selector is invalid");
+    }
+    return { keySuffix, origin };
+  });
+  if (headerSources.length > 12) throw new Error("Website Profile storage selector is invalid");
+  if (auth.sendCookies !== true && headerSources.length === 0) throw new Error("Website Profile authentication recipe is empty");
+  return {
+    allowedOrigins,
+    auth: { headerSources, sendCookies: auth.sendCookies === true },
+    connectorId,
+    ...(localProfileKey ? { localProfileKey } : {}),
+    loginUrl: loginUrl.toString(),
+    profileSchemaVersion: WEBSITE_BROWSER_PROFILE_SCHEMA_VERSION
+  };
+}
+
+async function originStorage(client, sessionId, spec) {
+  await client.call("Page.enable", {}, sessionId);
+  await client.call("Runtime.enable", {}, sessionId);
+  const origins = [...new Set(spec.auth.headerSources.map((source) => source.origin))];
+  const result = [];
+  for (const origin of origins) {
+    await client.call("Page.navigate", { url: `${origin}/` }, sessionId);
+    await waitForDocument(client, sessionId, origin);
+    const evaluated = await client.call("Runtime.evaluate", {
+      expression: "Object.entries(window.localStorage).map(([name,value])=>({name,value}))",
+      returnByValue: true
+    }, sessionId);
+    result.push({ localStorage: array(evaluated?.result?.value), origin });
+  }
+  return result;
+}
+
+async function browserCookies(client) {
+  const result = await client.call("Storage.getCookies");
+  return array(result.cookies);
+}
+
+async function pageSession(client, spec) {
+  const targets = await client.call("Target.getTargets");
+  const pages = array(targets.targetInfos).filter((target) => target.type === "page");
+  const page = pages.find((target) => {
+    try {
+      return spec.allowedOrigins.includes(new URL(target.url).origin);
+    } catch {
+      return false;
+    }
+  }) ?? pages[0];
+  if (!page?.targetId) throw new Error("Chrome did not create a page for Website Profile capture");
+  const attached = await client.call("Target.attachToTarget", { flatten: true, targetId: page.targetId });
+  if (!attached.sessionId) throw new Error("Could not attach to the local Chrome page");
+  return attached.sessionId;
+}
+
+async function waitForDocument(client, sessionId, expectedOrigin) {
+  for (let attempt = 0; attempt < 100; attempt += 1) {
+    const result = await client.call("Runtime.evaluate", {
+      expression: "({readyState:document.readyState,url:location.href})",
+      returnByValue: true
+    }, sessionId).catch(() => ({}));
+    const value = result?.result?.value;
+    if (documentIsReadyAtOrigin(value, expectedOrigin)) return;
+    await delay(100);
+  }
+  throw new Error(`Timed out while reading local storage for ${expectedOrigin}`);
+}
+
+async function waitForLoginConfirmation(spec, options) {
+  if (options.waitForLogin) return options.waitForLogin(spec);
+  const input = options.stdin ?? process.stdin;
+  const output = options.stderr ?? process.stderr;
+  if (!input.isTTY) throw new Error("Interactive login requires a TTY; use --no-prompt only for an already authenticated local Profile");
+  const nextStep = options.purpose === "local-execution"
+    ? "Complete login, then press Enter here to run locally; nothing will be uploaded."
+    : "Complete login, then press Enter here to upload only the allowlisted session state.";
+  output.write(`Fargo opened an isolated local Chrome Profile for ${spec.connectorId}.\n${nextStep}\n`);
+  const prompt = createInterface({ input, output });
+  try {
+    await prompt.question("");
+  } finally {
+    prompt.close();
+  }
+}
+
+async function findChromeExecutable(explicitPath, options) {
+  if (explicitPath) {
+    await access(explicitPath);
+    return resolve(explicitPath);
+  }
+  const currentPlatform = options.platform ?? platform();
+  const candidates = currentPlatform === "darwin"
+    ? [
+        "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+        "/Applications/Chromium.app/Contents/MacOS/Chromium"
+      ]
+    : currentPlatform === "win32"
+      ? [
+          join(process.env.PROGRAMFILES ?? "C:\\Program Files", "Google", "Chrome", "Application", "chrome.exe"),
+          join(process.env["PROGRAMFILES(X86)"] ?? "C:\\Program Files (x86)", "Google", "Chrome", "Application", "chrome.exe")
+        ]
+      : executableCandidates(["google-chrome", "google-chrome-stable", "chromium", "chromium-browser"]);
+  for (const candidate of candidates) {
+    try {
+      await access(candidate);
+      return candidate;
+    } catch { /* Try the next supported browser path. */ }
+  }
+  throw new Error("Google Chrome or Chromium was not found; pass --chrome-path <path>");
+}
+
+function executableCandidates(names) {
+  return String(process.env.PATH || "").split(delimiter).flatMap((directory) => names.map((name) => join(directory, name)));
+}
+
+async function waitForDevToolsEndpoint(path, child, options) {
+  const timeoutMs = boundedInteger(options.launchTimeoutMs, 15_000, 1_000, 60_000);
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < timeoutMs) {
+    if (child.exitCode !== null) throw new Error("Chrome exited before Website Profile capture started");
+    try {
+      const [port, browserPath] = (await readFile(path, "utf8")).trim().split(/\r?\n/);
+      if (/^\d+$/.test(port) && browserPath?.startsWith("/devtools/browser/")) {
+        return `ws://127.0.0.1:${port}${browserPath}`;
+      }
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+    }
+    await delay(100);
+  }
+  throw new Error("Timed out waiting for Chrome DevTools");
+}
+
+function waitForExit(child, timeoutMs) {
+  if (child.exitCode !== null) return Promise.resolve();
+  return new Promise((resolvePromise, reject) => {
+    const timeout = setTimeout(() => reject(new Error("Chrome did not close")), timeoutMs);
+    child.once("exit", () => {
+      clearTimeout(timeout);
+      resolvePromise();
+    });
+  });
+}
+
+class CdpClient {
+  constructor(socket) {
+    this.socket = socket;
+    this.nextId = 1;
+    this.pending = new Map();
+    socket.addEventListener("message", (event) => {
+      const message = JSON.parse(String(event.data));
+      if (!message.id) return;
+      const pending = this.pending.get(message.id);
+      if (!pending) return;
+      this.pending.delete(message.id);
+      if (message.error) pending.reject(new Error(message.error.message || "Chrome DevTools request failed"));
+      else pending.resolve(message.result ?? {});
+    });
+    socket.addEventListener("close", () => this.rejectPending(new Error("Chrome DevTools connection closed")));
+    socket.addEventListener("error", () => this.rejectPending(new Error("Chrome DevTools connection failed")));
+  }
+
+  static async connect(endpoint) {
+    const socket = new WebSocket(endpoint);
+    await new Promise((resolvePromise, reject) => {
+      socket.addEventListener("open", resolvePromise, { once: true });
+      socket.addEventListener("error", () => reject(new Error("Could not connect to local Chrome DevTools")), { once: true });
+    });
+    return new CdpClient(socket);
+  }
+
+  call(method, params = {}, sessionId) {
+    const id = this.nextId++;
+    return new Promise((resolvePromise, reject) => {
+      this.pending.set(id, { reject, resolve: resolvePromise });
+      this.socket.send(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) }));
+    });
+  }
+
+  rejectPending(error) {
+    for (const pending of this.pending.values()) pending.reject(error);
+    this.pending.clear();
+  }
+}
+
+function normalizeCookie(cookie) {
+  const sameSite = ["Strict", "Lax", "None"].includes(cookie.sameSite) ? cookie.sameSite : undefined;
+  const expires = Number(cookie.expires);
+  return {
+    domain: String(cookie.domain),
+    ...(Number.isFinite(expires) && expires > 0 ? { expires } : {}),
+    httpOnly: cookie.httpOnly === true,
+    name: String(cookie.name),
+    path: String(cookie.path || "/"),
+    ...(sameSite ? { sameSite } : {}),
+    secure: cookie.secure === true,
+    value: String(cookie.value)
+  };
+}
+
+function cookieAllowed(domain, allowedHosts) {
+  const host = String(domain || "").toLowerCase().replace(/^\./, "");
+  return allowedHosts.some((allowed) => host === allowed || host.endsWith(`.${allowed}`));
+}
+
+function exactHttpsOrigin(value) {
+  const url = new URL(String(value || ""));
+  if (url.protocol !== "https:" || url.origin !== value || url.username || url.password) throw new Error("Website Profile origin is invalid");
+  return url.origin;
+}
+
+function requiredConnectorId(value) {
+  const id = String(value || "");
+  if (!/^[a-z][a-z0-9-]{1,62}[a-z0-9]$/.test(id)) throw new Error("Website Connector id is invalid");
+  return id;
+}
+
+function boundedInteger(value, fallback, minimum, maximum) {
+  const candidate = value === undefined ? fallback : Number(value);
+  if (!Number.isInteger(candidate) || candidate < minimum || candidate > maximum) throw new Error("Website browser timeout is invalid");
+  return candidate;
+}
+
+function array(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function record(value, message) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(message);
+  return value;
+}
+
+function delay(milliseconds) {
+  return new Promise((resolvePromise) => setTimeout(resolvePromise, milliseconds));
+}