@mycadet/cli 0.12.7 → 0.12.9

package/src/lib/{ngrok.ts → tunnels/ngrok.ts}

@@ -1,18 +1,32 @@
 import { execFileSync, spawn, type ChildProcess } from "node:child_process";
-import { closeSync, existsSync, mkdirSync, openSync } from "node:fs";
+import {
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
 import { dirname, join } from "node:path";
 
-import { GATEWAY_PORT } from "./constants.js";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+
+import { GATEWAY_PORT } from "../constants.js";
+import { clearRootProcess, stampRootProcess } from "../assistant-config.js";
+import { ensureBinaryInstalled, readLineText } from "../ensure-binary.js";
 import {
   clearIngressUrl,
   getDefaultWorkspaceDir,
-  loadNgrokDomain,
   loadRawConfig,
   saveIngressUrl,
-  saveNgrokDomain,
-} from "./ingress-config.js";
-import { loopbackSafeFetch } from "./loopback-fetch.js";
+} from "../ingress-config.js";
+import { getConfigDir } from "../environments/paths.js";
+import { getCurrentEnvironment } from "../environments/resolve.js";
+import { loopbackSafeFetch } from "../loopback-fetch.js";
+import { readProcessCommandLine } from "../process.js";
 import { z } from "zod";
+import type { ProviderMeta, ProviderTunnelResult } from "../tunnel.js";
+import { notifyGatewayOfPublicUrl } from "./gateway-notify.js";
 
 const NGROK_API_URL = "http://127.0.0.1:4040/api/tunnels";
 const NGROK_POLL_INTERVAL_MS = 500;
@@ -42,6 +56,14 @@ export const IngressConfigSchema = z.object({
   publicBaseUrl: z.string().optional(),
 });
 
