@fargowealth/fargo-ai-cli 1.3.0 → 1.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fargowealth/fargo-ai-cli",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "description": "Agent-neutral Fargo AI CLI, MCP client, and LEGO project tooling",
   "type": "module",
   "bin": {
@@ -17,9 +17,13 @@
     "node": ">=20.19.0"
   },
   "dependencies": {
+    "@fargowealth/website-connector-runtime": "^1.1.0",
     "fflate": "^0.8.2",
     "ignore": "^7.0.6"
   },
+  "bundleDependencies": [
+    "@fargowealth/website-connector-runtime"
+  ],
   "license": "UNLICENSED",
   "publishConfig": {
     "access": "public"

package/src/constants.mjs

@@ -1,4 +1,4 @@
-export const CLI_VERSION = "1.3.0";
+export const CLI_VERSION = "1.4.1";
 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

@@ -1,5 +1,5 @@
 import { spawn } from "node:child_process";
-import { access, chmod, mkdir, readFile, unlink } from "node:fs/promises";
+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";
@@ -52,7 +52,7 @@ export function buildWebsiteBrowserProfile(spec, state, capturedAt = new Date())
     ? array(state.cookies).filter((cookie) => cookieAllowed(cookie.domain, allowedHosts)).map(normalizeCookie)
     : [];
   const suffixesByOrigin = new Map();
-  for (const source of captureSpec.auth.headerSources) {
+  for (const source of [...captureSpec.auth.headerSources, ...captureSpec.auth.secretSources]) {
     const suffixes = suffixesByOrigin.get(source.origin) ?? new Set();
     suffixes.add(source.keySuffix);
     suffixesByOrigin.set(source.origin, suffixes);
@@ -91,6 +91,34 @@ export function defaultLocalWebsiteProfileDirectory(connectorId, options = {}) {
   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");
@@ -117,11 +145,21 @@ export function parseCaptureSpec(value) {
     }
     return { keySuffix, origin };
   });
+  const secretSources = array(auth.secretSources).map((item) => {
+    const binding = record(item, "Website Profile secret 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 secret selector is invalid");
+    }
+    return { keySuffix, origin };
+  });
   if (headerSources.length > 12) throw new Error("Website Profile storage selector is invalid");
+  if (secretSources.length > 12) throw new Error("Website Profile secret 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 },
+    auth: { headerSources, secretSources, sendCookies: auth.sendCookies === true },
     connectorId,
     ...(localProfileKey ? { localProfileKey } : {}),
     loginUrl: loginUrl.toString(),
@@ -132,7 +170,9 @@ export function parseCaptureSpec(value) {
 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 origins = [...new Set(
+    [...spec.auth.headerSources, ...spec.auth.secretSources].map((source) => source.origin)
+  )];
   const result = [];
   for (const origin of origins) {
     await client.call("Page.navigate", { url: `${origin}/` }, sessionId);
@@ -174,7 +214,7 @@ async function waitForDocument(client, sessionId, expectedOrigin) {
       returnByValue: true
     }, sessionId).catch(() => ({}));
     const value = result?.result?.value;
-    if (value?.readyState === "complete" && new URL(value.url).origin === expectedOrigin) return;
+    if (documentIsReadyAtOrigin(value, expectedOrigin)) return;
     await delay(100);
   }
   throw new Error(`Timed out while reading local storage for ${expectedOrigin}`);
@@ -185,7 +225,10 @@ async function waitForLoginConfirmation(spec, options) {
   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");
-  output.write(`Fargo opened an isolated local Chrome Profile for ${spec.connectorId}.\nComplete login, then press Enter here to upload only the allowlisted session state.\n`);
+  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("");
@@ -311,7 +354,7 @@ function normalizeCookie(cookie) {
 
 function cookieAllowed(domain, allowedHosts) {
   const host = String(domain || "").toLowerCase().replace(/^\./, "");
-  return allowedHosts.some((allowed) => host === allowed || host.endsWith(`.${allowed}`));
+  return allowedHosts.some((allowed) => allowed === host || allowed.endsWith(`.${host}`));
 }
 
 function exactHttpsOrigin(value) {

package/src/website-cli.mjs

@@ -3,23 +3,33 @@ import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { callMcpTool } from "./mcp-client.mjs";
 import { mcpToolPayload } from "./mcp-result.mjs";
-import { captureLocalWebsiteProfile } from "./website-browser-profile.mjs";
-import { parseWebsiteConnectorDefinition } from "./website-connector-definition.mjs";
+import { captureLocalWebsiteProfile, resolveLocalWebsiteProfileDirectory } from "./website-browser-profile.mjs";
+import {
+  assertWebsiteConnectorRuntimeCompatibility,
+  executeWebsiteConnectorOperation,
+  parseWebsiteConnectorDefinition,
+  websiteConnectorRuntimeDescriptor
+} from "./website-connector-definition.mjs";
 
 const WEBSITE_BRIDGE_APP_ID = "website-bridge";
 const WEBSITE_BRIDGE_URL = "https://website-bridge.fargowealth.app";
 
 export async function runWebsiteCommand(args, stdout, store, options = {}) {
   const action = args[1];
-  if (action === "--help" || action === "-h" || action === "help") {
+  if (action === "help" || args.includes("--help") || args.includes("-h")) {
     stdout.write(WEBSITE_HELP);
     return;
   }
   if (action === "validate") {
     const definition = await readDefinition(args);
+    assertWebsiteConnectorRuntimeCompatibility(definition);
     stdout.write(`${JSON.stringify(validationSummary(definition))}\n`);
     return;
   }
+  if (action === "runtime") {
+    stdout.write(`${JSON.stringify(websiteConnectorRuntimeDescriptor())}\n`);
+    return;
+  }
   if (action === "release") {
     const definition = await readDefinition(args);
     const expectedRevision = optionalInteger(args, "--expected-revision");
@@ -41,13 +51,50 @@ export async function runWebsiteCommand(args, stdout, store, options = {}) {
     return;
   }
   if (action === "call") {
+    const mode = websiteCallMode(args);
     const write = args.includes("--write");
+    if (mode === "local") {
+      const definition = await readDefinition(args);
+      const connectorId = optionValue(args, "--connector")?.trim();
+      if (connectorId && connectorId !== definition.connectorId) {
+        throw new Error("--connector must match the Connector definition in --file");
+      }
+      const operationId = requiredOption(args, "--operation");
+      const operation = definition.operations.find((candidate) => candidate.operationId === operationId);
+      if (!operation) throw new Error("website_operation_not_found");
+      if (!operation.readOnly && (!write || !args.includes("--confirm"))) {
+        throw new Error("Local write operations require --write --confirm");
+      }
+      let storageState;
+      if (operation.requiresConnection) {
+        const capture = options.captureWebsiteProfile ?? captureLocalWebsiteProfile;
+        storageState = await capture(localProfileSpec(definition), {
+          chromePath: optionValue(args, "--chrome-path"),
+          noPrompt: args.includes("--no-prompt"),
+          profileDirectory: await resolveLocalWebsiteProfileDirectory(definition.connectorId, {
+            profileDirectory: optionValue(args, "--profile-dir")
+          }),
+          purpose: "local-execution",
+          settleMs: optionalInteger(args, "--settle-ms"),
+          stderr: options.stderr,
+          stdin: options.stdin
+        });
+      }
+      const execute = options.executeWebsiteOperation ?? executeWebsiteConnectorOperation;
+      const result = await execute(definition, operationId, await readArguments(args), {
+        fetchImpl: options.fetchImpl,
+        readOnlyOnly: !write,
+        ...(storageState ? { storageState } : {})
+      });
+      stdout.write(`${JSON.stringify({ ...result, executionMode: "local" })}\n`);
+      return;
+    }
     const result = await callWebsiteBridge(store, write ? "website_connector_execute" : "website_connector_read", {
       connectorId: requiredOption(args, "--connector"),
       operationId: requiredOption(args, "--operation"),
       arguments: await readArguments(args)
     }, { ...options, confirmation: args.includes("--confirm") });
-    stdout.write(`${JSON.stringify(result)}\n`);
+    stdout.write(`${JSON.stringify({ ...result, executionMode: "remote" })}\n`);
     return;
   }
   if (action === "connection-status") {
@@ -151,10 +198,36 @@ function validationSummary(definition) {
     displayName: definition.displayName,
     operationCount: definition.operations.length,
     requiresConnection: definition.operations.some((operation) => operation.requiresConnection),
+    runtime: websiteConnectorRuntimeDescriptor(),
     sha256: createHash("sha256").update(canonical).digest("hex")
   };
 }
 
+function websiteCallMode(args) {
+  if (args.includes("--local")) return "local";
+  const mode = optionValue(args, "--mode") ?? "remote";
+  if (!["auto", "local", "remote"].includes(mode)) throw new Error("--mode must be auto, local, or remote");
+  return mode === "auto" ? (optionValue(args, "--file") ? "local" : "remote") : mode;
+}
+
+function localProfileSpec(definition) {
+  if (definition.auth.kind !== "browser_storage" || !definition.loginUrl) {
+    throw new Error("Website Connector does not define a local browser Profile");
+  }
+  return {
+    allowedOrigins: definition.allowedOrigins,
+    auth: {
+      headerSources: definition.auth.headerSources.map(({ keySuffix, origin }) => ({ keySuffix, origin })),
+      secretSources: definition.auth.secretSources.map(({ keySuffix, origin }) => ({ keySuffix, origin })),
+      sendCookies: definition.auth.sendCookies
+    },
+    connection: {},
+    connectorId: definition.connectorId,
+    loginUrl: definition.loginUrl,
+    profileSchemaVersion: "fargo.browser-profile/v1"
+  };
+}
+
 function optionalInteger(args, name) {
   const raw = optionValue(args, name);
   if (raw === undefined) return undefined;
@@ -264,12 +337,13 @@ function validatedUploadUrl(value, options) {
   return url.toString();
 }
 
-export const WEBSITE_USAGE = "Usage: fargo website validate|release|list|operations|call|connect|sync|connection-status|authorize|authorize-complete|binding";
+export const WEBSITE_USAGE = "Usage: fargo website validate|runtime|release|list|operations|call|connect|sync|connection-status|authorize|authorize-complete|binding";
 
 export const WEBSITE_HELP = `Usage: fargo website <command> [options]
 
 Connector authoring:
   validate --file <path>
+  runtime
   release --file <path> [--expected-revision <n>] --confirm
   list
   operations --connector <id>
@@ -278,7 +352,8 @@ Connection and execution:
   connect --connector <id> [--chrome-path <path>] [--profile-dir <path>]
   sync --connector <id> [--no-prompt] [--settle-ms <n>]
   connection-status --connector <id>
-  call --connector <id> --operation <id> [--args <json> | --args-file <path>]
+  call --connector <id> --operation <id> [--args <json> | --args-file <path>] [--mode auto|remote]
+  call --file <path> --operation <id> --mode local [--profile-dir <path>] [--no-prompt]
   call --connector <id> --operation <id> --write [--confirm]
 
 Cloud login fallback:

package/src/website-connector-definition.d.mts

@@ -1,58 +1 @@
-export type WebsiteConnectorInputSchema = {
-  additionalProperties: false;
-  properties: Record<string, {
-    enum?: Array<string | number | boolean>;
-    maxLength?: number;
-    type: "string" | "number" | "integer" | "boolean";
-  }>;
-  required: string[];
-  type: "object";
-};
-
-export type WebsiteConnectorAuth =
-  | { kind: "none" }
-  | {
-      kind: "browser_storage";
-      sendCookies: boolean;
-      headerSources: Array<{ keySuffix: string; name: string; origin: string; prefix?: string }>;
-    };
-
-export type WebsiteConnectorOperation = {
-  operationId: string;
-  description: string;
-  readOnly: boolean;
-  requiresConnection: boolean;
-  riskLevel: "low" | "medium" | "high" | "critical";
-  inputSchema: WebsiteConnectorInputSchema;
-  request: {
-    origin: string;
-    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
-    path: string;
-    query: Record<string, string>;
-    headers: Record<string, string>;
-    body?: unknown;
-  };
-};
-
-export type WebsiteConnectorDefinition = {
-  schemaVersion: "fargo.website-connector/v1";
-  connectorId: string;
-  displayName: string;
-  allowedOrigins: string[];
-  loginUrl?: string;
-  auth: WebsiteConnectorAuth;
-  operations: WebsiteConnectorOperation[];
-};
-
-export const WEBSITE_CONNECTOR_SCHEMA_VERSION: "fargo.website-connector/v1";
-export class WebsiteConnectorDefinitionError extends Error {
-  code: string;
-  path: string;
-}
-export function parseWebsiteConnectorDefinition(value: unknown): WebsiteConnectorDefinition;
-export function connectorToolName(connectorId: string, operationId: string): string;
-export function renderWebsiteOperation(definition: unknown, operationId: string, rawArguments: unknown): {
-  definition: WebsiteConnectorDefinition;
-  operation: WebsiteConnectorOperation;
-  request: { body?: unknown; headers: Record<string, string>; method: string; url: string };
-};
+export * from "@fargowealth/website-connector-runtime";