surf-cli 2.8.0 → 2.10.0

package/native/do-parser.cjs

@@ -1,250 +1,9 @@
-/**
- * Parser for surf `do` workflow commands
- * 
- * Parses newline-separated commands into structured step arrays:
- * 
- * Input:
- *   'go "https://example.com"
- *    click e5
- *    screenshot'
- * 
- * Output:
- *   [
- *     { cmd: 'navigate', args: { url: 'https://example.com' } },
- *     { cmd: 'click', args: { ref: 'e5' } },
- *     { cmd: 'screenshot', args: {} }
- *   ]
- */
-
-// Aliases mapping (matches cli.cjs)
-const ALIASES = {
-  snap: "screenshot",
-  read: "page.read",
-  find: "search",
-  go: "navigate",
-  net: "network",
-  "network.dump": "network.get",
-};
-
-// Primary argument mapping for positional args (matches cli.cjs)
-const PRIMARY_ARG_MAP = {
-  ai: "query",
-  gemini: "query",
-  chatgpt: "query",
-  perplexity: "query",
-  grok: "query",
-  navigate: "url",
-  go: "url",
-  js: "code",
-  javascript_tool: "code",
-  key: "key",
-  wait: "duration",
-  health: "url",
-  new_tab: "url",
-  "tab.new": "url",
-  switch_tab: "tab_id",
-  "tab.switch": "id",
-  close_tab: "tab_id",
-  "tab.close": "id",
-  "tab.name": "name",
-  "tab.unname": "name",
-  scroll_to_position: "position",
-  type: "text",
-  smart_type: "text",
-  "emulate.network": "preset",
-  "emulate.cpu": "rate",
-  search: "term",
-  find: "term",
-  "wait.element": "selector",
-  "wait.url": "pattern",
-  zoom: "level",
-  "history.search": "query",
-  "network.get": "id",
-  "network.body": "id",
-  "network.curl": "id",
-  "network.path": "id",
-  "window.new": "url",
-  "window.focus": "id",
-  "window.close": "id",
-  "locate.role": "role",
-  "locate.text": "text",
-  "locate.label": "label",
-  "emulate.device": "device",
-  "frame.js": "code",
-  "element.styles": "selector",
-  "select": "selector",
-};
-
-/**
- * Tokenize a command line, respecting single and double quotes
- * @param {string} line - Single line to tokenize
- * @returns {string[]} - Array of tokens
- */
-function tokenize(line) {
-  const tokens = [];
-  let current = '';
-  let inQuote = null;
-  
-  for (let i = 0; i < line.length; i++) {
-    const ch = line[i];
-    
-    if (inQuote) {
-      if (ch === inQuote) {
-        // End of quoted string
-        inQuote = null;
-      } else {
-        current += ch;
-      }
-    } else if (ch === '"' || ch === "'") {
-      // Start of quoted string
-      inQuote = ch;
-    } else if (ch === ' ' || ch === '\t') {
-      // Whitespace separator
-      if (current) {
-        tokens.push(current);
-        current = '';
-      }
-    } else {
-      current += ch;
-    }
-  }
-  
-  // Don't forget last token
-  if (current) {
-    tokens.push(current);
-  }
-  
-  return tokens;
-}
-
-/**
- * Parse a single command line into a step object
- * @param {string} line - Single command line
- * @returns {{ cmd: string, args: object } | null}
- */
-function parseCommandLine(line) {
-  const tokens = tokenize(line);
-  if (tokens.length === 0) return null;
-  
-  // Get command and apply alias
-  let cmd = tokens[0];
-  cmd = ALIASES[cmd] || cmd;
-  
-  const args = {};
-  let i = 1;
-  
-  // Handle first positional argument based on command type
-  if (i < tokens.length && !tokens[i].startsWith('--')) {
-    const firstArg = tokens[i];
-    
-    // Special handling for click command
-    if (cmd === 'click') {
-      if (/^e\d+$/.test(firstArg)) {
-        // Element reference: e5 -> ref
-        args.ref = firstArg;
-        i++;
-      } else if (/^\d+$/.test(firstArg) && tokens[i + 1] && /^\d+$/.test(tokens[i + 1])) {
-        // Coordinates: 100 200 -> x, y
-        args.x = parseInt(firstArg, 10);
-        args.y = parseInt(tokens[i + 1], 10);
-        i += 2;
-      }
-    } else if (cmd === 'select') {
-      // Select takes selector + one or more values: select e5 "US" or select e5 "opt1" "opt2"
-      args.selector = firstArg;
-      i++;
-      // Collect remaining positional args as values
-      const values = [];
-      while (i < tokens.length && !tokens[i].startsWith('--')) {
-        values.push(tokens[i]);
-        i++;
-      }
-      // Host expects 'values' (always), matching CLI behavior
-      if (values.length === 1) {
-        args.values = values[0];  // Single value as string (host will wrap in array)
-      } else if (values.length > 1) {
-        args.values = values;     // Multiple values as array
-      }
-    } else if (cmd === 'scroll') {
-      if (firstArg === 'top' || firstArg === 'bottom') {
-        cmd = `scroll.${firstArg}`;
-        i++;
-      } else if (['up', 'down', 'left', 'right'].includes(firstArg)) {
-        args.direction = firstArg;
-        i++;
-        if (i < tokens.length && /^-?\d+$/.test(tokens[i])) {
-          args.scroll_pixels = parseInt(tokens[i], 10);
-          i++;
-        }
-      }
-    } else {
-      // Use PRIMARY_ARG_MAP for other commands
-      const primaryKey = PRIMARY_ARG_MAP[cmd];
-      if (primaryKey) {
-        args[primaryKey] = firstArg;
-        i++;
-      }
-    }
-  }
-  
-  // Parse --flag value pairs
-  while (i < tokens.length) {
-    const token = tokens[i];
-    if (token.startsWith('--')) {
-      const key = token.slice(2);
-      const next = tokens[i + 1];
-      if (next && !next.startsWith('--')) {
-        // Flag with value
-        let val = next;
-        // Type coercion
-        if (val === "true") val = true;
-        else if (val === "false") val = false;
-        else if (/^-?\d+$/.test(val)) val = parseInt(val, 10);
-        else if (/^-?\d+\.\d+$/.test(val)) val = parseFloat(val);
-        args[key] = val;
-        i += 2;
-      } else {
-        // Boolean flag
-        args[key] = true;
-        i++;
-      }
-    } else {
-      // Skip unrecognized positional (shouldn't happen normally)
-      i++;
-    }
-  }
-  
-  return { cmd, args };
-}
-
-/**
- * Parse a workflow string into step array
- * Supports pipe-separated (inline) or newline-separated (file) commands
- * @param {string} input - Workflow string
- * @returns {Array<{ cmd: string, args: object }>}
- */
-function parseDoCommands(input) {
-  // Determine separator: use pipe if present, otherwise newlines
-  // Pipe is preferred for inline: 'go "url" | click e5 | screenshot'
-  // Newlines for files or heredocs
-  const hasPipe = input.includes('|');
-  const separator = hasPipe ? '|' : '\n';
-  
-  // Also handle literal \n for backwards compatibility
-  const normalized = hasPipe ? input : input.replace(/\\n/g, '\n');
-  
-  return normalized
-    .split(separator)
-    .map(line => line.trim())
-    .filter(line => line && !line.startsWith('#'))
-    .map(line => parseCommandLine(line))
-    .filter(step => step !== null);
-}
-
-module.exports = { 
-  parseDoCommands, 
-  parseCommandLine, 
-  tokenize,
-  ALIASES,
-  PRIMARY_ARG_MAP
+const definition = require("./workflow-definition.cjs");
+
+module.exports = {
+  ALIASES: definition.ALIASES,
+  PRIMARY_ARG_MAP: definition.PRIMARY_ARG_MAP,
+  parseCommandLine: definition.parseCommandLine,
+  parseDoCommands: definition.parseDoCommands,
+  tokenize: definition.tokenize,
 };

package/native/doctor.cjs

@@ -3,6 +3,7 @@ const net = require("net");
 const os = require("os");
 const path = require("path");
 const { execFileSync } = require("child_process");
+const { connectEndpoint, selectEndpoint } = require("./endpoint.cjs");
 
 const HOST_NAME = "surf.browser.host";
 
@@ -402,6 +403,16 @@ function buildRecommendations(report) {
   return Array.from(new Set(recommendations));
 }
 
+function remoteRecommendations(endpoint, code) {
+  const base = [`Confirm Surf is listening on ${endpoint.display}; the remote host listener must allow this Tailnet connection.`];
+  if (code === "ENOTFOUND") return [...base, "Check the Tailnet DNS name, then run `tailscale status` and `tailscale ping <host>`."].map((item) => item.replace("<host>", endpoint.host));
+  if (code === "ETIMEDOUT") return [...base, `Run \`tailscale ping ${endpoint.host}\`; check restrictive Tailnet ACLs/grants and host firewall rules.`];
+  if (code === "ECONNREFUSED") return [...base, "Verify the host process is running and bound to the requested TCP port; check restrictive Tailnet ACLs/grants."];
+  if (code === "ENETUNREACH" || code === "EHOSTUNREACH") return [...base, `Run \`tailscale status\` and \`tailscale ping ${endpoint.host}\`; check Tailnet routing plus restrictive ACLs/grants.`];
+  if (code === "EAUTH") return [...base, "Verify the client credential path, pinned host identity, and that the labeled client has not been revoked."].map((item) => item.replace("<host>", endpoint.host));
+  return base;
+}
+
 async function runDoctor(rawOptions = {}, deps = {}) {
   const env = deps.env || process.env;
   const platform = deps.platform || process.platform;
@@ -413,6 +424,41 @@ async function runDoctor(rawOptions = {}, deps = {}) {
     socket: rawOptions.socket || env.SURF_SOCKET || defaultSocketPath(platform),
     connectTimeoutMs: rawOptions.connectTimeoutMs ?? 750,
   };
+  const selectedEndpoint = rawOptions.endpoint || selectEndpoint([], env).endpoint;
+  if (selectedEndpoint.kind === "remote") {
+    const endpoint = selectedEndpoint;
+    const connection = await (deps.connectEndpoint || ((target, timeoutMs) => new Promise((resolve) => {
+      let settled = false;
+      let socket;
+      const finish = (result) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timeout);
+        socket?.destroy();
+        resolve(result);
+      };
+      const timeout = setTimeout(() => finish({
+        ok: false,
+        code: socket?.connected ? "EAUTH" : "ETIMEDOUT",
+        message: socket?.connected ? "remote authentication timed out" : `timed out after ${timeoutMs}ms`,
+      }), timeoutMs);
+      socket = connectEndpoint(target, () => finish({ ok: true, message: "authenticated" }));
+      socket.once("error", (error) => finish({ ok: false, code: error.code, message: error.message || String(error) }));
+    })))(endpoint, options.connectTimeoutMs);
+    const checks = [{ id: "remote-endpoint", status: "info", message: `Remote endpoint: ${endpoint.display}`, endpoint: endpoint.display }, {
+      id: "remote-connect", status: connection.ok ? "pass" : "fail",
+      message: connection.ok ? `Connected to remote endpoint ${endpoint.display}` : `Could not connect to remote endpoint ${endpoint.display}: ${connection.message}`,
+      code: connection.code,
+    }, {
+      id: "remote-auth", status: connection.ok ? "pass" : connection.code === "EAUTH" ? "fail" : "info",
+      message: connection.ok ? "Remote credential authenticated and server identity verified" : connection.code === "EAUTH" ? "Remote credential rejected, revoked, or server identity mismatch" : "Remote authentication was not reached",
+      code: connection.code,
+    }];
+    const summary = summarize(checks);
+    const report = { ok: connection.ok, summary, environment: { platform, remoteEndpoint: endpoint.display, endpointKind: "remote", browsers: [] }, manifests: [], checks };
+    report.recommendations = connection.ok ? [] : remoteRecommendations(endpoint, connection.code);
+    return report;
+  }
   const effectiveTarget = resolveEffectiveTarget(options, { platform, runningInWsl });
   const browsers = resolveBrowsers(options.browser);
   const context = {
@@ -502,9 +548,13 @@ function formatCheck(check) {
 function formatDoctorReport(report) {
   const lines = ["Surf doctor", ""];
   lines.push(`Platform: ${report.environment.platform}${report.environment.runningInWsl ? " (WSL2 detected)" : ""}`);
-  lines.push(`Target: ${report.environment.effectiveTarget === "wsl-windows" ? "Windows browser from WSL2" : report.environment.effectiveTarget}`);
-  lines.push(`Socket: ${report.environment.socketPath}`);
-  lines.push(`Browsers: ${report.environment.browsers.join(", ")}`);
+  if (report.environment.endpointKind === "remote") {
+    lines.push(`Remote endpoint: ${report.environment.remoteEndpoint}`);
+  } else {
+    lines.push(`Target: ${report.environment.effectiveTarget === "wsl-windows" ? "Windows browser from WSL2" : report.environment.effectiveTarget}`);
+  }
+  if (report.environment.socketPath) lines.push(`Socket: ${report.environment.socketPath}`);
+  if (report.environment.browsers.length) lines.push(`Browsers: ${report.environment.browsers.join(", ")}`);
   lines.push("");
 
   for (const check of report.checks.filter((item) => item.status !== "info")) {
@@ -542,7 +592,7 @@ Examples:
 `;
 }
 
-async function runDoctorCli(rawArgs) {
+async function runDoctorCli(rawArgs, endpoint) {
   let options;
   try {
     options = parseDoctorArgs(rawArgs);
@@ -558,7 +608,7 @@ async function runDoctorCli(rawArgs) {
   }
 
   try {
-    const report = await runDoctor(options);
+    const report = await runDoctor({ ...options, endpoint });
     if (options.json) {
       console.log(JSON.stringify(report, null, 2));
     } else {

package/native/endpoint.cjs

@@ -0,0 +1,174 @@
+const net = require("net");
+const { DEFAULT_SOCKET_PATH } = require("./socket-path.cjs");
+const { authenticateClient } = require("./remote-transport.cjs");
+
+function parseRemoteEndpoint(value) {
+  if (typeof value !== "string" || !value) throw new Error("--remote requires host:port");
+  let host;
+  let portText;
+  if (value.startsWith("[")) {
+    const match = value.match(/^\[([^\]]+)\]:(\d+)$/);
+    if (!match || net.isIP(match?.[1]) !== 6) throw new Error("remote endpoint must use a bracketed IPv6 address and port");
+    [, host, portText] = match;
+    host = new URL(`http://[${host}]`).hostname.slice(1, -1);
+  } else {
+    const match = value.match(/^([^:]+):(\d+)$/);
+    if (!match) throw new Error("remote endpoint must be host:port (IPv6 must be bracketed)");
+    [, host, portText] = match;
+    if (host.includes("/") || host.includes("@") || host.includes(":") || host === "*" || host.includes("*")) throw new Error("remote endpoint host is invalid");
+    if ((/^\d+(?:\.\d+){3}$/.test(host) && net.isIP(host) !== 4) || (net.isIP(host) !== 4 && !/^(?=.{1,253}$)(?:[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?\.)*[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?$/.test(host))) {
+      throw new Error("remote endpoint host is invalid");
+    }
+    host = host.toLowerCase();
+  }
+  const port = Number(portText);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error("remote endpoint port must be between 1 and 65535");
+  if ((net.isIP(host) === 4 && host === "0.0.0.0") || (net.isIP(host) === 6 && /^0*:?0*$/.test(host.replace(/:/g, "")))) {
+    throw new Error("remote endpoint host must not be unspecified");
+  }
+  const display = net.isIP(host) === 6 ? `[${host}]:${port}` : `${host}:${port}`;
+  return { kind: "remote", host, port, display, key: `tcp:${display}`, connectionOptions: { host, port } };
+}
+
+function selectEndpoint(args, env) {
+  const selectedEnv = env === undefined ? process.env : env;
+  const remoteIndexes = [];
+  const credentialIndexes = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--remote") remoteIndexes.push(i);
+    if (args[i] === "--remote-credential") credentialIndexes.push(i);
+  }
+  if (remoteIndexes.length > 1) throw new Error("--remote may only be specified once");
+  if (credentialIndexes.length > 1) throw new Error("--remote-credential may only be specified once");
+  let cliRemote;
+  let cliCredential;
+  const strippedArgs = [...args];
+  if (remoteIndexes.length) {
+    const index = remoteIndexes[0];
+    cliRemote = args[index + 1];
+    if (!cliRemote || cliRemote.startsWith("--")) throw new Error("--remote requires host:port");
+    strippedArgs.splice(index, 2);
+  }
+  if (credentialIndexes.length) {
+    const index = credentialIndexes[0];
+    cliCredential = args[index + 1];
+    if (!cliCredential || cliCredential.startsWith("--")) throw new Error("--remote-credential requires a file path");
+    const adjustedIndex = index - (remoteIndexes.length && index > remoteIndexes[0] ? 2 : 0);
+    strippedArgs.splice(adjustedIndex, 2);
+  }
+  const remoteValue = cliRemote || selectedEnv.SURF_REMOTE;
+  if (remoteValue) {
+    const credentialPath = cliCredential || selectedEnv.SURF_REMOTE_CREDENTIAL;
+    if (!credentialPath) throw new Error("remote endpoint requires --remote-credential <path> or SURF_REMOTE_CREDENTIAL");
+    return { args: strippedArgs, endpoint: { ...parseRemoteEndpoint(remoteValue), credentialPath } };
+  }
+  if (cliCredential) throw new Error("--remote-credential requires a remote endpoint");
+  const socketPath = selectedEnv.SURF_SOCKET || DEFAULT_SOCKET_PATH;
+  return { args: strippedArgs, endpoint: { kind: "local", path: socketPath, display: socketPath, key: `unix:${socketPath}`, connectionOptions: socketPath } };
+}
+
+function createRemoteSocket(endpoint) {
+  const rawSocket = net.createConnection(endpoint.connectionOptions, () => {});
+  let ready = false;
+  let connected = false;
+  let destroyed = false;
+  const pending = new Map();
+  const queue = (event, listener, once) => {
+    if (ready) {
+      once ? rawSocket.once(event, listener) : rawSocket.on(event, listener);
+      return;
+    }
+    const listeners = pending.get(event) || [];
+    listeners.push({ listener, once });
+    pending.set(event, listeners);
+  };
+  const flush = () => {
+    ready = true;
+    for (const [event, listeners] of pending) {
+      for (const { listener, once } of listeners) {
+        once ? rawSocket.once(event, listener) : rawSocket.on(event, listener);
+      }
+    }
+    pending.clear();
+  };
+  const proxy = {
+    on(event, listener) { queue(event, listener, false); return proxy; },
+    once(event, listener) { queue(event, listener, true); return proxy; },
+    removeListener(event, listener) {
+      if (ready) rawSocket.removeListener(event, listener);
+      else pending.set(event, (pending.get(event) || []).filter((entry) => entry.listener !== listener));
+      return proxy;
+    },
+    write(...args) { return rawSocket.write(...args); },
+    end(...args) { return rawSocket.end(...args); },
+    destroy(...args) { destroyed = true; return rawSocket.destroy(...args); },
+    setTimeout(...args) { rawSocket.setTimeout(...args); return proxy; },
+    get authenticated() { return ready; },
+    get connected() { return connected; },
+  };
+  rawSocket.once("connect", () => { connected = true; });
+  rawSocket.on("error", (error) => {
+    if (ready || destroyed) return;
+    ready = true;
+    const listeners = pending.get("error") || [];
+    pending.delete("error");
+    for (const { listener } of listeners) listener(error);
+    if (proxy.__pendingErrors) proxy.__pendingErrors.length = 0;
+    flush();
+  });
+  rawSocket.on("close", () => {
+    if (ready) return;
+    ready = true;
+    const error = new Error("remote authentication connection closed");
+    for (const { listener } of pending.get("error") || []) listener(error);
+    for (const { listener } of pending.get("close") || []) listener();
+    pending.clear();
+    if (proxy.__pendingErrors) proxy.__pendingErrors.length = 0;
+  });
+  return { rawSocket, proxy, flush };
+}
+
+function connectEndpoint(endpoint, onConnect) {
+  if (endpoint.kind === "local") {
+    return net.createConnection(endpoint.connectionOptions, onConnect || (() => {}));
+  }
+  const { rawSocket, proxy, flush } = createRemoteSocket(endpoint);
+  rawSocket.once("connect", () => {
+    authenticateClient(rawSocket, endpoint.credentialPath)
+      .then(() => {
+        flush();
+        if (onConnect) onConnect(proxy);
+      })
+      .catch((error) => {
+        error.code = error.code || "EAUTH";
+        const listeners = proxy.__pendingErrors || [];
+        for (const listener of listeners) {
+          proxy.removeListener("error", listener);
+          listener(error);
+        }
+        proxy.__pendingErrors.length = 0;
+        flush();
+        proxy.destroy();
+      });
+  });
+  proxy.__pendingErrors = [];
+  const originalOn = proxy.on;
+  const originalOnce = proxy.once;
+  proxy.on = (event, listener) => {
+    if (event === "error" && !proxy.authenticated) proxy.__pendingErrors.push(listener);
+    return originalOn(event, listener);
+  };
+  proxy.once = (event, listener) => {
+    if (event === "error" && !proxy.authenticated) proxy.__pendingErrors.push(listener);
+    return originalOnce(event, listener);
+  };
+  return proxy;
+}
+
+function formatEndpointError(error, endpoint, formatSocketError) {
+  if (endpoint.kind === "local") return formatSocketError(error);
+  const message = error?.message || String(error);
+  return `Remote endpoint connection failed (${endpoint.display}): ${message}`;
+}
+
+module.exports = { parseRemoteEndpoint, selectEndpoint, connectEndpoint, formatEndpointError };