@mycadet/cli 0.12.9 → 0.12.11

package/src/commands/pair.ts

@@ -3,9 +3,12 @@
  *
  * Print the pairing link for another device, and the same link rendered as a
  * QR code. Runs on the machine hosting the assistant: it mints a remote-web
- * pairing challenge over the loopback gateway and approves it immediately, so
- * running this command IS the local-presence proof and one scan (or one paste
- * into `cadet connect import`) completes the pairing.
+ * pairing challenge through the gateway CLI (`gateway pairing mint <url>` —
+ * locally, or docker-exec'd into the gateway container) which approves it
+ * immediately, so running this command IS the local-presence proof and one
+ * scan (or one paste into `cadet connect import`) completes the pairing.
+ * local and docker assistants mint without any HTTP; other topologies keep
+ * the loopback HTTP mint.
  *
  * `--web-approve` is the reverse direction: approve a code a device already
  * shows, for pairings that device started on its own.
@@ -38,8 +41,11 @@ import {
 import { GATEWAY_PORT } from "../lib/constants.js";
 import { getCurrentEnvironment } from "../lib/environments/resolve.js";
 import { isLoopbackUrl, loopbackSafeFetch } from "../lib/loopback-fetch.js";
+import { dockerResourceNames } from "../lib/docker.js";
+import { gatewayCliInvocation } from "../lib/local.js";
 import { formatWebApproveFailure, parseGatewayErrorCode } from "../lib/pair.js";
 import { STALE_CLI_UPDATE_HINT } from "../lib/stale-cli-hint.js";
+import { execOutput } from "../lib/step-runner.js";
 
 function assistantDisplayName(entry: AssistantEntry): string {
   return entry.name || entry.assistantName || entry.assistantId;
@@ -89,9 +95,10 @@ function printUsage(): void {
 USAGE:
     cadet pair [assistant] [options]
 
-Mints a pairing challenge on the assistant's gateway over loopback and
-approves it on the spot (running this command on the host machine is the
-approval), then prints the pairing link and the same link as a QR code.
+Mints a pairing challenge on the assistant's gateway (via the gateway CLI
+for local and docker assistants, over loopback HTTP otherwise) and approves
+it on the spot (running this command on the host machine is the approval),
+then prints the pairing link and the same link as a QR code.
 Scanning the QR, opening the link, or passing it to 'cadet connect import'
 on the other device completes the pairing in one step.
 
@@ -214,26 +221,122 @@ async function exitOnHttpError(response: Response): Promise<Response> {
   return response;
 }
 
-/** Create a remote-web pairing challenge (RFC 8628 device-code flow). */
-async function createRemoteWebPairingChallenge(
-  gatewayUrl: string,
+/**
+ * Mint (and approve) a remote-web pairing challenge. `local` and `docker`
+ * remotes mint through the gateway CLI — `gateway pairing mint <url>` run on
+ * the assistant's host (locally, or docker-exec'd into the gateway container)
+ * — replacing the old loopback HTTP mint whose loopback-peer gate
+ * containerized gateways could never satisfy (published-port NAT rewrites
+ * host-originated peers to the docker bridge address). The mint executes the
+ * pairing logic directly against the file-backed challenge store, so the
+ * running gateway's verification routes see it with no IPC round-trip.
+ * Process execution is the local-presence proof; the mint command approves
+ * on the spot, so the returned challenge is already paired-ready. Other
+ * topologies keep the loopback HTTP mint they used before.
+ */
+async function mintPairingChallengeOrExit(
+  entry: AssistantEntry,
   publicBaseUrl: string,
 ): Promise<RemoteWebPairingChallengeResponse> {
+  if (entry.cloud !== "local" && entry.cloud !== "docker") {
+    return mintPairingChallengeOverLoopbackOrExit(entry, publicBaseUrl);
+  }
+
+  let stdout: string;
+  try {
+    if (entry.cloud === "docker") {
+      stdout = await execOutput(
+        "docker",
+        [
+          "exec",
+          dockerResourceNames(entry.assistantId).gatewayContainer,
+          "bun",
+          "run",
+          "src/cli/index.ts",
+          "pairing",
+          "mint",
+          publicBaseUrl,
+        ],
+        { timeoutMs: 30_000 },
+      );
+    } else {
+      const invocation = gatewayCliInvocation(entry.resources);
+      stdout = await execOutput(
+        invocation.command,
+        [...invocation.args, "pairing", "mint", publicBaseUrl],
+        {
+          cwd: invocation.cwd,
+          env: invocation.env,
+          timeoutMs: 30_000,
+        },
+      );
+    }
+  } catch (err) {
+    console.error(
+      `Error: could not mint a pairing challenge on the gateway ` +
+        `(${err instanceof Error ? err.message : String(err)}).`,
+    );
+    console.error("Is the assistant running? Try `cadet wake`.");
+    process.exit(1);
+  }
+
+  const lastLine = stdout.split("\n").filter(Boolean).pop() ?? "";
+  let challenge: RemoteWebPairingChallengeResponse;
+  try {
+    challenge = JSON.parse(lastLine) as RemoteWebPairingChallengeResponse;
+  } catch {
+    console.error(
+      "Error: could not parse the gateway's pairing mint output.",
+    );
+    process.exit(1);
+  }
+  if (!challenge.deviceCode || !challenge.userCode) {
+    console.error(
+      "Error: the gateway's pairing mint output is missing the challenge codes.",
+    );
+    process.exit(1);
+  }
+  return challenge;
+}
+
+/**
+ * Mint a challenge over the gateway's loopback HTTP route — the path every
+ * topology took before the gateway-CLI mint existed. Kept for remotes that
+ * are neither `local` nor `docker` (apple containers, SSH-managed hosts,
+ * cloud-managed), where no gateway-CLI execution surface is defined.
+ */
+async function mintPairingChallengeOverLoopbackOrExit(
+  entry: AssistantEntry,
+  publicBaseUrl: string,
+): Promise<RemoteWebPairingChallengeResponse> {
+  // Mint over loopback (localUrl avoids mDNS for same-machine calls), then
+  // approve immediately: running this CLI on the host IS the local-presence
+  // proof, so the other device completes pairing in one step from the link.
+  const mintUrl = (
+    entry.localUrl ||
+    entry.runtimeUrl ||
+    `http://127.0.0.1:${GATEWAY_PORT}`
+  ).replace(/\/+$/, "");
   const response = await gatewayPostOrExit(
-    gatewayUrl,
+    mintUrl,
     "/v1/remote-web/pairing-challenge",
     { publicBaseUrl } satisfies RemoteWebPairingChallengeRequest,
   );
-  return (await response.json()) as RemoteWebPairingChallengeResponse;
+  const challenge: RemoteWebPairingChallengeResponse =
+    await response.json();
+  await gatewayPostOrExit(mintUrl, "/v1/remote-web/pairing-verification", {
+    userCode: challenge.userCode,
+  } satisfies RemoteWebPairingVerificationRequest);
+  return challenge;
 }
 
 /**
  * Approve a pending pairing challenge by its user code, the local-presence
  * proof for the device-code flow. Single owner of the pairing-verification
- * route and request body: the link flow approves via
- * {@link approveRemoteWebPairing} (generic exit on non-2xx), while
- * `--web-approve` calls this directly to inspect rejections and print mismatch
- * diagnostics (see {@link formatWebApproveFailure}).
+ * route and request body: `--web-approve` calls this directly to inspect
+ * rejections and print mismatch diagnostics (see
+ * {@link formatWebApproveFailure}); the link flow needs no separate
+ * verification call — the gateway-CLI mint approves on the spot.
  */
 async function postPairingVerification(
   gatewayUrl: string,
@@ -244,20 +347,6 @@ async function postPairingVerification(
   } satisfies RemoteWebPairingVerificationRequest);
 }
 
-/**
- * Approve the challenge this command just minted so one scan completes
- * pairing, exiting with a generic message on non-2xx.
- */
-async function approveRemoteWebPairing(
-  gatewayUrl: string,
-  userCode: string,
-): Promise<RemoteWebPairingVerificationResponse> {
-  const response = await exitOnHttpError(
-    await postPairingVerification(gatewayUrl, userCode),
-  );
-  return (await response.json()) as RemoteWebPairingVerificationResponse;
-}
-
 export const pair = Object.assign(
   async function pair(): Promise<void> {
   const rawArgs = process.argv.slice(3);
@@ -355,6 +444,24 @@ export const pair = Object.assign(
     }
   }
 
+  // Minting requires host presence on this machine. Native and docker
+  // topologies qualify (the latter via docker exec); an assistant this
+  // machine only knows through `connect import` has no host presence here
+  // at all, and `cadet pair` never worked against it (its loopback gate
+  // denied remote mints). Refuse clearly instead of a confusing mint
+  // failure.
+  if (entry.cloud === "paired") {
+    console.error(
+      `Error: ${formatAssistantReference(entry)} was paired as a remote ` +
+        "assistant (cadet connect import), so this machine does not host it.",
+    );
+    console.error(
+      "Run `cadet pair` on the machine hosting the assistant, or approve " +
+        "a code it shows with `cadet pair --web-approve <code>`.",
+    );
+    process.exit(1);
+  }
+
   // Mint over loopback (localUrl avoids mDNS for same-machine calls), but
   // advertise a REACHABLE url in the link, since the loopback url would point
   // the other device at its own localhost. Prefer an explicit --url, then the
@@ -437,14 +544,10 @@ export const pair = Object.assign(
   }
   const publicBaseUrl = resolved.url;
 
-  // Mint a challenge and immediately approve it: running this CLI on the host
-  // IS the local-presence proof, so the other device completes pairing in one
-  // step from the link alone.
-  const challenge = await createRemoteWebPairingChallenge(
-    mintUrl,
-    publicBaseUrl,
-  );
-  await approveRemoteWebPairing(mintUrl, challenge.userCode);
+  // Mint a challenge (approved on the spot by the gateway-CLI invocation):
+  // running this CLI on the host IS the local-presence proof, so the other
+  // device completes pairing in one step from the link alone.
+  const challenge = await mintPairingChallengeOrExit(entry, publicBaseUrl);
   const pairUrl = buildRemoteWebPairingUrl(challenge);
   const displayName = assistantDisplayName(entry);
   const appUrl = appVariant
@@ -483,6 +586,10 @@ export const pair = Object.assign(
     console.log(qr);
   });
   console.log("");
+  console.log("Or enter this code on the pairing page:");
+  console.log("");
+  console.log(`  ${challenge.deviceCode}`);
+  console.log("");
   if (appUrl) {
     console.log("The QR opens the Cadet app. App link:");
     console.log("");
@@ -495,7 +602,9 @@ export const pair = Object.assign(
   console.log("");
   console.log(`  ${pairUrl}`);
   console.log("");
-  console.log(`On another computer, run:  cadet connect import "${pairUrl}"`);
+  console.log("Or on another computer, run:");
+  console.log("");
+  console.log(`  cadet connect import "${pairUrl}"`);
   console.log("");
   console.log(`Expires: ${challenge.expiresAt}`);
 },

package/src/commands/ps.ts

@@ -1,3 +1,4 @@
+import { getNginxIngressPort } from "../lib/nginx-ingress.js";
 import { isCloudHome } from "../lib/cloud-values.js";
 import { join } from "path";
 
@@ -649,10 +650,10 @@ async function getRootManagedRows(): Promise<RootManagedRow[]> {
     rows.push({
       assistantId: app.assistantId,
       row: {
-        name: "nginx edge",
+        name: "nginx",
         type: APP_TYPE,
         status: withStatusEmoji(alive ? "running" : "not running"),
-        info: alive ? `PID ${app.pid}` : `PID ${app.pid} (exited)`,
+        info: `port ${app.port ?? getNginxIngressPort()}, PID ${app.pid}${alive ? "" : " (exited)"}`,
       },
     });
   }
@@ -660,35 +661,23 @@ async function getRootManagedRows(): Promise<RootManagedRow[]> {
 }
 
 /**
- * Fold the CLI-managed process rows into ONE table with the assistant rows:
- * a process fronts an assistant when it recorded that assistant's id, and
- * those rows nest under it; anything unattributed (or fronting an assistant
- * this environment no longer lists) renders at the bottom, machine-level.
+ * Fold the CLI-managed process rows into ONE table with the assistant rows.
+ * Tunnel agents and the nginx edge are root resources of the machine, not
+ * children of whichever assistant they front — especially as the web bundle
+ * splits into /app and /ui — so every CLI-managed row renders machine-level.
  */
 async function assistantRowsWithRootProcesses(
   assistants: AssistantEntry[],
   healths: AssistantHealth[],
   activeAssistantId: string | null,
 ): Promise<TableRow[]> {
-  const nestedByAssistant = new Map<string, TableRow[]>();
-  const unattributed: TableRow[] = [];
-  const knownIds = new Set(assistants.map((entry) => entry.assistantId));
-  for (const managed of await getRootManagedRows()) {
-    if (managed.assistantId && knownIds.has(managed.assistantId)) {
-      const nested = nestedByAssistant.get(managed.assistantId) ?? [];
-      nested.push({ ...managed.row, name: `  └ ${managed.row.name}` });
-      nestedByAssistant.set(managed.assistantId, nested);
-    } else {
-      unattributed.push(managed.row);
-    }
-  }
+  const rootRows = (await getRootManagedRows()).map((managed) => managed.row);
 
   const rows: TableRow[] = [];
   assistants.forEach((entry, i) => {
     rows.push(formatAssistantListRow(entry, activeAssistantId, healths[i]!));
-    rows.push(...(nestedByAssistant.get(entry.assistantId) ?? []));
   });
-  rows.push(...unattributed);
+  rows.push(...rootRows);
   return rows;
 }
 
@@ -825,6 +814,7 @@ export async function listAllAssistants(verbose: boolean): Promise<void> {
     ),
     { name: "NAME", type: "TYPE", status: "STATUS", info: "INFO" },
   );
+  console.log("");
 }
 
 // ── Entry point ─────────────────────────────────────────────────

package/src/commands/teleport.ts

@@ -185,7 +185,6 @@ function printHelp(): void {
 
 export function parseArgs(argv: string[]): {
   from: string | undefined;
-  to: string | undefined;
   targetEnv: "local" | "docker" | "platform" | undefined;
   targetName: string | undefined;
   keepSource: boolean;
@@ -193,7 +192,6 @@ export function parseArgs(argv: string[]): {
   help: boolean;
 } {
   let from: string | undefined;
-  let to: string | undefined;
   let targetEnv: "local" | "docker" | "platform" | undefined;
   let targetName: string | undefined;
   let keepSource = false;
@@ -209,11 +207,6 @@ export function parseArgs(argv: string[]): {
         continue;
       }
       from = argv[++i];
-    } else if (arg === "--to" && i + 1 < argv.length) {
-      if (argv[i + 1].startsWith("--")) {
-        continue;
-      }
-      to = argv[++i];
     } else if (
       arg === "--local" ||
       arg === "--docker" ||
@@ -242,7 +235,7 @@ export function parseArgs(argv: string[]): {
     process.exit(1);
   }
 
-  return { from, to, targetEnv, targetName, keepSource, dryRun, help };
+  return { from, targetEnv, targetName, keepSource, dryRun, help };
 }
 
 // ---------------------------------------------------------------------------
@@ -1253,7 +1246,6 @@ async function tryInjectCloudCredentials(
       bearerToken: entry.bearerToken,
       assistantApiKey,
       cloudAssistantId: registration.assistant.id,
-      cloudBaseUrl: cloudUrl,
       organizationId: orgId,
       userId: user.id,
       webhookSecret: registration.webhook_secret,
@@ -1277,7 +1269,7 @@ async function tryInjectCloudCredentials(
 export const teleport = Object.assign(
   async function teleport(): Promise<void> {
   const args = process.argv.slice(3);
-  const { from, to, targetEnv, targetName, keepSource, dryRun, help } =
+  const { from, targetEnv, targetName, keepSource, dryRun, help } =
     parseArgs(args);
 
   if (help) {
@@ -1285,17 +1277,6 @@ export const teleport = Object.assign(
     process.exit(0);
   }
 
-  // Legacy --to flag deprecation
-  if (to) {
-    console.error("Error: --to is deprecated. Use environment flags instead:");
-    console.error(
-      "  cadet teleport --from <source> --local|--docker|--platform [name]",
-    );
-    console.error("");
-    console.error("Run 'cadet teleport --help' for details.");
-    process.exit(1);
-  }
-
   if (!from) {
     printHelp();
     process.exit(1);

package/src/commands/tunnel.ts

@@ -10,6 +10,7 @@ import {
 import {
   formatAssistantReference,
   loadAllAssistants,
+  readRootProcesses,
   resolveTargetAssistant,
   type AssistantEntry,
 } from "../lib/assistant-config";
@@ -37,6 +38,8 @@ import {
   hasWebhookIntegrationsConfigured,
   providerSupportsReservedDomain,
   runProviderTunnel,
+  stopTunnelProcess,
+  summarizeStartupFailure,
 } from "../lib/tunnel.js";
 
 // The accepted `--provider` values ARE the shared registry, so validation
@@ -47,7 +50,7 @@ interface TunnelArgs {
   provider: TunnelProviderName;
   domain: string | null;
   clearDomain: boolean;
-  detach: boolean;
+  foreground: boolean;
 }
 
 const FLAGS_WITH_VALUES = ["--provider", "--domain"] as const;
@@ -57,13 +60,13 @@ function parseArgs(): TunnelArgs {
   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];
     if (arg === "--help" || arg === "-h") {
       console.log(
-        "Usage: cadet tunnel [<name>] --provider <provider> [options]",
+        "Usage: cadet tunnel [<name>] --provider <provider> [options]\n       cadet tunnel stop [<name>]",
       );
       console.log("");
       console.log("Front a locally running assistant with an HTTPS tunnel.");
@@ -112,19 +115,22 @@ function parseArgs(): TunnelArgs {
         "                                tunnel 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`,
+        `  --foreground                  Stream the tunnel's logs to this terminal. By default the tunnel`,
       );
       console.log(
-        "                                initial established/failed status before returning; logs go to",
+        "                                runs in the background: the command returns after printing the public",
       );
       console.log(
-        "                                the CLI log directory. Stop it with `kill <pid>`, except when it",
+        `                                URL, and logs stream to tunnel.log in the CLI log directory. A background`,
       );
       console.log(
-        "                                adopted an already-running tunnel (started outside this",
+        "                                tunnel stops with `cadet tunnel stop`, except when it adopted an already-running",
       );
       console.log(
-        "                                command): killing the supervisor then leaves that tunnel running.",
+        "                                tunnel (started outside this command): killing the supervisor then",
+      );
+      console.log(
+        "                                leaves that tunnel running.",
       );
       console.log("");
       console.log("Providers:");
@@ -151,9 +157,6 @@ function parseArgs(): TunnelArgs {
       }
       console.log("  $ cadet tunnel --provider cloudflare");
       console.log("  $ cadet tunnel my-assistant --provider tailscale");
-      console.log(
-        `  $ cadet tunnel --provider ${DEFAULT_TUNNEL_PROVIDER} --detach`,
-      );
       process.exit(0);
     } else if (arg === "--provider") {
       const next = args[i + 1];
@@ -188,8 +191,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);
@@ -227,7 +230,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. */
@@ -345,31 +348,31 @@ const TUNNEL_BACKGROUND_START_TIMEOUT_MS = 35_000;
 const TUNNEL_ESTABLISHED_RE = /Tunnel established: (\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" or adopted-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 = "";
@@ -394,9 +397,17 @@ async function spawnDetachedTunnel(): Promise<void> {
   });
 
   if (exitCode !== undefined) {
+    let logText = "";
+    try {
+      logText = readFileSync(logPath, "utf-8");
+    } catch {
+      // Log file not readable — the summary falls back to none.
+    }
+    const reason = summarizeStartupFailure(logText);
     console.error(
-      `Error: tunnel process exited during startup${exitCode !== null ? ` (exit code ${exitCode})` : ""}. Logs: ${logPath}`,
+      `Error (${exitCode ?? "unknown"}): tunnel process exited during startup${reason ? `: ${reason}` : "."}`,
     );
+    console.error(`Logs: ${logPath}`);
     process.exit(1);
   }
 
@@ -411,16 +422,44 @@ async function spawnDetachedTunnel(): Promise<void> {
   if (adopted) {
     console.log(adoptedTunnelStopNotice(child.pid));
   } else {
-    console.log(`Stop with: kill ${child.pid}`);
+    console.log("Stop with: cadet tunnel stop");
   }
 }
 
 export const tunnel = Object.assign(
   async function tunnel(): Promise<void> {
-    const { assistantName, provider, domain, clearDomain, detach } =
+    if (process.argv[3] === "stop") {
+      const args = process.argv.slice(4);
+      if (args.includes("--help") || args.includes("-h")) {
+        console.log("Usage: cadet tunnel stop [<name>]");
+        console.log(
+          "Stop the recorded Cadet-managed tunnel, keeping nginx and the saved domain.",
+        );
+        return;
+      }
+      if (args.some((arg) => arg.startsWith("-")))
+        throw new Error("Usage: cadet tunnel stop [<name>]");
+      const { entry, workspaceDir } = resolveLocalTunnelTarget(
+        args.join(" ") || null,
+      );
+      if (!readRootProcesses().tunnel) {
+        console.log(
+          "No Cadet-managed tunnel is recorded. Externally started tunnels must be stopped directly.",
+        );
+        return;
+      }
+      const stopped = await stopTunnelProcess(entry.assistantId, workspaceDir);
+      console.log(
+        stopped
+          ? "Tunnel stopped. nginx and the saved domain are unchanged."
+          : "No running tunnel found; cleared stale tunnel state.",
+      );
+      return;
+    }
+    const { assistantName, provider, domain, clearDomain, foreground } =
       parseArgs();
 
-    if (detach) {
+    if (!foreground) {
       await spawnDetachedTunnel();
       return;
     }