@mycadet/cli 0.12.7 → 0.12.9-dev.202610131452.9acab64

package/src/commands/tunnel.ts

@@ -1,4 +1,4 @@
-import { isManagedCloud } from "../lib/managed-cloud.js";
+import { isCloudHome } from "../lib/cloud-values.js";
 import { readFileSync } from "node:fs";
 import { join } from "path";
 
@@ -14,54 +14,50 @@ import {
   type AssistantEntry,
 } from "../lib/assistant-config";
 import { parseAssistantTargetArg } from "../lib/assistant-target-args.js";
-import { runCloudflareTunnel } from "../lib/cloudflare-tunnel.js";
 import { relaunchDetached } from "../lib/detached-process.js";
 import {
   getDefaultWorkspaceDir,
   isLocalContainerEntry,
   parseGatewayPortFromEntryUrls,
-  saveNgrokDomain,
 } from "../lib/ingress-config.js";
 import {
   ensureTunnelEdge,
-  formatEdgeMode,
+  getNginxVersion,
   type TunnelEdge,
 } from "../lib/nginx-ingress.js";
-import { hasWebhookIntegrationsConfigured, runNgrokTunnel } from "../lib/ngrok";
-import { shellArg } from "../lib/shell-arg.js";
+import { ensureBinaryInstalled } from "../lib/ensure-binary.js";
 import { STALE_CLI_UPDATE_HINT } from "../lib/stale-cli-hint.js";
