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

package/src/lib/terminal-client.ts

@@ -2,12 +2,12 @@
  * Platform terminal API client.
  *
  * Wraps the Django terminal session endpoints that proxy through vembda to
- * open K8s exec streams into managed assistant containers. Same transport
+ * open K8s exec streams into cloud assistant containers. Same transport
  * the web UI's xterm.js terminal uses.
  */
 
 import { loopbackSafeFetch } from "./loopback-fetch.js";
-import { authHeaders, getPlatformUrl } from "./platform-client.js";
+import { authHeaders, getCloudUrl } from "./cloud-client.js";
 import { z } from "zod";
 
 const TerminalSessionResponseSchema = z.object({ session_id: z.string() });
@@ -29,10 +29,10 @@ export async function createTerminalSession(
   assistantId: string,
   cols: number,
   rows: number,
-  platformUrl?: string,
+  cloudUrl?: string,
   service?: string,
 ): Promise<{ session_id: string }> {
-  const baseUrl = platformUrl || getPlatformUrl();
+  const baseUrl = cloudUrl || getCloudUrl();
   const body: Record<string, unknown> = { cols, rows };
   if (service) {
     body.service = service;
@@ -41,7 +41,7 @@ export async function createTerminalSession(
     `${baseUrl}/v1/assistants/${assistantId}/terminal/sessions/`,
     {
       method: "POST",
-      headers: await authHeaders(token, platformUrl),
+      headers: await authHeaders(token, cloudUrl),
       body: JSON.stringify(body),
     },
   );
@@ -62,14 +62,14 @@ export async function closeTerminalSession(
   token: string,
   assistantId: string,
   sessionId: string,
-  platformUrl?: string,
+  cloudUrl?: string,
 ): Promise<void> {
-  const baseUrl = platformUrl || getPlatformUrl();
+  const baseUrl = cloudUrl || getCloudUrl();
   const response = await loopbackSafeFetch(
     `${baseUrl}/v1/assistants/${assistantId}/terminal/sessions/${sessionId}/`,
     {
       method: "DELETE",
-      headers: await authHeaders(token, platformUrl),
+      headers: await authHeaders(token, cloudUrl),
     },
   );
   // 404 = already closed, treat as success
@@ -89,14 +89,14 @@ export async function sendTerminalInput(
   assistantId: string,
   sessionId: string,
   data: string,
-  platformUrl?: string,
+  cloudUrl?: string,
 ): Promise<void> {
-  const baseUrl = platformUrl || getPlatformUrl();
+  const baseUrl = cloudUrl || getCloudUrl();
   const response = await loopbackSafeFetch(
     `${baseUrl}/v1/assistants/${assistantId}/terminal/sessions/${sessionId}/input/`,
     {
       method: "POST",
-      headers: await authHeaders(token, platformUrl),
+      headers: await authHeaders(token, cloudUrl),
       body: JSON.stringify({ data }),
     },
   );
@@ -113,14 +113,14 @@ export async function resizeTerminalSession(
   sessionId: string,
   cols: number,
   rows: number,
-  platformUrl?: string,
+  cloudUrl?: string,
 ): Promise<void> {
-  const baseUrl = platformUrl || getPlatformUrl();
+  const baseUrl = cloudUrl || getCloudUrl();
   const response = await loopbackSafeFetch(
     `${baseUrl}/v1/assistants/${assistantId}/terminal/sessions/${sessionId}/resize/`,
     {
       method: "POST",
-      headers: await authHeaders(token, platformUrl),
+      headers: await authHeaders(token, cloudUrl),
       body: JSON.stringify({ cols, rows }),
     },
   );
@@ -143,14 +143,14 @@ export async function* subscribeTerminalEvents(
   token: string,
   assistantId: string,
   sessionId: string,
-  platformUrl?: string,
+  cloudUrl?: string,
   signal?: AbortSignal,
 ): AsyncGenerator<TerminalOutputEvent> {
-  const baseUrl = platformUrl || getPlatformUrl();
+  const baseUrl = cloudUrl || getCloudUrl();
   const response = await loopbackSafeFetch(
     `${baseUrl}/v1/assistants/${assistantId}/terminal/sessions/${sessionId}/events/`,
     {
-      headers: await authHeaders(token, platformUrl),
+      headers: await authHeaders(token, cloudUrl),
       signal,
     },
   );

package/src/lib/terminal-session.ts

@@ -1,14 +1,14 @@
 /**
  * Shared terminal session primitives for managed (cloud-hosted) assistants.
  *
- * Extracted from commands/terminal.ts so that ssh.ts, exec.ts, and
- * terminal.ts can all use the same interactive session and assistant
- * resolver without cross-importing commands (per cli/CONTRIBUTING.md).
+ * Extracted from commands/terminal.ts so that exec.ts and terminal.ts can
+ * use the same interactive session and assistant resolver without
+ * cross-importing commands (per cli/CONTRIBUTING.md).
  */
 
-import { isManagedCloud } from "./managed-cloud.js";
+import { isCloudHome } from "./cloud-values.js";
 import { resolveAssistant } from "./assistant-config.js";
-import { getPlatformUrl, readPlatformToken } from "./platform-client.js";
+import { getCloudUrl, readCloudToken } from "./cloud-client.js";
 import {
   closeTerminalSession,
   createTerminalSession,
@@ -24,7 +24,7 @@ import {
 export interface ResolvedManagedAssistant {
   assistantId: string;
   token: string;
-  platformUrl: string;
+  cloudUrl: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -32,7 +32,7 @@ export interface ResolvedManagedAssistant {
 // ---------------------------------------------------------------------------
 
 /**
- * Resolve a managed (cloud-hosted) assistant from the lockfile. Exits with
+ * Resolve a cloud (cloud-hosted) assistant from the lockfile. Exits with
  * an error if the assistant is not found, not managed, or the user isn't
  * logged in.
  */
@@ -51,14 +51,14 @@ export function resolveManagedAssistant(
   }
 
   const cloud = entry.cloud;
-  if (!isManagedCloud(cloud)) {
+  if (!isCloudHome(cloud)) {
     if (cloud === "local") {
       console.error(
         "This assistant runs locally on your machine. You can access it directly.",
       );
     } else if (cloud === "docker") {
       console.error(
-        `Use 'cadet exec -it -- /bin/bash' or 'cadet ssh' for ${cloud} instances.`,
+        `Use 'cadet exec -it -- /bin/bash' or 'cadet terminal' for ${cloud} instances.`,
       );
     } else {
       console.error(
@@ -68,7 +68,7 @@ export function resolveManagedAssistant(
     process.exit(1);
   }
 
-  const token = readPlatformToken();
+  const token = readCloudToken();
   if (!token) {
     console.error(
       "Not logged in. Run `cadet login` first to authenticate with Cadet Cloud.",
@@ -79,7 +79,7 @@ export function resolveManagedAssistant(
   return {
     assistantId: entry.assistantId,
     token,
-    platformUrl: getPlatformUrl(),
+    cloudUrl: getCloudUrl(),
   };
 }
 
@@ -88,8 +88,8 @@ export function resolveManagedAssistant(
 // ---------------------------------------------------------------------------
 
 /**
- * Open an interactive raw-tty terminal session to a managed assistant.
- * Bridges local stdin/stdout to the platform terminal session API.
+ * Open an interactive raw-tty terminal session to a cloud assistant.
+ * Bridges local stdin/stdout to the cloud terminal session API.
  */
 export async function interactiveSession(
   assistant: ResolvedManagedAssistant,
@@ -106,7 +106,7 @@ export async function interactiveSession(
     assistant.assistantId,
     cols,
     rows,
-    assistant.platformUrl,
+    assistant.cloudUrl,
     service,
   );
 
@@ -142,7 +142,7 @@ export async function interactiveSession(
         assistant.token,
         assistant.assistantId,
         sessionId,
-        assistant.platformUrl,
+        assistant.cloudUrl,
       );
     } catch {
       // Best-effort cleanup
@@ -169,7 +169,7 @@ export async function interactiveSession(
       sessionId,
       newCols,
       newRows,
-      assistant.platformUrl,
+      assistant.cloudUrl,
     ).catch(() => {
       // Resize failures are non-fatal
     });
@@ -190,7 +190,7 @@ export async function interactiveSession(
       assistant.assistantId,
       sessionId,
       data,
-      assistant.platformUrl,
+      assistant.cloudUrl,
     ).catch((err) => {
       if (!exiting) {
         console.error(`\r\nInput error: ${err.message}\r\n`);
@@ -214,7 +214,7 @@ export async function interactiveSession(
       assistant.assistantId,
       sessionId,
       initialCommand + "\r",
-      assistant.platformUrl,
+      assistant.cloudUrl,
     );
   }
 
@@ -224,7 +224,7 @@ export async function interactiveSession(
       assistant.token,
       assistant.assistantId,
       sessionId,
-      assistant.platformUrl,
+      assistant.cloudUrl,
       abortController.signal,
     )) {
       if (exiting) break;
@@ -271,7 +271,7 @@ export function shellEscapeArgs(args: string[]): string {
 // ---------------------------------------------------------------------------
 
 /**
- * Run a command non-interactively in a managed assistant service. Creates
+ * Run a command non-interactively in a cloud assistant service. Creates
  * an ephemeral terminal session, sends the command wrapped in sentinels for
  * reliable output extraction, captures the result, and exits with the
  * remote command's exit code.
@@ -300,7 +300,7 @@ export async function nonInteractiveExec(
     assistant.assistantId,
     120,
     24,
-    assistant.platformUrl,
+    assistant.cloudUrl,
     options?.service,
   );
 
@@ -333,7 +333,7 @@ export async function nonInteractiveExec(
       assistant.token,
       assistant.assistantId,
       sessionId,
-      assistant.platformUrl,
+      assistant.cloudUrl,
       abortController.signal,
     )) {
       eventCount++;
@@ -369,7 +369,7 @@ export async function nonInteractiveExec(
             assistant.assistantId,
             sessionId,
             fullCmd,
-            assistant.platformUrl,
+            assistant.cloudUrl,
           );
         }
       }
@@ -403,7 +403,7 @@ export async function nonInteractiveExec(
       assistant.token,
       assistant.assistantId,
       sessionId,
-      assistant.platformUrl,
+      assistant.cloudUrl,
     ).catch(() => {});
   }
 

package/src/lib/{tunnel-edge.ts → tunnel.ts}

@@ -1,11 +1,10 @@
-import type { ChildProcess } from "child_process";
-
-import { selectRestartTunnelRecord } from "@mycadet/service-contracts/ingress";
-
 import {
+  clearRootProcess,
   loadAllAssistants,
   loadAllAssistantsAcrossEnvs,
+  readRootProcesses,
   type AssistantEntry,
+  type RootProcessRecord,
 } from "./assistant-config.js";
 
 import {
@@ -14,7 +13,6 @@ import {
   loadRawConfig,
   parseGatewayPortFromEntryUrls,
 } from "./ingress-config.js";
-import { IngressConfigSchema } from "./ngrok.js";
 import {
   ensureTunnelEdge,
   formatEdgeMode,
@@ -23,8 +21,187 @@ import {
   type TunnelEdge,
 } from "./nginx-ingress.js";
 import { waitForDaemonReady } from "./http-client.js";
-import { hasWebhookIntegrations, maybeStartNgrokTunnel } from "./ngrok.js";
+import {
+  hasWebhookIntegrations,
+  IngressConfigSchema,
+  isNgrokProcess,
+  maybeStartNgrokTunnel,
+  NGROK_TUNNEL_META,
+  runNgrokTunnel,
+  saveNgrokDomain,
+} from "./tunnels/ngrok.js";
+import { stopProcess } from "./process.js";
 import { shellArg } from "./shell-arg.js";
+import { notifyGatewayOfPublicUrl } from "./tunnels/gateway-notify.js";
+import {
+  selectRestartTunnelRecord,
+  type TunnelProviderName,
+} from "@mycadet/service-contracts/ingress";
+import { runCadetTunnel, CADET_TUNNEL_META } from "./tunnels/cadet.js";
+import {
+  runCloudflareTunnel,
+  CLOUDFLARE_TUNNEL_META,
+} from "./tunnels/cloudflare.js";
+import {
+  runTailscaleTunnel,
+  TAILSCALE_TUNNEL_META,
+} from "./tunnels/tailscale.js";
+
+/**
+ * The provider the automatic tunnel paths start when no provider is named.
+ * ngrok today; the north star has the managed `cadet` tunnel as the eventual
+ * default, at which point only this constant flips.
+ */
+export const DEFAULT_TUNNEL_PROVIDER: TunnelProviderName = "ngrok";
+
+/** Per-provider copy `cadet tunnel`'s help renders. */
+export interface ProviderMeta {
+  /** How far the tunnel URL reaches. */
+  reach: string;
+  /** Install instruction line, rendered under the provider entry. */
+  install: string;
+  /** Extra behavior notes, rendered under the install line. */
+  notes?: string[];
+  /** Example reserved-domain value, for providers that support `--domain`. */
+  domainExample?: string;
+  /** Whether `--domain`/`--clear-domain` can bind a reserved domain. */
+  supportsReservedDomain: boolean;
+  /**
+   * Listed but not yet implemented: the command refuses it before starting
+   * any infrastructure, so `--provider <name>` fails fast with the
+   * coming-soon copy instead of building an edge nothing will use.
+   */
+  comingSoon?: boolean;
+}
+
+/**
+ * The registry: each provider's copy lives in its own `tunnels/<provider>.ts`
+ * module and is assembled here, so `cadet tunnel`'s help, `--provider`
+ * validation, and dispatch all read one shape.
+ */
+export const PROVIDER_META: Record<TunnelProviderName, ProviderMeta> = {
+  cadet: CADET_TUNNEL_META,
+  ngrok: NGROK_TUNNEL_META,
+  cloudflare: CLOUDFLARE_TUNNEL_META,
+  tailscale: TAILSCALE_TUNNEL_META,
+};
+
+/**
+ * Registry check that tolerates any provider spelling: only providers whose
+ * meta claims reserved-domain support accept `--domain`/`--clear-domain`.
+ */
+export function providerSupportsReservedDomain(provider: string): boolean {
+  for (const [name, meta] of Object.entries(PROVIDER_META)) {
+    if (name === provider) return meta.supportsReservedDomain;
+  }
+  return false;
+}
+
+/** Options every provider tunnel accepts; `runProviderTunnel` maps them. */
+export interface ProviderTunnelOptions {
+  port: number;
+  assistantId?: string;
+  workspaceDir: string;
+  /** Reserved domain to bind (providers that support one only). */
+  domain?: string;
+  /** Tailnet-only runs keep the webhook callback base as it is. */
+  preserveIngressUrl?: boolean;
+}
+
+/**
+ * What every tunnel provider's run hands back: the public URL it established
+ * or adopted, and the promise that settles when the run ends. Conformance is
+ * the point — the tunnel level can notify the gateway the same way no matter
+ * which provider ran.
+ */
+export interface ProviderTunnelResult {
+  publicUrl: string;
+  waitForExit: Promise<void>;
+}
+
+/**
+ * Run a tunnel provider by name — the dispatch `cadet tunnel` uses, so the
+ * command layer never names a provider implementation directly. Notifies the
+ * gateway of the resulting public URL identically for every provider, then
+ * holds until the run ends.
+ */
+export async function runProviderTunnel(
+  provider: TunnelProviderName,
+  opts: ProviderTunnelOptions,
+): Promise<{ publicUrl: string }> {
+  const result = await runProvider(provider, opts);
+  await notifyGatewayOfPublicUrl(result.publicUrl, opts.assistantId);
+  await result.waitForExit;
+  return { publicUrl: result.publicUrl };
+}
+
+/** Map the provider name onto its run — no gateway notification here. */
+function runProvider(
+  provider: TunnelProviderName,
+  opts: ProviderTunnelOptions,
+): Promise<ProviderTunnelResult> {
+  const base = {
+    port: opts.port,
+    assistantId: opts.assistantId,
+    workspaceDir: opts.workspaceDir,
+  };
+  if (provider === "ngrok") {
+    return runNgrokTunnel({
+      ...base,
+      ...(opts.domain ? { domain: opts.domain } : {}),
+    });
+  }
+  if (provider === "cadet") {
+    return runCadetTunnel(opts);
+  }
+  if (provider === "cloudflare") {
+    return runCloudflareTunnel(base);
+  }
+  return runTailscaleTunnel({
+    ...base,
+    ...(opts.preserveIngressUrl
+      ? { preserveIngressUrl: opts.preserveIngressUrl }
+      : {}),
+  });
+}
+
+/** Drop the saved reserved-domain record (providers that keep one). */
+export function clearReservedDomain(): void {
+  saveNgrokDomain(null);
+}
+
+/**
+ * Stop a tunnel agent this CLI started, per the root lockfile's `tunnel`
+ * entry. The pid is verified against the provider's process identity before
+ * signaling — a stale entry after PID reuse must not kill an unrelated
+ * process.
+ */
+export async function stopTunnelProcess(): Promise<void> {
+  const recorded: RootProcessRecord | undefined = readRootProcesses().tunnel;
+  if (!recorded) return;
+  if (isNgrokProcess(recorded.pid)) {
+    await stopProcess(recorded.pid, "tunnel");
+  }
+  clearRootProcess("tunnel");
+}
+
+/**
+ * The `cadet tunnel --detach` copy for a run that adopted an already-running
+ * agent: killing the supervisor does not stop a tunnel it did not spawn.
+ */
+export function adoptedTunnelStopNotice(pid: number | undefined): string {
+  return (
+    `That ngrok agent was already running outside this command, so \`kill ${pid}\` only ` +
+    "stops this supervisor, not the ngrok tunnel or its saved ingress URL. Stop the ngrok agent " +
+    "directly to end the tunnel."
+  );
+}
+
+export {
+  ADOPTED_TUNNEL_RE,
+  hasWebhookIntegrationsConfigured,
+} from "./tunnels/ngrok.js";
+export { cadetTunnelComingSoonError } from "./tunnels/cadet.js";
 
 /** Matches the Docker hatch path's service-readiness allowance. */
 export const DOCKER_GATEWAY_READY_TIMEOUT_MS = 5 * 60_000;
@@ -221,8 +398,9 @@ function ownsSharedIngress(
  * survived across sleep (a tailnet serve, a reserved ngrok domain) reaches the
  * gateway again without a manual `cadet tunnel`.
  *
- * No webhook auto-tunnel here. Container wakes have never tracked a spawned
- * ngrok PID, so starting one would leak it past the next sleep.
+ * The auto-tunnel runs here too, matching the local wake path: the spawned
+ * agent records itself in the root lockfile under `tunnel`, so `cadet ps` and
+ * the stop paths can see it instead of it leaking past the next sleep.
  */
 export async function restoreContainerTunnelEdge(
   entry: AssistantEntry,
@@ -257,20 +435,30 @@ export async function restoreContainerTunnelEdge(
     );
     return;
   }
-  await restoreTunnelEdge(entry.assistantId, gatewayPort, workspaceDir, false);
+  await restoreTunnelEdgeAndAutoTunnel(
+    entry.assistantId,
+    gatewayPort,
+    workspaceDir,
+  );
 }
 
+/**
+ * Restore the nginx edge, then start the default provider's tunnel at it
+ * (the gateway port when the edge is down, keeping webhook delivery alive).
+ * The spawned agent records itself in the root lockfile under `tunnel`;
+ * adopting an already-running one clears any stale entry.
+ */
 export async function restoreTunnelEdgeAndAutoTunnel(
   assistantId: string,
   gatewayPort: number,
   workspaceDir: string,
-): Promise<ChildProcess | null> {
+): Promise<void> {
   const edgePort = await restoreTunnelEdge(
     assistantId,
     gatewayPort,
     workspaceDir,
   );
-  return maybeStartNgrokTunnel(
+  await maybeStartNgrokTunnel(
     edgePort ?? gatewayPort,
     workspaceDir,
     assistantId,

package/src/lib/tunnels/cadet.ts

@@ -0,0 +1,29 @@
+import { STALE_CLI_UPDATE_HINT } from "../stale-cli-hint.js";
+import type { ProviderMeta, ProviderTunnelOptions } from "../tunnel.js";
+
+/**
+ * The managed `cadet` tunnel. It is listed in the shared registry so the
+ * command's help and `--provider` validation speak its name, but the tunnel
+ * itself ships with Cadet Cloud — until then every run refuses loudly.
+ */
+export const CADET_TUNNEL_META: ProviderMeta = {
+  reach: "Managed tunnel via Cadet Cloud (coming soon)",
+  install: "no install needed — included with Cadet Cloud",
+  supportsReservedDomain: false,
+  comingSoon: true,
+};
+
+/** Copy every refusing path shares, so the wording cannot drift apart. */
+export function cadetTunnelComingSoonError(provider: string): Error {
+  return new Error(
+    `Tunnel provider '${provider}' is not yet implemented. ` +
+      `If this provider is documented, ${STALE_CLI_UPDATE_HINT}`,
+  );
+}
+
+/** Refuse the run: the managed tunnel is not something the CLI can start. */
+export async function runCadetTunnel(
+  _opts: ProviderTunnelOptions,
+): Promise<never> {
+  throw cadetTunnelComingSoonError("cadet");
+}

package/src/lib/{cloudflare-tunnel.ts → tunnels/cloudflare.ts}

@@ -1,11 +1,15 @@
+import type { ProviderMeta, ProviderTunnelResult } from "../tunnel.js";
+
 import { execFileSync, spawn, type ChildProcess } from "node:child_process";
 
-import { GATEWAY_PORT } from "./constants.js";
+import { ensureBinaryInstalled } from "../ensure-binary.js";
+
+import { GATEWAY_PORT } from "../constants.js";
 import {
   clearIngressUrl,
   getDefaultWorkspaceDir,
   saveIngressUrl,
-} from "./ingress-config.js";
+} from "../ingress-config.js";
 
 // ── Cloudflare Tunnel ─────────────────────────────────────────────────────────
 
@@ -135,19 +139,27 @@ export interface RunCloudflareTunnelOptions {
 
 export async function runCloudflareTunnel(
   opts: RunCloudflareTunnelOptions = {},
-): Promise<void> {
-  const version = getCloudflareTunnelVersion();
+): Promise<ProviderTunnelResult> {
+  const version = await ensureBinaryInstalled({
+    binary: "cloudflared",
+    purpose: "the cloudflare tunnel",
+    packages: {
+      brew: ["brew", "install", "cloudflare/cloudflare/cloudflared"],
+      winget: [
+        "winget",
+        "install",
+        "--silent",
+        "--accept-package-agreements",
+        "--accept-source-agreements",
+        "Cloudflare.cloudflared",
+      ],
+      choco: ["choco", "install", "-y", "cloudflared"],
+    },
+    manualHint:
+      "See https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/ for how to install",
+    probe: getCloudflareTunnelVersion,
+  });
   if (!version) {
-    console.error("Error: cloudflared is not installed.");
-    console.error("");
-    console.error("Install cloudflared:");
-    console.error("  macOS:   brew install cloudflare/cloudflare/cloudflared");
-    console.error("  Linux:   https://pkg.cloudflare.com/index.html");
-    console.error(
-      "  Windows: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/",
-    );
-    console.error("");
-    console.error("No Cloudflare account is required for quick tunnels.");
     process.exit(1);
   }
 
@@ -226,7 +238,16 @@ export async function runCloudflareTunnel(
   console.log("Press Ctrl+C to stop the tunnel and clear the ingress URL.");
 
   // Keep running until cloudflared exits (e.g., network error or user Ctrl+C)
-  await new Promise<void>((resolve) => {
+  const waitForExit = new Promise<void>((resolve) => {
     child.on("exit", () => resolve());
   });
+  return { publicUrl, waitForExit };
 }
+
+/** Per-provider copy `cadet tunnel`'s help renders for cloudflare. */
+export const CLOUDFLARE_TUNNEL_META: ProviderMeta = {
+  reach: "Public tunnel that webhook integrations can reach",
+  install: "install: brew install cloudflare/cloudflare/cloudflared",
+  notes: ["No Cloudflare account required for quick tunnels."],
+  supportsReservedDomain: false,
+};