@fargowealth/fargo-ai-cli 1.2.1 → 1.4.0

package/src/website-cli.mjs

@@ -0,0 +1,364 @@
+import { createHash, randomBytes } from "node:crypto";
+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, 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") {
+    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");
+    const result = await callWebsiteBridge(store, "website_connector_release", {
+      definition,
+      ...(expectedRevision === undefined ? {} : { expectedRevision })
+    }, { ...options, confirmation: args.includes("--confirm") });
+    stdout.write(`${JSON.stringify(result)}\n`);
+    return;
+  }
+  if (action === "list") {
+    stdout.write(`${JSON.stringify(await callWebsiteBridge(store, "website_connector_list", {}, options))}\n`);
+    return;
+  }
+  if (action === "operations") {
+    stdout.write(`${JSON.stringify(await callWebsiteBridge(store, "website_connector_operations", {
+      connectorId: requiredOption(args, "--connector")
+    }, options))}\n`);
+    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, executionMode: "remote" })}\n`);
+    return;
+  }
+  if (action === "connection-status") {
+    stdout.write(`${JSON.stringify(await callWebsiteBridge(store, "website_connection_status", {
+      connectorId: requiredOption(args, "--connector")
+    }, options))}\n`);
+    return;
+  }
+  if (action === "connect" || action === "sync") {
+    const connectorId = requiredOption(args, "--connector");
+    const spec = await callWebsiteBridge(store, "website_connection_profile_spec", { connectorId }, options);
+    const capture = options.captureWebsiteProfile ?? captureLocalWebsiteProfile;
+    const profile = await capture(spec, {
+      chromePath: optionValue(args, "--chrome-path"),
+      noPrompt: args.includes("--no-prompt"),
+      profileDirectory: optionValue(args, "--profile-dir"),
+      settleMs: optionalInteger(args, "--settle-ms"),
+      stderr: options.stderr,
+      stdin: options.stdin
+    });
+    const result = await uploadWebsiteProfile(store, spec, profile, {
+      ...options,
+      connectorId,
+      mode: action === "sync" ? "sync" : "establish"
+    });
+    stdout.write(`${JSON.stringify(result)}\n`);
+    return;
+  }
+  if (action === "authorize") {
+    stdout.write(`${JSON.stringify(await callWebsiteBridge(store, "website_connection_authorize", {
+      connectorId: requiredOption(args, "--connector")
+    }, options))}\n`);
+    return;
+  }
+  if (action === "authorize-complete") {
+    stdout.write(`${JSON.stringify(await callWebsiteBridge(store, "website_connection_authorize_complete", {
+      connectorId: requiredOption(args, "--connector")
+    }, options))}\n`);
+    return;
+  }
+  if (action === "binding") {
+    stdout.write(`${JSON.stringify({
+      appId: WEBSITE_BRIDGE_APP_ID,
+      manifestVersion: "fargo.app-mcp/v1",
+      requiresCurrentUserDelegation: true,
+      authority: { mode: "invoking_user" },
+      allowedToolNames: [
+        "website_connector_list",
+        "website_connector_operations",
+        "website_connector_read",
+        "website_connector_execute",
+        "website_connection_status"
+      ]
+    }, null, 2)}\n`);
+    return;
+  }
+  throw new Error(WEBSITE_USAGE);
+}
+
+async function callWebsiteBridge(store, toolName, toolArguments, options) {
+  return mcpToolPayload(await callMcpTool(store, "app_mcp_tool_call", {
+    appId: WEBSITE_BRIDGE_APP_ID,
+    toolName,
+    arguments: toolArguments,
+    ...(options.confirmation === true ? { confirmation: true } : {})
+  }, options));
+}
+
+async function readDefinition(args) {
+  const path = resolve(requiredOption(args, "--file"));
+  let value;
+  try {
+    value = JSON.parse(await readFile(path, "utf8"));
+  } catch (error) {
+    if (error instanceof SyntaxError) throw new Error("Website Connector definition must be valid JSON");
+    throw error;
+  }
+  return parseWebsiteConnectorDefinition(value);
+}
+
+async function readArguments(args) {
+  const inline = optionValue(args, "--args");
+  const file = optionValue(args, "--args-file");
+  if (inline !== undefined && file !== undefined) throw new Error("Use only one of --args or --args-file");
+  const text = file === undefined ? inline ?? "{}" : await readFile(resolve(file), "utf8");
+  try {
+    const value = JSON.parse(text);
+    if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("invalid");
+    return value;
+  } catch {
+    throw new Error("Website operation arguments must be a JSON object");
+  }
+}
+
+function validationSummary(definition) {
+  const canonical = JSON.stringify(definition);
+  return {
+    valid: true,
+    schemaVersion: definition.schemaVersion,
+    connectorId: definition.connectorId,
+    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 })),
+      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;
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < 0) throw new Error(`${name} must be a non-negative integer`);
+  return value;
+}
+
+function requiredOption(args, name) {
+  const value = optionValue(args, name)?.trim();
+  if (!value || value.startsWith("--")) throw new Error(`Missing required option ${name}`);
+  return value;
+}
+
+function optionValue(args, name) {
+  const inline = args.find((value) => value.startsWith(`${name}=`));
+  if (inline) return inline.slice(name.length + 1);
+  const index = args.indexOf(name);
+  return index >= 0 ? args[index + 1] : undefined;
+}
+
+export async function uploadWebsiteProfile(store, spec, profile, options) {
+  assertWebsiteProfile(profile, options.connectorId);
+  const body = JSON.stringify(profile);
+  const bodyBytes = Buffer.byteLength(body, "utf8");
+  if (bodyBytes > 512_000) throw new Error("Website Profile exceeds the 512 KB upload limit");
+  const uploadSecret = randomBytes(32).toString("base64url");
+  const mode = options.mode === "sync" ? "sync" : "establish";
+  const currentVersion = Number(spec?.connection?.profileVersion ?? 0);
+  if (
+    mode === "sync"
+    && (
+      !Number.isInteger(currentVersion)
+      || currentVersion < 1
+      || !["active", "needs_reauth"].includes(spec?.connection?.state)
+    )
+  ) {
+    throw new Error("Website Connection must already exist before it can be synchronized");
+  }
+  const capability = await callWebsiteBridge(store, "website_connection_import_begin", {
+    connectorId: options.connectorId,
+    mode,
+    profileSha256: createHash("sha256").update(body).digest("hex"),
+    uploadSecretSha256: createHash("sha256").update(uploadSecret).digest("hex"),
+    ...(mode === "sync" ? { expectedProfileVersion: currentVersion } : {})
+  }, options);
+  if (
+    capability?.method !== "POST"
+    || !Number.isInteger(capability?.maxBytes)
+    || capability.maxBytes < bodyBytes
+    || capability.maxBytes > 512_000
+    || !Number.isFinite(Date.parse(capability?.expiresAt))
+    || Date.parse(capability.expiresAt) <= Date.now()
+  ) throw new Error("Website Profile upload capability is invalid");
+  const uploadUrl = validatedUploadUrl(capability?.uploadUrl, options);
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const response = await fetchImpl(uploadUrl, {
+    body,
+    headers: {
+      Accept: "application/json",
+      "Content-Type": "application/json",
+      "X-Fargo-Profile-Upload-Secret": uploadSecret
+    },
+    method: "POST",
+    redirect: "error"
+  });
+  let payload;
+  try {
+    payload = await response.json();
+  } catch {
+    throw new Error(`Website Profile upload failed (${response.status})`);
+  }
+  if (!response.ok) throw new Error(payload?.error || `Website Profile upload failed (${response.status})`);
+  return payload;
+}
+
+function assertWebsiteProfile(profile, connectorId) {
+  if (
+    !profile
+    || typeof profile !== "object"
+    || Array.isArray(profile)
+    || profile.schemaVersion !== "fargo.browser-profile/v1"
+    || profile.connectorId !== connectorId
+    || !Number.isFinite(Date.parse(profile.capturedAt))
+    || !Array.isArray(profile.cookies)
+    || !Array.isArray(profile.origins)
+  ) throw new Error("Local Website Profile is invalid");
+}
+
+function validatedUploadUrl(value, options) {
+  const expectedOrigin = new URL(options.websiteBridgeUrl ?? process.env.FARGO_WEBSITE_BRIDGE_URL ?? WEBSITE_BRIDGE_URL).origin;
+  let url;
+  try {
+    url = new URL(String(value || ""));
+  } catch {
+    throw new Error("Website Profile upload capability is invalid");
+  }
+  if (
+    url.protocol !== "https:"
+    || url.origin !== expectedOrigin
+    || !/^\/v1\/website\/profile-imports\/wpi_[0-9a-f-]{36}$/.test(url.pathname)
+    || url.search
+    || url.hash
+    || url.username
+    || url.password
+  ) throw new Error("Website Profile upload capability is invalid");
+  return url.toString();
+}
+
+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>
+
+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>] [--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:
+  authorize --connector <id>
+  authorize-complete --connector <id>
+
+Teammate:
+  binding
+`;

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

@@ -0,0 +1 @@
+export * from "@fargowealth/website-connector-runtime";

package/src/website-connector-definition.mjs

@@ -0,0 +1 @@
+export * from "@fargowealth/website-connector-runtime";