zk-agent-cli 0.1.0-beta.1 → 0.1.0-beta.3

package/dist/connector-ui/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>zk-agent connector</title>
+    <script type="module" crossorigin src="/assets/index-WTJRR5fK.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-BnFLonFL.css">
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+  </html>

package/dist/index.js

@@ -11748,6 +11748,9 @@ import fs7 from "node:fs";
 import path6 from "node:path";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 var RELAY_BODY_LIMIT_BYTES = 1024 * 1024;
+var RELAY_SERVICE = "zk-agent-relay";
+var RELAY_PROTOCOL = "zk-agent-session-relay";
+var RELAY_SCHEMA_VERSION = 1;
 function relayDir() {
   const directory = path6.join(storageDir(), "relay");
   if (!fs7.existsSync(directory)) {
@@ -11837,6 +11840,8 @@ function resolveConnectorUiDistRoot() {
   const currentFile = fileURLToPath3(import.meta.url);
   const currentDir2 = path6.dirname(currentFile);
   const candidates = [
+    path6.resolve(currentDir2, "../connector-ui"),
+    path6.resolve(currentDir2, "../../dist/connector-ui"),
     path6.resolve(currentDir2, "../../../zk-connector-ui/dist"),
     path6.resolve(currentDir2, "../../zk-connector-ui/dist")
   ];
@@ -11857,6 +11862,32 @@ function contentTypeFor(filePath) {
 function normalizeRelayBaseUrl(baseUrl) {
   return baseUrl.replace(/\/+$/, "");
 }
+function resolveRelayPublicBaseUrl(actualBaseUrl, publicOrigin) {
+  return publicOrigin?.trim() ? normalizeRelayBaseUrl(new URL(publicOrigin.trim()).toString()) : normalizeRelayBaseUrl(actualBaseUrl);
+}
+function relayCapabilities(connectorUiAvailable) {
+  return [
+    "create-request",
+    "read-status",
+    "fetch-approval",
+    "submit-approval",
+    "share-redirect",
+    ...connectorUiAvailable ? ["connector-ui"] : []
+  ];
+}
+function relayHealthResponse(actualBaseUrl, publicBaseUrl, connectorUiAvailable) {
+  return {
+    ok: true,
+    service: RELAY_SERVICE,
+    protocol: RELAY_PROTOCOL,
+    schema_version: RELAY_SCHEMA_VERSION,
+    relay_mode: "local-file",
+    origin: normalizeRelayBaseUrl(actualBaseUrl),
+    public_origin: normalizeRelayBaseUrl(publicBaseUrl),
+    connector_ui_available: connectorUiAvailable,
+    capabilities: relayCapabilities(connectorUiAvailable)
+  };
+}
 function relayShareUrl(baseUrl, requestId) {
   return `${normalizeRelayBaseUrl(baseUrl)}/r/${requestId}`;
 }
@@ -11886,6 +11917,13 @@ async function fetchRelayStatus(baseUrl, requestId) {
   }
   return await response.json();
 }
+async function fetchRelayHealth(baseUrl) {
+  const response = await fetch(`${normalizeRelayBaseUrl(baseUrl)}/health`);
+  if (!response.ok) {
+    throw new Error(`Relay health fetch failed with status ${response.status}`);
+  }
+  return await response.json();
+}
 function sleep(ms) {
   return new Promise((resolve) => {
     setTimeout(resolve, ms);
@@ -11922,13 +11960,18 @@ async function startRelayServer(options) {
       const requestUrl = new URL(request.url || "/", `http://${request.headers.host || "localhost"}`);
       const pathname = requestUrl.pathname;
       const method = request.method || "GET";
-      const baseUrl = `${requestUrl.protocol}//${requestUrl.host}`;
+      const actualBaseUrl = `${requestUrl.protocol}//${requestUrl.host}`;
+      const publicBaseUrl = resolveRelayPublicBaseUrl(actualBaseUrl, options.publicOrigin);
       if (method === "OPTIONS") {
         writeJson2(response, 204, {});
         return;
       }
       if (method === "GET" && pathname === "/health") {
-        writeJson2(response, 200, { ok: true });
+        writeJson2(
+          response,
+          200,
+          relayHealthResponse(actualBaseUrl, publicBaseUrl, Boolean(uiDistRoot))
+        );
         return;
       }
       if (method === "POST" && pathname === "/api/requests") {
@@ -11945,9 +11988,9 @@ async function startRelayServer(options) {
         writeJson2(response, existing ? 200 : 201, {
           request_id: record.request_id,
           status: relayStatus(record),
-          share_url: relayShareUrl(baseUrl, record.request_id),
-          status_url: relayStatusUrl(baseUrl, record.request_id),
-          approval_url: relayShareUrl(baseUrl, record.request_id)
+          share_url: relayShareUrl(publicBaseUrl, record.request_id),
+          status_url: relayStatusUrl(publicBaseUrl, record.request_id),
+          approval_url: relayShareUrl(publicBaseUrl, record.request_id)
         });
         return;
       }
@@ -11958,7 +12001,7 @@ async function startRelayServer(options) {
           writeJson2(response, 404, { error: `Relay request not found: ${requestMatch[1]}` });
           return;
         }
-        writeJson2(response, 200, relayStatusResponse(baseUrl, record));
+        writeJson2(response, 200, relayStatusResponse(publicBaseUrl, record));
         return;
       }
       const approvalMatch = pathname.match(/^\/api\/requests\/([^/]+)\/approval$/);
@@ -11989,7 +12032,7 @@ async function startRelayServer(options) {
         response.statusCode = 302;
         response.setHeader(
           "Location",
-          `/?relayRequestUrl=${encodeURIComponent(relayStatusUrl(baseUrl, shareMatch[1]))}`
+          `/?relayRequestUrl=${encodeURIComponent(relayStatusUrl(publicBaseUrl, shareMatch[1]))}`
         );
         response.end();
         return;
@@ -12033,6 +12076,7 @@ async function startRelayServer(options) {
     });
   });
   return {
+    connectorUiAvailable: Boolean(uiDistRoot),
     origin: `http://${address.address}:${address.port}`,
     port: address.port,
     close: async () => await new Promise((resolve, reject) => {
@@ -12054,9 +12098,104 @@ function buildRelayServeRecommendedCommands(relayUrl) {
     reapproveWallet: `zk-agent wallet reapprove --name main --relay-url ${relayUrl}`
   };
 }
+function isRecord3(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function isRelayCapability(value) {
+  return [
+    "create-request",
+    "read-status",
+    "fetch-approval",
+    "submit-approval",
+    "share-redirect",
+    "connector-ui"
+  ].includes(String(value));
+}
+function asRelayHealthResponse(value) {
+  if (!isRecord3(value)) return null;
+  if (value.ok !== true) return null;
+  if (value.service !== "zk-agent-relay") return null;
+  if (value.protocol !== "zk-agent-session-relay") return null;
+  if (value.schema_version !== 1) return null;
+  if (value.relay_mode !== "local-file") return null;
+  if (typeof value.origin !== "string") return null;
+  if (typeof value.public_origin !== "string") return null;
+  if (typeof value.connector_ui_available !== "boolean") return null;
+  if (!Array.isArray(value.capabilities) || !value.capabilities.every(isRelayCapability)) {
+    return null;
+  }
+  return value;
+}
+function hasCoreRelayCapabilities(capabilities) {
+  const capabilitySet = new Set(capabilities);
+  return capabilitySet.has("create-request") && capabilitySet.has("read-status") && capabilitySet.has("fetch-approval") && capabilitySet.has("submit-approval") && capabilitySet.has("share-redirect");
+}
+function relayPublicOriginLooksLocal(origin) {
+  try {
+    const { hostname } = new URL(origin);
+    return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "0.0.0.0" || hostname === "::1" || hostname === "[::1]";
+  } catch {
+    return false;
+  }
+}
+function relayHostedReadinessNotes(options) {
+  const notes = [];
+  if (!options.compatible) {
+    notes.push(
+      "Relay health responded, but it did not advertise the full zk-agent relay compatibility contract."
+    );
+    return notes;
+  }
+  if (relayPublicOriginLooksLocal(options.publicOrigin)) {
+    notes.push(
+      "Relay compatibility is present, but the advertised public origin still points at a local-only address. Set --public-origin to the externally reachable URL before using this as a hosted approval path."
+    );
+  }
+  if (options.connectorUiAvailable === false) {
+    notes.push(
+      "Relay compatibility is present, but the built connector UI is not available at this relay. Hosted share-link approval needs a connector UI build or another externally reachable approval UI."
+    );
+  }
+  return notes;
+}
+function buildRelayInspectPayload(relayUrl, rawHealth) {
+  const health = asRelayHealthResponse(rawHealth);
+  const fallbackPublicOrigin = isRecord3(rawHealth) && typeof rawHealth.public_origin === "string" ? rawHealth.public_origin : relayUrl;
+  const publicOrigin = health?.public_origin || fallbackPublicOrigin;
+  const compatible = Boolean(health && hasCoreRelayCapabilities(health.capabilities));
+  const connectorUiAvailable = health?.connector_ui_available ?? null;
+  const publicOriginLooksLocal = relayPublicOriginLooksLocal(publicOrigin);
+  const hostedShareRedirectReady = compatible && connectorUiAvailable === true && !publicOriginLooksLocal;
+  const notes = relayHostedReadinessNotes({
+    compatible,
+    publicOrigin,
+    connectorUiAvailable
+  });
+  return {
+    ok: true,
+    status: "relay-inspected",
+    relayUrl,
+    compatible,
+    service: health?.service || null,
+    protocol: health?.protocol || null,
+    schemaVersion: health?.schema_version || null,
+    relayMode: health?.relay_mode || null,
+    origin: health?.origin || null,
+    publicOrigin,
+    publicOriginLooksLocal,
+    connectorUiAvailable,
+    hostedShareRedirectReady,
+    capabilities: health?.capabilities || [],
+    recommendedCommands: compatible ? buildRelayServeRecommendedCommands(publicOrigin) : {},
+    notes
+  };
+}
 function createRelayCommand() {
   const relay = new Command8("relay").description("Run the local connector relay prototype server");
-  relay.command("serve").description("Serve the local relay API and, when available, the built connector UI").option("--host <host>", "Host to bind", "127.0.0.1").option("--port <port>", "Port to bind (0 = choose a free port)", "4445").action(async (options) => {
+  relay.command("serve").description("Serve the local relay API and, when available, the built connector UI").option("--host <host>", "Host to bind", "127.0.0.1").option("--port <port>", "Port to bind (0 = choose a free port)", "4445").option(
+    "--public-origin <url>",
+    "Public base URL to advertise in share/status links when the relay is behind a tunnel or reverse proxy"
+  ).action(async (options) => {
     const host = options.host?.trim() || "127.0.0.1";
     const parsedPort = Number.parseInt(options.port || "4445", 10);
     if (!Number.isInteger(parsedPort) || parsedPort < 0 || parsedPort > 65535) {
@@ -12064,25 +12203,60 @@ function createRelayCommand() {
     }
     const server = await startRelayServer({
       host,
-      port: parsedPort
+      port: parsedPort,
+      publicOrigin: options.publicOrigin?.trim()
+    });
+    const publicOrigin = options.publicOrigin?.trim() || server.origin;
+    const publicOriginLooksLocal = relayPublicOriginLooksLocal(publicOrigin);
+    const connectorUiAvailable = server.connectorUiAvailable;
+    const hostedShareRedirectReady = connectorUiAvailable && !publicOriginLooksLocal;
+    const recommendedCommands = buildRelayServeRecommendedCommands(publicOrigin);
+    const notes = relayHostedReadinessNotes({
+      compatible: true,
+      publicOrigin,
+      connectorUiAvailable
     });
-    const recommendedCommands = buildRelayServeRecommendedCommands(server.origin);
     const payload = {
       ok: true,
       status: "relay-serving",
       origin: server.origin,
+      publicOrigin,
+      publicOriginLooksLocal,
       port: server.port,
       healthUrl: `${server.origin}/health`,
-      recommendedCommands
+      publicHealthUrl: `${publicOrigin}/health`,
+      relayMode: "local-file",
+      connectorUiAvailable,
+      hostedShareRedirectReady,
+      capabilities: [
+        "create-request",
+        "read-status",
+        "fetch-approval",
+        "submit-approval",
+        "share-redirect",
+        ...connectorUiAvailable ? ["connector-ui"] : []
+      ],
+      recommendedCommands,
+      notes
     };
     if (shouldJsonOutput()) {
       jsonOut(payload);
     } else {
       humanLine("status", "relay-serving");
       humanLine("origin", server.origin);
+      if (publicOrigin !== server.origin) {
+        humanLine("public origin", publicOrigin);
+      }
       humanLine("health", `${server.origin}/health`);
+      humanLine("hosted ready", hostedShareRedirectReady ? "yes" : "no");
+      if (connectorUiAvailable !== null) {
+        humanLine("connector ui", connectorUiAvailable ? "available" : "missing");
+      }
       humanLine("create wallet", recommendedCommands.createWallet);
       humanLine("reapprove wallet", recommendedCommands.reapproveWallet);
+      for (const note of notes) {
+        humanLine("note", note);
+      }
     }
     const shutdown = async () => {
       process.off("SIGINT", handleSignal);
@@ -12098,6 +12272,53 @@ function createRelayCommand() {
     await new Promise(() => {
     });
   });
+  relay.command("inspect").description("Inspect a relay URL for zk-agent compatibility and hosted remote-approval readiness").requiredOption("--relay-url <url>", "Relay server base URL to inspect").action(async (options) => {
+    const relayUrl = options.relayUrl.trim();
+    const rawHealth = await fetchRelayHealth(relayUrl);
+    const payload = buildRelayInspectPayload(relayUrl, rawHealth);
+    if (shouldJsonOutput()) {
+      jsonOut(payload);
+      return;
+    }
+    humanLine("status", "relay-inspected");
+    humanLine("relay url", relayUrl);
+    humanLine("compatible", payload.compatible ? "yes" : "no");
+    if (payload.service) {
+      humanLine("service", payload.service);
+    }
+    if (payload.protocol) {
+      humanLine("protocol", payload.protocol);
+    }
+    if (payload.relayMode) {
+      humanLine("mode", payload.relayMode);
+    }
+    if (payload.origin) {
+      humanLine("origin", payload.origin);
+    }
+    if (payload.publicOrigin) {
+      humanLine("public origin", payload.publicOrigin);
+    }
+    humanLine("public origin local", payload.publicOriginLooksLocal ? "yes" : "no");
+    if (payload.connectorUiAvailable !== null) {
+      humanLine("connector ui", payload.connectorUiAvailable ? "available" : "missing");
+    }
+    humanLine("hosted ready", payload.hostedShareRedirectReady ? "yes" : "no");
+    if (payload.capabilities.length > 0) {
+      humanLine("capabilities", payload.capabilities.join(", "));
+    }
+    if (payload.compatible) {
+      if (payload.recommendedCommands.createWallet) {
+        humanLine("create wallet", payload.recommendedCommands.createWallet);
+      }
+      if (payload.recommendedCommands.reapproveWallet) {
+        humanLine("reapprove wallet", payload.recommendedCommands.reapproveWallet);
+      }
+    } else {
+      for (const note of payload.notes) {
+        humanLine("note", note);
+      }
+    }
+  });
   return relay;
 }
 
@@ -12127,6 +12348,7 @@ function resolvePackageRoot() {
   const cwd = process.cwd();
   const candidates = [
     process.env.ZK_AGENT_ACCOUNT_PROFILES_ROOT,
+    path7.join(moduleRoot, "dist", "builtin-account-profiles"),
     moduleRoot,
     path7.join(cwd, "packages", "account-profiles"),
     path7.join(cwd, "account-profiles"),
@@ -12165,14 +12387,14 @@ function normalizeHexString(value, label) {
   }
   return prefixed;
 }
-function isRecord3(value) {
+function isRecord4(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function parseArtifactFile(artifactPath2) {
   const raw = JSON.parse(fs8.readFileSync(artifactPath2, "utf8"));
-  if (!isRecord3(raw)) throw new Error(`Artifact at ${artifactPath2} must be a JSON object`);
+  if (!isRecord4(raw)) throw new Error(`Artifact at ${artifactPath2} must be a JSON object`);
   if (!Array.isArray(raw.abi)) throw new Error(`Artifact at ${artifactPath2} must include an abi array`);
-  const bytecodeCandidate = typeof raw.bytecode === "string" ? raw.bytecode : isRecord3(raw.evm) && isRecord3(raw.evm.bytecode) && typeof raw.evm.bytecode.object === "string" ? raw.evm.bytecode.object : void 0;
+  const bytecodeCandidate = typeof raw.bytecode === "string" ? raw.bytecode : isRecord4(raw.evm) && isRecord4(raw.evm.bytecode) && typeof raw.evm.bytecode.object === "string" ? raw.evm.bytecode.object : void 0;
   if (!bytecodeCandidate) {
     throw new Error(`Artifact at ${artifactPath2} must include bytecode or evm.bytecode.object`);
   }
@@ -12184,7 +12406,7 @@ function parseArtifactFile(artifactPath2) {
       }
       return normalizeHexString(entry, `factoryDeps[${index}]`);
     });
-  } else if (isRecord3(raw.factoryDeps)) {
+  } else if (isRecord4(raw.factoryDeps)) {
     factoryDeps = Object.values(raw.factoryDeps).map((entry, index) => {
       if (typeof entry !== "string") {
         throw new Error(`factoryDeps value ${index} in ${artifactPath2} must be a hex string`);
@@ -12201,7 +12423,7 @@ function parseArtifactFile(artifactPath2) {
 }
 function missingArtifactError(profileId, artifactPath2) {
   return new Error(
-    `Built-in smart-account profile "${profileId}" is source-only right now. Expected compiled artifact at ${artifactPath2}. Compile the profile with a zkSync EraVM toolchain before using --profile ${profileId}.`
+    `Built-in smart-account profile "${profileId}" is not available in this runtime. Expected a compiled artifact at ${artifactPath2}. If you are running from source, compile the profile with a zkSync EraVM toolchain or point ZK_AGENT_ACCOUNT_PROFILES_ROOT at a checked-out ${PACKAGE_NAME} package directory.`
   );
 }
 function contractPath(...segments) {
@@ -12236,7 +12458,7 @@ function createDailySpendLimitProfile() {
       "The checked-in Solidity source uses 24 hours instead of the tutorial 1 minute reset window.",
       "AAFactory is kept as a reference helper, but the CLI deploy path targets the account artifact directly.",
       ...packageRootResolved ? [] : [
-        `Built-in profile assets are not available in this runtime. Set ZK_AGENT_ACCOUNT_PROFILES_ROOT to a checked-out ${PACKAGE_NAME} package directory to enable artifact-backed built-in profile deploys.`
+        `Built-in profile assets are not available in this runtime. Set ZK_AGENT_ACCOUNT_PROFILES_ROOT to a checked-out ${PACKAGE_NAME} package directory to enable artifact-backed built-in profile deploys when source checkout is required.`
       ]
     ],
     buildConstructorArgs(context) {
@@ -12283,7 +12505,7 @@ function createSedLiteProfile() {
       "The first standalone policy hook, NativePerTxLimitHook, is now deployed and live-validated on zkSync Sepolia.",
       "The second standalone policy hook, TargetAllowlistHook, is now deployed and live-validated on zkSync Sepolia.",
       ...packageRootResolved ? [] : [
-        `Built-in profile assets are not available in this runtime. Set ZK_AGENT_ACCOUNT_PROFILES_ROOT to a checked-out ${PACKAGE_NAME} package directory to enable artifact-backed built-in profile deploys.`
+        `Built-in profile assets are not available in this runtime. Set ZK_AGENT_ACCOUNT_PROFILES_ROOT to a checked-out ${PACKAGE_NAME} package directory to enable artifact-backed built-in profile deploys when source checkout is required.`
       ]
     ],
     buildConstructorArgs(context) {
@@ -12755,7 +12977,7 @@ function requireSmartAccountWallet(wallet) {
   }
   return wallet;
 }
-function isRecord4(value) {
+function isRecord5(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function cloneWalletSessionRecord(wallet) {
@@ -12788,11 +13010,11 @@ function cloneWalletSessionRecord(wallet) {
   };
 }
 function isWalletExportRecord(value) {
-  return isRecord4(value) && value.format === "zk-agent-wallet-export" && value.version === 1 && typeof value.exportedAt === "string" && typeof value.sensitiveDataIncluded === "boolean" && isRecord4(value.wallet);
+  return isRecord5(value) && value.format === "zk-agent-wallet-export" && value.version === 1 && typeof value.exportedAt === "string" && typeof value.sensitiveDataIncluded === "boolean" && isRecord5(value.wallet);
 }
 function parseWalletExportRecord(value) {
   const raw = parseJsonInput(value);
-  const candidate = isRecord4(raw) && isRecord4(raw.export) ? raw.export : raw;
+  const candidate = isRecord5(raw) && isRecord5(raw.export) ? raw.export : raw;
   if (!isWalletExportRecord(candidate)) {
     throw new Error(
       'Restore payload must be a wallet export bundle created by "wallet export". You can pass either the raw export bundle or the full JSON output from "wallet export --json".'
@@ -12856,9 +13078,9 @@ function normalizeHexString2(value, label) {
 }
 function parseArtifactInput(value) {
   const raw = parseJsonInput(value);
-  if (!isRecord4(raw)) throw new Error("Artifact must be a JSON object");
+  if (!isRecord5(raw)) throw new Error("Artifact must be a JSON object");
   if (!Array.isArray(raw.abi)) throw new Error("Artifact must include an abi array");
-  const bytecodeCandidate = typeof raw.bytecode === "string" ? raw.bytecode : isRecord4(raw.evm) && isRecord4(raw.evm.bytecode) && typeof raw.evm.bytecode.object === "string" ? raw.evm.bytecode.object : void 0;
+  const bytecodeCandidate = typeof raw.bytecode === "string" ? raw.bytecode : isRecord5(raw.evm) && isRecord5(raw.evm.bytecode) && typeof raw.evm.bytecode.object === "string" ? raw.evm.bytecode.object : void 0;
   if (!bytecodeCandidate) {
     throw new Error("Artifact must include bytecode or evm.bytecode.object");
   }
@@ -12870,7 +13092,7 @@ function parseArtifactInput(value) {
       }
       return normalizeHexString2(entry, `factoryDeps[${index}]`);
     });
-  } else if (isRecord4(raw.factoryDeps)) {
+  } else if (isRecord5(raw.factoryDeps)) {
     factoryDeps = Object.values(raw.factoryDeps).map((entry, index) => {
       if (typeof entry !== "string") {
         throw new Error(`factoryDeps value ${index} must be a hex string`);
@@ -13922,7 +14144,7 @@ async function createWalletReapprovalRequest(options) {
   return request;
 }
 function ensureSessionPayload(value) {
-  if (!isRecord4(value)) {
+  if (!isRecord5(value)) {
     throw new Error("Approved callback payload must include a payload object.");
   }
   return value;
@@ -14201,7 +14423,7 @@ async function awaitLocalWalletApproval(options) {
         try {
           assertRequestActive(walletRequest.expiresAt);
           const body = await readLocalApprovalBody(requestMessage);
-          if (!isRecord4(body)) {
+          if (!isRecord5(body)) {
             throw new Error("Approved callback body must be a JSON object.");
           }
           const callbackRequestId = typeof body.requestId === "string" ? body.requestId : void 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zk-agent-cli",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.3",
   "description": "Local-first zkSync Era and ZK Stack agent CLI with wallet session recovery, workflow orchestration, relay-backed approval, and SED smart-account support.",
   "license": "MIT",
   "type": "module",