@mycadet/cli 0.12.7-dev.202610111049.d2b52a8 → 0.12.8

package/src/lib/nginx-ingress.ts

@@ -19,8 +19,10 @@ import { join } from "node:path";
 import { cloudAssistantHubUrl } from "@mycadet/environments";
 
 import {
+  clearRootProcess,
   getAssistantDisplayName,
   lookupAssistantByIdentifier,
+  stampRootProcess,
   type AssistantEntry,
 } from "./assistant-config.js";
 import type { RemoteHost } from "./constants.js";
@@ -360,7 +362,7 @@ http {
   # remote client cannot smuggle one. Every caller reaches this loopback-only
   # listener through the TLS-terminating front (tunnel agent), so the raw peer
   # is always 127.0.0.1; the front records the real client as the RIGHTMOST
-  # X-Forwarded-For entry (ngrok/cloudflared append, tailscale serve sets it),
+  # X-Forwarded-For entry (tunnel providers append one; tailscale serve sets it),
   # which the remote client cannot control. Fall back to the raw peer when the
   # front sets no X-Forwarded-For.
   map $http_x_forwarded_for $cadet_edge_client_ip {
@@ -494,7 +496,8 @@ export function getNginxVersion(): string | null {
  * process.ts helpers: stopProcessByPidFile's isCadetProcess() guard only
  * matches command lines containing a cadet path, which fails for a custom
  * CADET_WORKSPACE_DIR and would silently leave nginx running (the same
- * reason local.ts kills ngrok directly). This module is also imported by
+ * reason local.ts stops the tunnel agent directly). This module is also
+ * imported by
  * sleep/retire, whose tests mock.module() process.js process-globally —
  * depending on it here would couple this lib's behavior to those mocks.
  */
@@ -625,13 +628,15 @@ function clearIngressState(workspaceDir: string): void {
 function clearStoppedIngress(workspaceDir: string, pidPath: string): void {
   clearIngressState(workspaceDir);
   rmSync(pidPath, { force: true });
+  // The edge is gone; drop the root lockfile's process entry with it.
+  clearRootProcess("app");
 }
 
 /**
- * Write the nginx config and spawn nginx detached (same idiom as the ngrok
- * spawn in ngrok.ts: stdout/stderr to a log file, fd closed after spawn,
- * caller unrefs). nginx runs with `daemon off` so the spawned process is the
- * master; it writes its pid to nginx.pid under the prefix dir.
+ * Write the nginx config and spawn nginx detached (stdout/stderr to a log
+ * file, fd closed after spawn, caller unrefs). nginx runs with `daemon off`
+ * so the spawned process is the master; it writes its pid to nginx.pid under
+ * the prefix dir.
  */
 export function startIngressNginx(opts: {
   workspaceDir: string;
@@ -1035,8 +1040,22 @@ export async function stopContainerTunnelEdge(
   return stopIngressNginx(workspaceDir);
 }
 
-/** Resolved edge a tunnel (or bring-your-own HTTPS front) should target. */
-export interface TunnelEdge {
+/** Record the running edge's pid in the root lockfile for `cadet ps`. */
+function stampAppProcessEntry(
+  workspaceDir: string,
+  assistantId?: string,
+): void {
+  const pid = getIngressPid(workspaceDir);
+  if (pid !== null) {
+    stampRootProcess("app", {
+      pid,
+      startedAt: new Date().toISOString(),
+      assistantId,
+    });
+  }
+}
+
+/** Resolved edge a tunnel (or bring-your-own HTTPS front) should target. */ export interface TunnelEdge {
   /** Loopback listen port the HTTPS front should forward to. */
   port: number;
   /** True when this call started the edge, false when a running one was reused. */
@@ -1099,6 +1118,7 @@ export async function ensureTunnelEdge(opts: {
 
   switch (result.status) {
     case "started":
+      stampAppProcessEntry(opts.workspaceDir, opts.assistantId);
       return {
         port: result.listenPort,
         started: true,
@@ -1132,6 +1152,7 @@ export async function ensureTunnelEdge(opts: {
             stuckEdgeRecoveryHint(opts.workspaceDir),
         );
       }
+      stampAppProcessEntry(opts.workspaceDir, opts.assistantId);
       return {
         port: result.listenPort,
         started: false,

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.`,
+    );
+  }
+}