+/** Per-provider copy `cadet tunnel`'s help renders for ngrok. */
+export const NGROK_TUNNEL_META: ProviderMeta = {
+  reach: "Public tunnel that webhook integrations can reach",
+  install: "install: brew install ngrok/ngrok/ngrok",
+  domainExample: "my-assistant.ngrok.app",
+  supportsReservedDomain: true,
+};
+
 /**
  * Check whether ngrok is installed and accessible on the PATH.
  * Returns the version string if installed, null otherwise.
@@ -60,6 +82,52 @@ export function getNgrokVersion(): string | null {
   }
 }
 
+/** Whether captured agent output says the startup failure was authentication. */
+export function isNgrokAuthError(output: string): boolean {
+  return /authtoken|authenticat|unauthorized|usage limit|ERR_NGROK_10\d\d|ERR_NGROK_40\d\d/i.test(
+    output,
+  );
+}
+
+/** An ngrok agent that exited during startup, with its captured output. */
+export class NgrokStartupError extends Error {
+  readonly exitCode: number;
+  readonly output: string;
+
+  constructor(exitCode: number, output: string) {
+    super(`ngrok exited with code ${exitCode}`);
+    this.exitCode = exitCode;
+    this.output = output;
+  }
+}
+
+/** Paste-in attempts before the tunnel command gives up and says how. */
+const MAX_AUTH_RETRIES = 2;
+
+/**
+ * Run `ngrok config add-authtoken <token>` — writing the user's default
+ * ngrok config, which is exactly the config the tunnel spawn loads. The
+ * token is never echoed: output is piped and any failure message has the
+ * token scrubbed.
+ */
+export function saveNgrokAuthToken(token: string): boolean {
+  try {
+    execFileSync("ngrok", ["config", "add-authtoken", token], {
+      encoding: "utf-8",
+      timeout: 10_000,
+      stdio: ["ignore", "pipe", "pipe"],
+      windowsHide: true,
+    });
+    return true;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(
+      `⚠ Couldn't save the authtoken: ${message.replaceAll(token, "***")}`,
+    );
+    return false;
+  }
+}
+
 /**
  * Query the ngrok local API for running tunnels.
  * Returns the list of tunnels, or null if the API is unreachable.
@@ -118,9 +186,106 @@ function staleAgentDiagnostic(tunnels: NgrokTunnel[], port: number): string {
 
 /** Recovery copy for a saved domain whose reservation may have lapsed. */
 function savedDomainRecoveryHint(domain: string): string {
-  return `The saved ngrok domain '${domain}' (ingress.ngrok.domain in the workspace config) may no longer be reserved. Run \`cadet tunnel --provider ngrok --clear-domain\` to drop it and tunnel without one.`;
+  return `The saved ngrok domain '${domain}' (${ngrokConfigPath()}) may no longer be reserved. Run \`cadet tunnel --provider ngrok --clear-domain\` to drop it and tunnel without one.`;
+}
+
+const NGROK_TUNNEL_NAME = "cadet";
+
+const NgrokTunnelDefSchema = z.looseObject({
+  proto: z.string().optional(),
+  addr: z.string().optional(),
+  domain: z.string().optional(),
+});
+
+const NgrokConfigFileSchema = z.looseObject({
+  version: z.string().optional(),
+  tunnels: z.record(z.string(), NgrokTunnelDefSchema).optional(),
+});
+
+type NgrokConfigFile = z.infer<typeof NgrokConfigFileSchema>;
+type NgrokTunnelDef = z.infer<typeof NgrokTunnelDefSchema>;
+
+/**
+ * The ngrok-format config file this CLI owns in the XDG config dir. It no
+ * longer participates in spawning (plain `ngrok http` loads the user's
+ * default config, keeping their authtoken in play); it is the source of
+ * truth for the reserved domain at this layer — the workspace config no
+ * longer records one.
+ */
+export function ngrokConfigPath(): string {
+  return join(getConfigDir(getCurrentEnvironment()), "tunnels", "ngrok.yaml");
+}
+
+function readNgrokConfigFile(): NgrokConfigFile {
+  const path = ngrokConfigPath();
+  if (!existsSync(path)) return {};
+  try {
+    const parsed = NgrokConfigFileSchema.safeParse(
+      parseYaml(readFileSync(path, "utf-8")),
+    );
+    return parsed.success ? parsed.data : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeNgrokConfigFile(config: NgrokConfigFile): void {
+  const path = ngrokConfigPath();
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, stringifyYaml(config));
+}
+
+/**
+ * Persist a reserved ngrok domain in the XDG ngrok config; null clears it.
+ *
+ * The reserved domain is an ngrok reservation concept (cloudflare quick
+ * tunnels and tailscale serve have no equivalent), which is why this lives in
+ * the ngrok provider module rather than the shared ingress-config helpers.
+ */
+export function saveNgrokDomain(domain: string | null): void {
+  const config = readNgrokConfigFile();
+  const cadet: NgrokTunnelDef = {
+    ...config.tunnels?.[NGROK_TUNNEL_NAME],
+    proto: "http",
+  };
+  if (domain) {
+    cadet.domain = domain;
+  } else {
+    delete cadet.domain;
+  }
+  const tunnels: Record<string, NgrokTunnelDef> = { ...config.tunnels };
+  tunnels[NGROK_TUNNEL_NAME] = cadet;
+  const next: NgrokConfigFile = { ...config, version: config.version ?? "2" };
+  next.tunnels = tunnels;
+  writeNgrokConfigFile(next);
+}
+
+/** Read the reserved ngrok domain from the XDG ngrok config, if saved. */
+export function loadNgrokDomain(): string | null {
+  const domain = readNgrokConfigFile().tunnels?.[NGROK_TUNNEL_NAME]?.domain;
+  return domain?.trim() ? domain : null;
 }
 
+/**
+ * Check whether a PID belongs to an ngrok process via its command line, so a
+ * recorded pid is verified before it is signaled (PID reuse guard).
+ */
+export function isNgrokProcess(pid: number): boolean {
+  try {
+    return /ngrok/i.test(readProcessCommandLine(pid));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Matches the adoption line the tunnel workflows print when they find an
+ * already-running tunnel, so the detached-tunnel supervisor can detect
+ * adoption without this module's implementation details leaking into the
+ * command layer.
+ */
+export const ADOPTED_TUNNEL_RE = /Found existing ngrok tunnel: (\S+)/;
+
 /** Whether a tunnel public URL's host equals the given reserved domain. */
 function urlMatchesDomain(publicUrl: string, domain: string): boolean {
   try {
@@ -132,16 +297,34 @@ function urlMatchesDomain(publicUrl: string, domain: string): boolean {
   }
 }
 
+/** The argv for an ngrok agent forwarding the edge port, domain when set. */
+export function buildNgrokSpawnArgs(
+  targetPort: number,
+  domain?: string,
+): string[] {
+  const args = ["http", `127.0.0.1:${targetPort}`, "--log=stdout"];
+  if (domain) {
+    args.push(`--domain=${domain}`);
+  }
+  return args;
+}
+
 /**
  * Start an ngrok process tunneling HTTP traffic to the given local port.
  *
+ * Plain `ngrok http` is spawned deliberately: ngrok only loads the user's
+ * default config — where `ngrok config add-authtoken` writes — when no
+ * `--config` is passed, so this is what keeps the authtoken in play. The
+ * explicit `127.0.0.1:` host avoids a bare port, which ngrok expands to
+ * `localhost`, whose ::1 answer resolves first on macOS and races the edge's
+ * IPv4 bind.
+ *
  * When `logFilePath` is provided, stdout/stderr are redirected to that file
  * instead of being piped. This avoids keeping pipe handles open in the
  * parent process — which would either prevent the CLI from exiting (if
  * handles are left open) or send SIGPIPE to ngrok (if destroyed).
  *
- * When `domain` is set, the tunnel binds that reserved ngrok domain via
- * `--domain=<domain>`.
+ * When `domain` is set, the spawned tunnel binds that reserved ngrok domain.
  *
  * Returns the spawned child process.
  */
@@ -159,14 +342,7 @@ export function startNgrokProcess(
     stdio = ["ignore", fd, fd];
   }
 
-  // Explicit over a bare port, which ngrok expands to `localhost`, whose ::1
-  // answer resolves first on macOS and races the edge's IPv4 bind.
-  const args = ["http", `127.0.0.1:${targetPort}`, "--log=stdout"];
-  if (domain) {
-    args.push(`--domain=${domain}`);
-  }
-
-  const child = spawn("ngrok", args, {
+  const child = spawn("ngrok", buildNgrokSpawnArgs(targetPort, domain), {
     detached: true,
     stdio,
     windowsHide: true,
@@ -225,10 +401,7 @@ export function hasWebhookIntegrations(
   const telegram = TelegramIntegrationSchema.safeParse(config.telegram);
   if (telegram.success && telegram.data.botUsername) return true;
   const twilio = TwilioIntegrationSchema.safeParse(config.twilio);
-  if (
-    twilio.success &&
-    (twilio.data.accountSid || twilio.data.phoneNumber)
-  ) {
+  if (twilio.success && (twilio.data.accountSid || twilio.data.phoneNumber)) {
     return true;
   }
   return false;
@@ -282,7 +455,7 @@ export async function maybeStartNgrokTunnel(
   workspaceDir: string,
   assistantId?: string,
 ): Promise<ChildProcess | null> {
-  // Managed/containerized deployments route webhooks through the platform's
+  // Managed/containerized deployments route webhooks through the cloud's
   // callback proxy. ngrok is not needed and would not be reachable from the
   // platform anyway — skip it entirely.
   const isContainerized =
@@ -295,7 +468,7 @@ export async function maybeStartNgrokTunnel(
   const version = getNgrokVersion();
   if (!version) return null;
 
-  const savedDomain = loadNgrokDomain(workspaceDir) ?? undefined;
+  const savedDomain = loadNgrokDomain() ?? undefined;
 
   // Reuse an existing tunnel if one is already running
   const runningTunnels = (await queryNgrokTunnels()) ?? [];
@@ -312,6 +485,10 @@ export async function maybeStartNgrokTunnel(
     }
     console.log(`   Found existing ngrok tunnel: ${existingUrl}`);
     saveIngressUrl(workspaceDir, existingUrl, assistantId, "ngrok");
+    await notifyGatewayOfPublicUrl(existingUrl, assistantId);
+    // The adopted tunnel belongs to some other agent we do not own a pid for,
+    // so any recorded tunnel process entry would be stale from here on.
+    clearRootProcess("tunnel");
     return null;
   }
   if (runningTunnels.length > 0) {
@@ -339,6 +516,15 @@ export async function maybeStartNgrokTunnel(
   try {
     const publicUrl = await waitForNgrokUrl(targetPort, savedDomain);
     saveIngressUrl(workspaceDir, publicUrl, assistantId, "ngrok");
+    await notifyGatewayOfPublicUrl(publicUrl, assistantId);
+    if (ngrokProcess.pid) {
+      stampRootProcess("tunnel", {
+        pid: ngrokProcess.pid,
+        provider: "ngrok",
+        startedAt: new Date().toISOString(),
+        assistantId,
+      });
+    }
     console.log(`   Tunnel established: ${publicUrl}`);
 
     return ngrokProcess;
@@ -350,6 +536,7 @@ export async function maybeStartNgrokTunnel(
       console.warn(`   ⚠ ${savedDomainRecoveryHint(savedDomain)}`);
     }
     if (!ngrokProcess.killed) ngrokProcess.kill("SIGTERM");
+    clearRootProcess("tunnel");
     return null;
   }
 }
@@ -370,23 +557,33 @@ export interface RunNgrokTunnelOptions {
 
 /**
  * Run the ngrok tunnel workflow: check installation, find or start a tunnel,
- * save the public URL to config, and block until exit or signal.
+ * and save the public URL to config. Hands the URL back so the tunnel level
+ * can notify the gateway of it; `waitForExit` settles when the run ends
+ * (process exit, signal, or detach).
  */
 export async function runNgrokTunnel(
   opts: RunNgrokTunnelOptions = {},
-): Promise<void> {
-  const version = getNgrokVersion();
+): Promise<ProviderTunnelResult> {
+  const version = await ensureBinaryInstalled({
+    binary: "ngrok",
+    purpose: "the ngrok tunnel",
+    packages: {
+      brew: ["brew", "install", "ngrok/ngrok/ngrok"],
+      snap: ["sudo", "snap", "install", "ngrok"],
+      choco: ["choco", "install", "-y", "ngrok"],
+      winget: [
+        "winget",
+        "install",
+        "--silent",
+        "--accept-package-agreements",
+        "--accept-source-agreements",
+        "ngrok.ngrok",
+      ],
+    },
+    manualHint: "See https://ngrok.com/download for how to install",
+    probe: getNgrokVersion,
+  });
   if (!version) {
-    console.error("Error: ngrok is not installed.");
-    console.error("");
-    console.error("Install ngrok:");
-    console.error("  macOS:  brew install ngrok/ngrok/ngrok");
-    console.error("  Linux:  sudo snap install ngrok");
-    console.error("");
-    console.error("Then authenticate: ngrok config add-authtoken <your-token>");
-    console.error(
-      "  Get your token at: https://dashboard.ngrok.com/get-started/your-authtoken",
-    );
     process.exit(1);
   }
 
@@ -397,7 +594,7 @@ export async function runNgrokTunnel(
 
   // The saved domain is standing intent: a run without --domain reuses it,
   // and only an explicit --domain rewrites it.
-  const domain = opts.domain ?? loadNgrokDomain(workspaceDir) ?? undefined;
+  const domain = opts.domain ?? loadNgrokDomain() ?? undefined;
   if (domain && !opts.domain) {
     console.log(`Using saved ngrok domain: ${domain}`);
   }
@@ -426,8 +623,10 @@ export async function runNgrokTunnel(
     }
     console.log(`Found existing ngrok tunnel: ${existingUrl}`);
     saveIngressUrl(workspaceDir, existingUrl, opts.assistantId, "ngrok");
+    // Not our child process: a recorded entry would be stale or foreign.
+    clearRootProcess("tunnel");
     if (opts.domain) {
-      saveNgrokDomain(workspaceDir, opts.domain);
+      saveNgrokDomain(opts.domain);
     }
     console.log("Ingress URL saved to config.");
     console.log("");
@@ -436,23 +635,26 @@ export async function runNgrokTunnel(
     );
 
     // Block until SIGINT/SIGTERM
-    await new Promise<void>((resolve) => {
+    const waitForExit = new Promise<void>((resolve) => {
       process.on("SIGINT", () => resolve());
       process.on("SIGTERM", () => resolve());
     });
-    return;
+    return { publicUrl: existingUrl, waitForExit };
   }
 
   console.log(`Starting ngrok tunnel to localhost:${port}...`);
 
   let publicUrl: string | undefined;
-
-  const ngrokProcess = startNgrokProcess(port, undefined, domain);
+  // Points at the live agent across auth retries; signals and cleanup act on
+  // whichever attempt is current.
+  let currentNgrok: ChildProcess | null = null;
+  let authAttempts = 0;
 
   const cleanup = () => {
-    if (!ngrokProcess.killed) {
-      ngrokProcess.kill("SIGTERM");
+    if (currentNgrok && !currentNgrok.killed) {
+      currentNgrok.kill("SIGTERM");
     }
+    clearRootProcess("tunnel");
     if (publicUrl) {
       console.log("\nClearing ingress URL from config...");
       clearIngressUrl(workspaceDir, opts.assistantId);
@@ -468,57 +670,116 @@ export async function runNgrokTunnel(
     process.exit(0);
   });
 
-  ngrokProcess.on("error", (err: Error) => {
-    console.error(`ngrok process error: ${err.message}`);
-    process.exit(1);
-  });
+  while (publicUrl === undefined) {
+    const ngrokProcess = startNgrokProcess(port, undefined, domain);
+    currentNgrok = ngrokProcess;
 
-  ngrokProcess.on("exit", (code: number | null) => {
-    if (code !== null && code !== 0) {
-      console.error(`ngrok exited with code ${code}.`);
-      console.error(
-        "Check that ngrok is authenticated: ngrok config add-authtoken <token>",
-      );
+    // Captured per attempt so an authentication failure can be told apart
+    // from other startup failures and recovered with a pasted-in token.
+    const ngrokOutput: string[] = [];
+
+    ngrokProcess.on("error", (err: Error) => {
+      console.error(`ngrok process error: ${err.message}`);
       process.exit(1);
-    }
-  });
+    });
 
-  // Pipe ngrok stdout/stderr to console for visibility
-  ngrokProcess.stdout?.on("data", (data: Buffer) => {
-    const line = data.toString().trim();
-    if (line) console.log(`[ngrok] ${line}`);
-  });
-  ngrokProcess.stderr?.on("data", (data: Buffer) => {
-    const line = data.toString().trim();
-    if (line) console.error(`[ngrok] ${line}`);
-  });
+    // Pipe ngrok stdout/stderr to console for visibility
+    ngrokProcess.stdout?.on("data", (data: Buffer) => {
+      const line = data.toString().trim();
+      if (line) {
+        ngrokOutput.push(line);
+        console.log(`[ngrok] ${line}`);
+      }
+    });
+    ngrokProcess.stderr?.on("data", (data: Buffer) => {
+      const line = data.toString().trim();
+      if (line) {
+        ngrokOutput.push(line);
+        console.error(`[ngrok] ${line}`);
+      }
+    });
 
-  try {
-    publicUrl = await waitForNgrokUrl(port, domain);
-  } catch (err) {
-    cleanup();
-    if (domain && !opts.domain) {
-      console.error(savedDomainRecoveryHint(domain));
+    // An agent that exits during startup rejects this instead of leaving
+    // waitForNgrokUrl to poll a dead API for its full timeout.
+    const exitFailure = new Promise<never>((_, reject) => {
+      ngrokProcess.on("exit", (code: number | null) => {
+        if (code !== null && code !== 0) {
+          reject(new NgrokStartupError(code, ngrokOutput.join("\n")));
+        }
+      });
+    });
+
+    let url: string;
+    try {
+      url = await Promise.race([waitForNgrokUrl(port, domain), exitFailure]);
+    } catch (err) {
+      if (err instanceof NgrokStartupError && isNgrokAuthError(err.output)) {
+        if (authAttempts >= MAX_AUTH_RETRIES) {
+          console.error("\nngrok still rejects the tunnel as unauthenticated.");
+          console.error(
+            "Authenticate manually: ngrok config add-authtoken <your-token>",
+          );
+          console.error(
+            "  Get your token at: https://dashboard.ngrok.com/get-started/your-authtoken",
+          );
+          process.exit(1);
+        }
+        console.log("");
+        console.log("⚠ ngrok rejected the tunnel: it isn't authenticated.");
+        console.log(
+          "  Get your authtoken at: https://dashboard.ngrok.com/get-started/your-authtoken",
+        );
+        const token = (
+          await readLineText(
+            "Paste your ngrok authtoken to continue (Enter to cancel): ",
+          )
+        ).trim();
+        if (!token) {
+          console.log("No authtoken entered.");
+          process.exit(1);
+        }
+        authAttempts++;
+        if (saveNgrokAuthToken(token)) {
+          console.log("✅ ngrok authtoken saved. Retrying the tunnel...");
+        }
+        continue;
+      }
+      cleanup();
+      if (domain && !opts.domain) {
+        console.error(savedDomainRecoveryHint(domain));
+      }
+      throw err;
     }
-    throw err;
-  }
+    publicUrl = url;
 
-  console.log("");
-  console.log(`Tunnel established: ${publicUrl}`);
-  console.log(`Forwarding to:     localhost:${port}`);
+    console.log("");
+    console.log(`Tunnel established: ${publicUrl}`);
+    console.log(`Forwarding to:     localhost:${port}`);
+
+    // The domain is standing intent, not tunnel state: cleanup clears the
+    // ingress URL but leaves the domain saved for wake/daemon restores.
+    saveIngressUrl(workspaceDir, publicUrl, opts.assistantId, "ngrok");
+    if (ngrokProcess.pid) {
+      stampRootProcess("tunnel", {
+        pid: ngrokProcess.pid,
+        provider: "ngrok",
+        startedAt: new Date().toISOString(),
+        assistantId: opts.assistantId,
+      });
+    }
+    if (opts.domain) {
+      saveNgrokDomain(opts.domain);
+    }
+    console.log("Ingress URL saved to config.");
+    console.log("");
+    console.log("Press Ctrl+C to stop the tunnel and clear the ingress URL.");
 
-  // The domain is standing intent, not tunnel state: cleanup clears the
-  // ingress URL but leaves the domain saved for wake/daemon restores.
-  saveIngressUrl(workspaceDir, publicUrl, opts.assistantId, "ngrok");
-  if (opts.domain) {
-    saveNgrokDomain(workspaceDir, opts.domain);
+    // Keep running until the ngrok process exits or we receive a signal
+    const waitForExit = new Promise<void>((resolve) => {
+      ngrokProcess.on("exit", () => resolve());
+    });
+    return { publicUrl, waitForExit };
   }
-  console.log("Ingress URL saved to config.");
-  console.log("");
-  console.log("Press Ctrl+C to stop the tunnel and clear the ingress URL.");
-
-  // Keep running until the ngrok process exits or we receive a signal
-  await new Promise<void>((resolve) => {
-    ngrokProcess.on("exit", () => resolve());
-  });
+  // Unreachable: the loop only exits via return, process.exit, or a throw.
+  throw new Error("ngrok tunnel did not start.");
 }