-import { runTailscaleTunnel } from "../lib/tailscale-tunnel.js";
-
-// `cadet` is the managed option this command owns; the local providers come
-// from the shared registry so validation here cannot drift from what the
-// workspace config accepts.
-const VALID_PROVIDERS = ["cadet", ...TUNNEL_PROVIDERS] as const;
-type TunnelProvider = (typeof VALID_PROVIDERS)[number];
-
-// How far each provider's URL reaches, for the chooser a missing `--provider`
-// prints. Keyed off the registry so a new provider cannot ship unoffered.
-const PROVIDER_REACH: Record<TunnelProviderName, string> = {
-  ngrok: "Public tunnel that webhook integrations can reach",
-  cloudflare: "Public tunnel that webhook integrations can reach",
-  tailscale: "Tailnet-only tunnel, reachable from your own devices",
-};
+import {
+  ADOPTED_TUNNEL_RE,
+  DEFAULT_TUNNEL_PROVIDER,
+  PROVIDER_META,
+  adoptedTunnelStopNotice,
+  cadetTunnelComingSoonError,
+  clearReservedDomain,
+  hasWebhookIntegrationsConfigured,
+  providerSupportsReservedDomain,
+  runProviderTunnel,
+} from "../lib/tunnel.js";
+
+// The accepted `--provider` values ARE the shared registry, so validation
+// here cannot drift from what the workspace config accepts.
 
 interface TunnelArgs {
   assistantName: string | null;
-  provider: TunnelProvider;
+  provider: TunnelProviderName;
   domain: string | null;
   clearDomain: boolean;
-  detach: boolean;
+  foreground: boolean;
 }
 
 const FLAGS_WITH_VALUES = ["--provider", "--domain"] as const;
 
 function parseArgs(): TunnelArgs {
   const args = process.argv.slice(3);
-  let provider: TunnelProvider | null = null;
+  let provider: TunnelProviderName | null = null;
   let domain: string | null = null;
   let clearDomain = false;
-  let detach = false;
+  let foreground = false;
 
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -76,119 +72,115 @@ function parseArgs(): TunnelArgs {
       );
       console.log("");
       console.log(
-        "How far that URL reaches depends on the provider, so --provider is required.",
+        "How far that URL reaches depends on the provider; omit --provider for",
       );
       console.log(
-        "A tailscale tunnel is reachable only from your own tailnet; webhook",
+        "the default. A tailscale tunnel is reachable only from your",
       );
       console.log(
-        "integrations need a public tunnel: --provider ngrok or --provider cloudflare.",
+        "own tailnet; webhook integrations need a public tunnel. See Providers",
       );
+      console.log("below.");
       console.log("");
       console.log(
         "The tunnel always fronts the local nginx edge, which is started automatically.",
       );
       console.log(
-        "nginx must be installed (macOS: brew install nginx, Linux: sudo apt install nginx).",
+        "nginx must be installed; if it is missing, cadet offers to install it.",
       );
       console.log("");
       console.log("Arguments:");
       console.log(
-        "  <name>                        Name of the assistant (defaults to active or only local)",
+        "  <name>                        Name of the assistant, defaults to active or only local",
       );
       console.log("");
       console.log("Options:");
       console.log(
-        `  --provider <provider>         Required. Tunnel provider: ${VALID_PROVIDERS.join(", ")}`,
-      );
-      console.log(
-        "  --domain <domain>             Reserved ngrok domain to bind (ngrok provider only).",
-      );
-      console.log(
-        "                                Saved to the workspace config so `cadet wake` restores reuse it.",
-      );
-      console.log(
-        "  --clear-domain                Clear the saved ngrok domain (ngrok provider only) and tunnel",
-      );
-      console.log(
-        "                                without one. Cannot be combined with --domain.",
-      );
-      console.log(
-        `  -d, --detach                  Run the tunnel in the background. Waits up to ${TUNNEL_BACKGROUND_START_TIMEOUT_MS / 1000}s for the`,
-      );
-      console.log(
-        "                                initial established/failed status before returning; logs go to",
-      );
-      console.log(
-        "                                the CLI log directory. Stop it with `kill <pid>`, except when it",
+        `  --provider <provider>         Tunnel provider: ${TUNNEL_PROVIDERS.join(", ")} — default ${DEFAULT_TUNNEL_PROVIDER}`,
       );
       console.log(
-        "                                adopted an already-running ngrok tunnel (started outside this",
+        "  --domain <domain>             Reserved domain to bind, for providers that support",
       );
       console.log(
-        "                                command): killing the supervisor then leaves that tunnel running.",
+        "                                one. Saved to the workspace config so `cadet wake` restores",
       );
-      console.log("");
-      console.log("Providers:");
+      console.log("                                reuse it.");
       console.log(
-        "  cadet       Managed tunnel via Cadet Cloud (not yet available)",
+        "  --clear-domain                Clear the saved reserved domain (same providers) and",
       );
       console.log(
-        "  ngrok        ngrok tunnel — install: brew install ngrok/ngrok/ngrok",
+        "                                tunnel without one. Cannot be combined with --domain.",
       );
       console.log(
-        "  cloudflare   Cloudflare quick tunnel — install: brew install cloudflare/cloudflare/cloudflared",
+        `  --foreground                  Stream the tunnel's logs to this terminal. By default the tunnel`,
       );
       console.log(
-        "               No Cloudflare account required for quick tunnels.",
+        "                                runs in the background: the command returns after printing the public",
       );
       console.log(
-        "  tailscale    Tailscale serve. Install: https://tailscale.com/download, then run `tailscale up`",
+        `                                URL, and logs stream to tunnel.log in the CLI log directory. A background`,
       );
       console.log(
-        "               Reachable only from your own tailnet (private; LetsEncrypt cert).",
+        "                                tunnel stops with `kill <pid>`, except when it adopted an already-running",
       );
       console.log(
-        "               When webhook integrations are configured it records its URL for device",
+        "                                tunnel (started outside this command): killing the supervisor then",
       );
       console.log(
-        "               pairing only, leaving the saved webhook callback base as it is.",
+        "                                leaves that tunnel running.",
       );
       console.log("");
+      console.log("Providers:");
+      for (const name of TUNNEL_PROVIDERS) {
+        const meta = PROVIDER_META[name];
+        console.log(`  ${name.padEnd(12)}${meta.reach}`);
+        console.log(`  ${" ".repeat(12)}${meta.install}`);
+        for (const note of meta.notes ?? []) {
+          console.log(`  ${" ".repeat(12)}${note}`);
+        }
+      }
+      console.log("");
       console.log("Examples:");
-      console.log("  $ cadet tunnel --provider ngrok");
-      console.log(
-        "  $ cadet tunnel --provider ngrok --domain my-assistant.ngrok.app",
-      );
-      console.log("  $ cadet tunnel --provider ngrok --clear-domain");
+      console.log(`  $ cadet tunnel --provider ${DEFAULT_TUNNEL_PROVIDER}`);
+      const domainExample =
+        PROVIDER_META[DEFAULT_TUNNEL_PROVIDER].domainExample;
+      if (domainExample) {
+        console.log(
+          `  $ cadet tunnel --provider ${DEFAULT_TUNNEL_PROVIDER} --domain ${domainExample}`,
+        );
+        console.log(
+          `  $ cadet tunnel --provider ${DEFAULT_TUNNEL_PROVIDER} --clear-domain`,
+        );
+      }
       console.log("  $ cadet tunnel --provider cloudflare");
       console.log("  $ cadet tunnel my-assistant --provider tailscale");
-      console.log("  $ cadet tunnel --provider ngrok --detach");
       process.exit(0);
     } else if (arg === "--provider") {
       const next = args[i + 1];
       if (!next || next.startsWith("-")) {
         console.error(
-          `Error: --provider requires one of: ${VALID_PROVIDERS.join(", ")}`,
+          `Error: --provider requires one of: ${TUNNEL_PROVIDERS.join(", ")}`,
         );
         process.exit(1);
       }
-      if (!VALID_PROVIDERS.includes(next as TunnelProvider)) {
+      if (!TUNNEL_PROVIDERS.includes(next as TunnelProviderName)) {
         console.error(
-          `Error: unknown tunnel provider '${next}'. Valid providers: ${VALID_PROVIDERS.join(", ")}.`,
+          `Error: unknown tunnel provider '${next}'. Valid providers: ${TUNNEL_PROVIDERS.join(", ")}.`,
         );
         console.error(
           `If this provider is documented, ${STALE_CLI_UPDATE_HINT}`,
         );
         process.exit(1);
       }
-      provider = next as TunnelProvider;
+      provider = next as TunnelProviderName;
       i++;
     } else if (arg === "--domain") {
       const next = args[i + 1];
       if (!next || next.startsWith("-")) {
+        const domainExample =
+          PROVIDER_META[DEFAULT_TUNNEL_PROVIDER].domainExample;
         console.error(
-          "Error: --domain requires a value, e.g. --domain my-assistant.ngrok.app",
+          `Error: --domain requires a value${domainExample ? `, e.g. --domain ${domainExample}` : ""}`,
         );
         process.exit(1);
       }
@@ -196,8 +188,8 @@ function parseArgs(): TunnelArgs {
       i++;
     } else if (arg === "--clear-domain") {
       clearDomain = true;
-    } else if (arg === "-d" || arg === "--detach") {
-      detach = true;
+    } else if (arg === "--foreground") {
+      foreground = true;
     } else if (arg.startsWith("-")) {
       console.error(`Error: Unknown option '${arg}'.`);
       process.exit(1);
@@ -210,32 +202,20 @@ function parseArgs(): TunnelArgs {
     parseAssistantTargetArg(args, FLAGS_WITH_VALUES) ?? null;
 
   if (provider === null) {
-    console.error(
-      "Error: --provider is required. How far the tunnel URL reaches depends on it, so there is no default.",
-    );
-    console.error("");
-    console.error("Run one of:");
-    // Carries the assistant through: dropping it would suggest a command that
-    // tunnels the active assistant instead of the one that was asked for.
-    const target = assistantName ? ` ${shellArg(assistantName)}` : "";
-    for (const name of TUNNEL_PROVIDERS) {
-      console.error(
-        `  cadet tunnel${target} --provider ${name.padEnd(13)}${PROVIDER_REACH[name]}`,
-      );
-    }
-    process.exit(1);
+    provider = DEFAULT_TUNNEL_PROVIDER;
+    console.log(`Using the default provider: ${provider}.`);
   }
 
-  if (domain && provider !== "ngrok") {
+  if (domain && !providerSupportsReservedDomain(provider)) {
     console.error(
-      `Error: --domain is only supported with --provider ngrok (got '${provider}').`,
+      `Error: --domain is not supported with --provider ${provider} (reserved domains have no equivalent there).`,
     );
     process.exit(1);
   }
 
-  if (clearDomain && provider !== "ngrok") {
+  if (clearDomain && !providerSupportsReservedDomain(provider)) {
     console.error(
-      `Error: --clear-domain is only supported with --provider ngrok (got '${provider}').`,
+      `Error: --clear-domain is not supported with --provider ${provider} (reserved domains have no equivalent there).`,
     );
     process.exit(1);
   }
@@ -247,7 +227,7 @@ function parseArgs(): TunnelArgs {
     process.exit(1);
   }
 
-  return { assistantName, provider, domain, clearDomain, detach };
+  return { assistantName, provider, domain, clearDomain, foreground };
 }
 
 /** A tunnelable assistant plus the gateway port and workspace the edge fronts. */
@@ -259,7 +239,7 @@ interface LocalTunnelTarget {
 
 /**
  * Map an entry to its local tunnel target, or null when it has no locally
- * reachable gateway (e.g. platform-hosted). Entries with `resources` carry
+ * reachable gateway (e.g. cloud-hosted). Entries with `resources` carry
  * their own gateway port and instance workspace. Local container entries
  * (docker, apple-container) run locally without host resources: their gateway
  * port comes from localUrl/runtimeUrl and their ingress state lives in the
@@ -284,7 +264,7 @@ function toLocalTunnelTarget(entry: AssistantEntry): LocalTunnelTarget | null {
 
 function describeUntunnelableEntry(entry: AssistantEntry): string {
   const reference = formatAssistantReference(entry);
-  return isManagedCloud(entry.cloud)
+  return isCloudHome(entry.cloud)
     ? `Assistant '${reference}' runs on Cadet Cloud and needs no tunnel.`
     : `Assistant '${reference}' has no locally managed runtime to tunnel.`;
 }
@@ -292,7 +272,7 @@ function describeUntunnelableEntry(entry: AssistantEntry): string {
 /**
  * Resolve the assistant whose gateway and workspace the tunnel edge fronts.
  * Tunnels only make sense for assistants with a local gateway; when the
- * resolved entry has none (e.g. the active assistant is platform-hosted) and
+ * resolved entry has none (e.g. the active assistant is cloud-hosted) and
  * no name was given, fall back to the sole local target, otherwise exit with
  * an error naming the local assistants to pass explicitly.
  */
@@ -350,8 +330,8 @@ function guardTailnetOnlyWebhookIngress(workspaceDir: string): boolean {
   console.warn(
     "⚠ Webhook integrations are configured, and the tailscale tunnel is reachable only from your own tailnet, " +
       "so it cannot serve their callbacks. The saved ingress base URL stays as it is and the tailnet URL is " +
-      "recorded for device pairing only. For a tunnel those integrations can reach too, use --provider ngrok " +
-      "or --provider cloudflare.",
+      "recorded for device pairing only. For a tunnel those integrations can reach too, run `cadet tunnel --help` " +
+      "to see the public providers.",
   );
   return true;
 }
@@ -359,38 +339,37 @@ function guardTailnetOnlyWebhookIngress(workspaceDir: string): boolean {
 // Generous cap so a slow provider handshake (e.g. cloudflared's own ~30s
 // quick-tunnel timeout) still counts as a successful, if slow, start.
 const TUNNEL_BACKGROUND_START_TIMEOUT_MS = 35_000;
-// Matches the "just established" line every provider prints, or ngrok's
-// "found an already-running agent" adoption line (captured separately since
-// that case does not own the tunnel it adopted).
+// Matches the "just established" line every provider prints, or the adoption
+// line printed when a run adopts an already-running agent's tunnel (captured
+// separately since that case does not own the tunnel it adopted).
 const TUNNEL_ESTABLISHED_RE = /Tunnel established: (\S+)/;
-const TUNNEL_ADOPTED_RE = /Found existing ngrok tunnel: (\S+)/;
 
 /**
- * Re-invoke `cadet tunnel` (without `-d`/`--detach`) as a detached background
- * process via `relaunchDetached`, waiting for the child to either print its
- * "Tunnel established"/"Found existing ngrok tunnel" line (readiness) or
- * exit early (failure), so a misconfigured provider still fails loudly in
- * the terminal that ran `-d`.
+ * Re-invoke `cadet tunnel --foreground` as a detached background process via
+ * `relaunchDetached`, waiting for the child to either print its
+ * "Tunnel established" or adopted-tunnel line (readiness) or exit early
+ * (failure), so a misconfigured provider still fails loudly in the terminal
+ * that ran `cadet tunnel`.
  *
- * The log filename is scoped to this (parent) process's pid so concurrent
- * `-d` runs (e.g. tunneling two different local assistants at once) don't
- * truncate and read each other's readiness output.
+ * The log file is the fixed `tunnel.log` so there is one stable path to tail;
+ * concurrent tunnel runs share (and truncate) it.
  */
 async function spawnDetachedTunnel(): Promise<void> {
   const childArgs: string[] = ["tunnel"];
   for (const arg of process.argv.slice(3)) {
-    if (arg === "-d" || arg === "--detach") {
+    if (arg === "--foreground") {
       continue;
     }
     childArgs.push(arg);
   }
+  childArgs.push("--foreground");
 
   let publicUrl: string | undefined;
   let adopted = false;
 
   const { child, logPath, ready, exitCode } = await relaunchDetached({
     args: childArgs,
-    logFile: `tunnel-${process.pid}.log`,
+    logFile: "tunnel.log",
     timeoutMs: TUNNEL_BACKGROUND_START_TIMEOUT_MS,
     isReady: (logPath) => {
       let logText = "";
@@ -404,7 +383,7 @@ async function spawnDetachedTunnel(): Promise<void> {
         publicUrl = established[1];
         return true;
       }
-      const adoptedMatch = TUNNEL_ADOPTED_RE.exec(logText);
+      const adoptedMatch = ADOPTED_TUNNEL_RE.exec(logText);
       if (adoptedMatch) {
         publicUrl = adoptedMatch[1];
         adopted = true;
@@ -430,11 +409,7 @@ async function spawnDetachedTunnel(): Promise<void> {
   }
   console.log(`Running in background (pid ${child.pid}). Logs: ${logPath}`);
   if (adopted) {
-    console.log(
-      `That ngrok agent was already running outside this command, so \`kill ${child.pid}\` only ` +
-        "stops this supervisor, not the ngrok tunnel or its saved ingress URL. Stop the ngrok agent " +
-        "directly to end the tunnel.",
-    );
+    console.log(adoptedTunnelStopNotice(child.pid));
   } else {
     console.log(`Stop with: kill ${child.pid}`);
   }
@@ -442,72 +417,78 @@ async function spawnDetachedTunnel(): Promise<void> {
 
 export const tunnel = Object.assign(
   async function tunnel(): Promise<void> {
-  const { assistantName, provider, domain, clearDomain, detach } = parseArgs();
+    const { assistantName, provider, domain, clearDomain, foreground } =
+      parseArgs();
 
-  if (detach) {
-    await spawnDetachedTunnel();
-    return;
-  }
+    if (!foreground) {
+      await spawnDetachedTunnel();
+      return;
+    }
 
-  if (provider === "cadet") {
-    throw new Error(
-      `Tunnel provider '${provider}' is not yet implemented. ` +
-        `If this provider is documented, ${STALE_CLI_UPDATE_HINT}`,
-    );
-  }
+    if (PROVIDER_META[provider].comingSoon) {
+      throw cadetTunnelComingSoonError(provider);
+    }
 
-  const { entry, gatewayPort, workspaceDir } =
-    resolveLocalTunnelTarget(assistantName);
+    const { entry, gatewayPort, workspaceDir } =
+      resolveLocalTunnelTarget(assistantName);
 
-  const preserveIngressUrl =
-    provider === "tailscale" && guardTailnetOnlyWebhookIngress(workspaceDir);
+    const preserveIngressUrl =
+      provider === "tailscale" && guardTailnetOnlyWebhookIngress(workspaceDir);
 
-  if (clearDomain) {
-    saveNgrokDomain(workspaceDir, null);
-    console.log("Cleared the saved ngrok domain from the workspace config.");
-  }
+    if (clearDomain) {
+      clearReservedDomain();
+      console.log("Cleared the saved reserved domain.");
+    }
 
-  let edge: TunnelEdge;
-  try {
-    edge = await ensureTunnelEdge({
-      assistantId: entry.assistantId,
-      workspaceDir,
-      gatewayPort,
+    const nginxVersion = await ensureBinaryInstalled({
+      binary: "nginx",
+      purpose: "the tunnel edge",
+      packages: {
+        brew: ["brew", "install", "nginx"],
+        "apt-get": ["sudo", "apt-get", "install", "-y", "nginx"],
+        dnf: ["sudo", "dnf", "install", "-y", "nginx"],
+        pacman: ["sudo", "pacman", "-S", "--noconfirm", "nginx"],
+        zypper: ["sudo", "zypper", "install", "-y", "nginx"],
+        choco: ["choco", "install", "-y", "nginx"],
+      },
+      manualHint:
+        "See https://nginx.org/en/docs/install.html for how to install, or point NGINX_BIN at an existing binary.",
+      probe: getNginxVersion,
     });
-  } catch (err) {
-    console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
-    process.exit(1);
-  }
+    if (!nginxVersion) {
+      console.error("Error: nginx is required to run the tunnel edge.");
+      process.exit(1);
+    }
 
-  console.log(
-    `${edge.started ? "Started" : "Reusing"} the nginx edge on 127.0.0.1:${edge.port} ` +
-      `(serves ${formatEdgeMode(edge.includesWebApp)}).`,
-  );
+    let edge: TunnelEdge;
+    try {
+      edge = await ensureTunnelEdge({
+        assistantId: entry.assistantId,
+        workspaceDir,
+        gatewayPort,
+      });
+    } catch (err) {
+      console.error(
+        `Error: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      process.exit(1);
+    }
 
-  const baseTunnelOpts = {
-    port: edge.port,
-    assistantId: entry.assistantId,
-    workspaceDir,
-  };
+    console.log(
+      `${edge.started ? "Started" : "Reusing"} the nginx edge on 127.0.0.1:${edge.port}.`,
+    );
 
-  if (provider === "ngrok") {
-    await runNgrokTunnel({
+    const baseTunnelOpts = {
+      port: edge.port,
+      assistantId: entry.assistantId,
+      workspaceDir,
+    };
+
+    await runProviderTunnel(provider, {
       ...baseTunnelOpts,
       ...(domain ? { domain } : {}),
+      ...(preserveIngressUrl ? { preserveIngressUrl } : {}),
     });
-    return;
-  }
-
-  if (provider === "cloudflare") {
-    await runCloudflareTunnel(baseTunnelOpts);
-    return;
-  }
-
-  await runTailscaleTunnel({
-    ...baseTunnelOpts,
-    ...(preserveIngressUrl ? { preserveIngressUrl } : {}),
-  });
-},
+  },
   { description: "Create a tunnel for a locally hosted assistant" },
 );
-