@mycadet/cli 0.12.7 → 0.12.8

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,13 @@
+import type { ProviderMeta, ProviderTunnelResult } from "../tunnel.js";
+
 import { execFileSync, spawn, type ChildProcess } from "node:child_process";
 
-import { GATEWAY_PORT } from "./constants.js";
+import { GATEWAY_PORT } from "../constants.js";
 import {
   clearIngressUrl,
   getDefaultWorkspaceDir,
   saveIngressUrl,
-} from "./ingress-config.js";
+} from "../ingress-config.js";
 
 // ── Cloudflare Tunnel ─────────────────────────────────────────────────────────
 
@@ -135,7 +137,7 @@ export interface RunCloudflareTunnelOptions {
 
 export async function runCloudflareTunnel(
   opts: RunCloudflareTunnelOptions = {},
-): Promise<void> {
+): Promise<ProviderTunnelResult> {
   const version = getCloudflareTunnelVersion();
   if (!version) {
     console.error("Error: cloudflared is not installed.");
@@ -226,7 +228,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,
+};

package/src/lib/tunnels/gateway-notify.ts

@@ -0,0 +1,61 @@
+/**
+ * Tunnel-level gateway notification: once ANY tunnel provider has a public
+ * URL, the gateway learns it here — ngrok-agnostic on purpose, so every
+ * provider conforms by returning its `publicUrl` and the dispatch (`cadet
+ * tunnel`'s tunnel level, or the daemon's auto-tunnel) calls this.
+ */
+
+import { lookupAssistantByIdentifier } from "../assistant-config.js";
+import { GATEWAY_PORT } from "../constants.js";
+import { loadGuardianToken } from "../guardian-token.js";
+import { loopbackSafeFetch } from "../loopback-fetch.js";
+
+/**
+ * Where the gateway for this run's assistant answers. The entry's recorded
+ * loopback URL when one resolves; the global gateway port otherwise.
+ */
+function gatewayUrlFor(assistantId: string | undefined): string {
+  if (assistantId) {
+    const result = lookupAssistantByIdentifier(assistantId);
+    if (result.status === "found") {
+      const url = result.entry.localUrl ?? result.entry.runtimeUrl;
+      if (url) return url;
+    }
+  }
+  return `http://127.0.0.1:${GATEWAY_PORT}`;
+}
+
+/**
+ * Tell the gateway the tunnel's public URL so it records the ingress domain
+ * in its own config, the same way its own tunnel machinery does. Best-effort:
+ * a gateway that is down never fails the tunnel that fronts it.
+ */
+export async function notifyGatewayOfPublicUrl(
+  publicUrl: string,
+  assistantId: string | undefined,
+): Promise<void> {
+  try {
+    const token = assistantId
+      ? loadGuardianToken(assistantId)?.accessToken
+      : undefined;
+    const res = await loopbackSafeFetch(
+      `${gatewayUrlFor(assistantId)}/v1/ingress/domains`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...(token ? { Authorization: `Bearer ${token}` } : {}),
+        },
+        body: JSON.stringify({ publicBaseUrl: publicUrl }),
+        signal: AbortSignal.timeout(5_000),
+      },
+    );
+    if (!res.ok) {
+      throw new Error(`gateway responded ${res.status}`);
+    }
+  } catch (err) {
+    console.warn(
+      `   ⚠ Could not record the ingress domain with the gateway: ${err instanceof Error ? err.message : String(err)}. The tunnel still runs.`,
+    );
+  }
+}