@mycadet/cli 0.12.10 → 0.13.0

package/src/lib/__tests__/web-dist.test.ts

@@ -3,7 +3,7 @@ import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-import { findWebDistDir } from "../web-dist.js";
+import { findWebDistDir, readWebReleaseVersion } from "../web-dist.js";
 
 const tempDirs: string[] = [];
 
@@ -84,3 +84,29 @@ test("preserves installed package and source checkout resolution", () => {
     }),
   ).toBe(sourceDist);
 });
+
+test("reads the built UI release, including a normalized version prefix", () => {
+  const root = makeTempDir();
+  writeFileSync(
+    join(root, "release.json"),
+    JSON.stringify({ version: "v1.2.3-dev.5" }),
+  );
+  expect(readWebReleaseVersion(root)).toBe("1.2.3-dev.5");
+});
+
+test("missing or malformed release metadata cannot stand in for a release", () => {
+  const root = makeTempDir();
+  expect(readWebReleaseVersion(root)).toBeUndefined();
+  for (const value of [
+    "not JSON",
+    "null",
+    "{}",
+    '{"version":null}',
+    '{"version":"latest"}',
+    '{"version":""}',
+    '{"version":"bundle-hash"}',
+  ]) {
+    writeFileSync(join(root, "release.json"), value);
+    expect(readWebReleaseVersion(root)).toBeUndefined();
+  }
+});

package/src/lib/assistant-client.ts

@@ -334,7 +334,7 @@ export class AssistantClient {
 
     // A stale cached Cadet-Organization-Id is the usual cause of a 401 on the
     // platform path (e.g. the user switched orgs elsewhere). Drop it and retry
-    // once. Mirrors localRuntimeIdentity in local-runtime-client.ts.
+    // once.
     if (response.status === 401 && this.authMode === "platform" && this.token) {
       invalidateOrgIdCache(this.token, this.runtimeUrl);
       this.platformHeaders = undefined;

package/src/lib/assistant-config.ts

@@ -103,16 +103,11 @@ export type AssistantEntry = Omit<
   /** Loopback URL for same-machine health checks (e.g. `http://127.0.0.1:7831`).
    *  Avoids mDNS resolution issues when the machine checks its own gateway. */
   localUrl?: string;
-  /** Public https ingress URL recorded by `cadet tunnel` providers for this
-   *  instance. The advertised-URL default for remote-web pairing. */
-  ingressUrl?: string;
   bearerToken?: string;
   /** True when this entry was registered via `cadet connect import` (a remote
    *  pairing). Set alongside `cloud: "paired"`; also backs the re-import /
    *  overwrite guard in connect import. */
   paired?: boolean;
-  instanceId?: string;
-  namespace?: string;
   project?: string;
   region?: string;
   sshUser?: string;
@@ -123,19 +118,6 @@ export type AssistantEntry = Omit<
   guardianBootstrapSecret?: string;
   /** Docker image metadata for rollback. Only present for docker topology entries. */
   containerInfo?: ContainerInfo;
-  /** Docker image metadata from before the last upgrade. Enables rollback to the prior version. */
-  previousContainerInfo?: ContainerInfo;
-  /** Path to the .vbundle backup created for the most recent upgrade. Used by rollback to restore
-   *  only the backup from the specific upgrade being rolled back — never a stale backup from a
-   *  previous upgrade cycle. */
-  preUpgradeBackupPath?: string;
-  /** Running version of the service group at the time of the last upgrade, as reported by
-   *  the health endpoint.  Used by saved-state rollback for logging / broadcast events. */
-  previousVersion?: string;
-  /** Pre-upgrade DB migration version — used by rollback to know how far back to revert. */
-  previousDbMigrationVersion?: number;
-  /** Pre-upgrade workspace migration ID — used by rollback to know how far back to revert. */
-  previousWorkspaceMigrationId?: string;
   /** Client-minted uuid (web's temp-client-id pattern) the CLI addresses this
    *  assistant's chat conversation by. Minted once on first `cadet client`
    *  launch and persisted here so every session shares one conversation. */
@@ -170,6 +152,10 @@ export interface RootProcessRecord {
   /** The assistant the process fronts, so `cadet ps` can nest the row. */
   assistantId?: string;
   startedAt: string;
+  /** Listening port for the nginx edge. */
+  port?: number;
+  /** Managed process temporarily displaced by a pairing-only tunnel. */
+  previous?: RootProcessRecord;
 }
 
 export type RootProcessKind = "tunnel" | "app";
@@ -247,12 +233,21 @@ export function stampRootProcess(
   });
 }
 
-/** Drop the recorded root process entry, e.g. once the process is stopped. */
-export function clearRootProcess(kind: RootProcessKind): void {
+/** Release a recorded process, preserving a replacement or restoring a displaced record. */
+export function clearRootProcess(
+  kind: RootProcessKind,
+  expectedPid?: number,
+): void {
   withCliLockfileLock(() => {
     const data = readLockfile();
-    if (data[kind] === undefined) return;
-    delete data[kind];
+    const record = data[kind];
+    if (
+      record === undefined ||
+      (expectedPid !== undefined && record.pid !== expectedPid)
+    )
+      return;
+    if (record.previous) data[kind] = record.previous;
+    else delete data[kind];
     writeLockfileUnlocked(data);
   });
 }
@@ -442,7 +437,9 @@ export function loadLatestAssistant(): AssistantEntry | null {
 }
 
 export function findAssistantByName(name: string): AssistantEntry | null {
-  return loadAllAssistants().find((entry) => entry.assistantId === name) ?? null;
+  return (
+    loadAllAssistants().find((entry) => entry.assistantId === name) ?? null
+  );
 }
 
 export function getAssistantDisplayName(entry: AssistantEntry): string {

package/src/lib/backup-ops.ts

@@ -1,21 +1,8 @@
-import {
-  existsSync,
-  mkdirSync,
-  readdirSync,
-  readFileSync,
-  statSync,
-  unlinkSync,
-  writeFileSync,
-} from "fs";
-import { dirname, join } from "path";
+import { existsSync, readdirSync, statSync, unlinkSync } from "fs";
+import { join } from "path";
 
-import {
-  importStagedBundle,
-  stageBundleForRestore,
-  type RestoreStagingTarget,
-} from "./bundle-staging.js";
-import { loadGuardianToken, refreshGuardianToken } from "./guardian-token.js";
-import { loopbackSafeFetch } from "./loopback-fetch.js";
+import { findAssistantByName } from "./assistant-config.js";
+import { createRootBackup, restoreRootBackup } from "./root-backup.js";
 import { getStateDir } from "./environments/paths.js";
 import { getCurrentEnvironment } from "./environments/resolve.js";
 
@@ -31,261 +18,60 @@ export function formatSize(bytes: number): string {
   return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
 }
 
-/**
- * Obtain a valid guardian access token.
- *
- * Resolution order:
- *  1. Cached token that is not yet expired — use as-is.
- *  2. Cached token with a valid refresh token — call /v1/guardian/refresh.
- *  3. No usable token — return null so callers can skip the backup gracefully
- *     rather than hitting /v1/guardian/init (which 403s on bootstrapped instances).
- */
-async function getGuardianAccessToken(
-  runtimeUrl: string,
-  assistantId: string,
-): Promise<string | null> {
-  const tokenData = loadGuardianToken(assistantId);
-  if (tokenData && new Date(tokenData.accessTokenExpiresAt) > new Date()) {
-    return tokenData.accessToken;
-  }
-  const refreshed = await refreshGuardianToken(runtimeUrl, assistantId);
-  return refreshed?.accessToken ?? null;
-}
-
-/**
- * Create a .vbundle backup of a running assistant.
- * Returns the path to the saved backup, or null if backup failed.
- * Never throws — failures are logged as warnings.
- */
+/** Internal safety backup callers resolve their registered host topology, never runtime auth. */
 export async function createBackup(
-  runtimeUrl: string,
+  _runtimeUrl: string,
   assistantId: string,
   options?: { prefix?: string; description?: string; timeoutMs?: number },
 ): Promise<string | null> {
-  const timeoutMs = options?.timeoutMs ?? 120_000;
   try {
-    let accessToken = await getGuardianAccessToken(runtimeUrl, assistantId);
-    if (!accessToken) {
-      console.warn(
-        "Warning: backup skipped — no valid guardian token available",
-      );
-      return null;
-    }
-
-    let response = await loopbackSafeFetch(
-      `${runtimeUrl}/v1/migrations/export`,
-      {
-        method: "POST",
-        headers: {
-          Authorization: `Bearer ${accessToken}`,
-          "Content-Type": "application/json",
-        },
-        body: JSON.stringify({
-          description: options?.description ?? "CLI backup",
-        }),
-        signal: AbortSignal.timeout(timeoutMs),
-      },
-    );
-
-    // Retry once with a refreshed token on 401 — the cached token may be
-    // stale after a container restart that regenerated the gateway signing key.
-    if (response.status === 401) {
-      const refreshed = await refreshGuardianToken(runtimeUrl, assistantId);
-      if (!refreshed) {
-        console.warn(
-          `Warning: backup export failed (401) and token refresh failed`,
-        );
-        return null;
-      }
-      accessToken = refreshed.accessToken;
-      response = await loopbackSafeFetch(`${runtimeUrl}/v1/migrations/export`, {
-        method: "POST",
-        headers: {
-          Authorization: `Bearer ${accessToken}`,
-          "Content-Type": "application/json",
-        },
-        body: JSON.stringify({
-          description: options?.description ?? "CLI backup",
-        }),
-        signal: AbortSignal.timeout(timeoutMs),
-      });
-    }
-
-    if (!response.ok) {
-      const body = await response.text();
-      console.warn(
-        `Warning: backup export failed (${response.status}): ${body}`,
-      );
-      return null;
-    }
-
-    const arrayBuffer = await response.arrayBuffer();
-    const data = new Uint8Array(arrayBuffer);
-
-    const isoTimestamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const entry = findAssistantByName(assistantId);
+    if (!entry)
+      throw new Error(`No registered assistant found for '${assistantId}'.`);
     const prefix = options?.prefix ?? assistantId;
-    const outputPath = join(
+    if (prefix.includes("/") || prefix.includes("\\"))
+      throw new Error("Backup prefix must be a filename.");
+    const path = join(
       getBackupsDir(),
-      `${prefix}-${isoTimestamp}.vbundle`,
+      `${prefix}-${new Date().toISOString().replace(/[:.]/g, "-")}.tar.gz`,
     );
-
-    mkdirSync(dirname(outputPath), { recursive: true });
-    writeFileSync(outputPath, data);
-
-    return outputPath;
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    console.warn(`Warning: backup failed: ${msg}`);
-    return null;
-  }
-}
-
-async function postRestoreWithRetries(
-  postImport: () => Promise<Response>,
-  runtimeUrl: string,
-  assistantId: string,
-  onTokenRefresh: (token: string) => void,
-): Promise<Response | null> {
-  let response = await postImport();
-
-  // Retry once with a refreshed token on 401 — the cached token may be
-  // stale after a container restart that regenerated the gateway signing key.
-  if (response.status === 401) {
-    const refreshed = await refreshGuardianToken(runtimeUrl, assistantId);
-    if (!refreshed) {
-      console.warn(`Warning: restore failed (401) and token refresh failed`);
-      return null;
-    }
-    onTokenRefresh(refreshed.accessToken);
-    response = await postImport();
-  }
-
-  // A freshly-(re)started gateway 503s {status:"starting"} for a couple of
-  // seconds until its own assistant poll observes the migration state and
-  // opens the traffic gate — retry through that window rather than failing
-  // the recovery. The daemon's running-migrations 503 carries a `reason`
-  // field and is excluded: the import must not race an in-flight migration.
-  const startingGateDeadline = Date.now() + 15_000;
-  while (!response.ok) {
-    const body = await response.text();
-    let gatewayStarting = false;
-    try {
-      const parsed = JSON.parse(body) as {
-        status?: string;
-        reason?: string;
-      };
-      gatewayStarting =
-        parsed.status === "starting" && parsed.reason === undefined;
-    } catch {
-      // Non-JSON error body — not the starting gate.
-    }
-    if (gatewayStarting && Date.now() < startingGateDeadline) {
-      await new Promise((r) => setTimeout(r, 1_000));
-      response = await postImport();
-      continue;
-    }
-    console.warn(`Warning: restore failed (${response.status}): ${body}`);
-    return null;
-  }
-
-  return response;
-}
-
-async function finishRestoreResponse(response: Response): Promise<boolean> {
-  const result = (await response.json()) as {
-    success: boolean;
-    message?: string;
-    reason?: string;
-  };
-  if (!result.success) {
+    await createRootBackup(entry, path);
+    return path;
+  } catch (error) {
     console.warn(
-      `Warning: restore failed — ${result.message ?? result.reason ?? "unknown reason"}`,
+      `Backup failed: ${error instanceof Error ? error.message : String(error)}`,
     );
-    return false;
+    return null;
   }
-  return true;
 }
 
-/**
- * Restore a .vbundle backup into a running assistant.
- * Returns true if restore succeeded, false otherwise.
- * Never throws — failures are logged as warnings.
- */
+/** Restore every persistent root; failed-state recovery can leave services stopped for its caller to restart. */
 export async function restoreBackup(
-  runtimeUrl: string,
+  _runtimeUrl: string,
   assistantId: string,
   backupPath: string,
-  staging?: RestoreStagingTarget | null,
+  options: { resume?: boolean } = {},
 ): Promise<boolean> {
   try {
-    if (!existsSync(backupPath)) {
-      console.warn(`Warning: backup file not found: ${backupPath}`);
-      return false;
-    }
-
-    const initialToken = await getGuardianAccessToken(runtimeUrl, assistantId);
-    if (!initialToken) {
-      console.warn(
-        "Warning: restore skipped — no valid guardian token available",
-      );
-      return false;
-    }
-    let token = initialToken;
-
-    if (staging) {
-      const staged = await stageBundleForRestore(staging, backupPath);
-      try {
-        const postImport = () =>
-          importStagedBundle(runtimeUrl, token, staged.relativePath);
-        const response = await postRestoreWithRetries(
-          postImport,
-          runtimeUrl,
-          assistantId,
-          (nextToken) => {
-            token = nextToken;
-          },
-        );
-        if (!response) {
-          return false;
-        }
-        return await finishRestoreResponse(response);
-      } finally {
-        await staged.cleanup();
-      }
-    }
-
-    const bundleData = new Uint8Array(readFileSync(backupPath));
-    const postImport = () =>
-      loopbackSafeFetch(`${runtimeUrl}/v1/migrations/import`, {
-        method: "POST",
-        headers: {
-          Authorization: `Bearer ${token}`,
-          "Content-Type": "application/octet-stream",
-        },
-        body: bundleData,
-        signal: AbortSignal.timeout(120_000),
-      });
-    const response = await postRestoreWithRetries(
-      postImport,
-      runtimeUrl,
-      assistantId,
-      (nextToken) => {
-        token = nextToken;
-      },
+    const entry = findAssistantByName(assistantId);
+    if (!entry)
+      throw new Error(`No registered assistant found for '${assistantId}'.`);
+    await restoreRootBackup(entry, backupPath, options);
+    return true;
+  } catch (error) {
+    console.warn(
+      `Restore failed: ${error instanceof Error ? error.message : String(error)}`,
     );
-    if (!response) {
-      return false;
-    }
-    return await finishRestoreResponse(response);
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    console.warn(`Warning: restore failed: ${msg}`);
     return false;
   }
 }
 
-/** Filename kinds this CLI writes: `<assistantId>-<kind>-<timestamp>.vbundle`. */
-export const CLI_BACKUP_KINDS = ["pre-upgrade", "pre-teleport"] as const;
+/** Filename kinds this CLI writes: `<assistantId>-<kind>-<timestamp>.tar.gz`. */
+export const CLI_BACKUP_KINDS = [
+  "pre-upgrade",
+  "pre-rollback",
+  "pre-teleport",
+] as const;
 export type CliBackupKind = (typeof CLI_BACKUP_KINDS)[number];
 
 /** `new Date().toISOString().replace(/[:.]/g, "-")`, as used in every CLI backup filename. */
@@ -307,12 +93,12 @@ export function assistantBackupFilenamePattern(
   kinds: readonly CliBackupKind[] = CLI_BACKUP_KINDS,
 ): RegExp {
   return new RegExp(
-    `^${escapeRegExp(assistantId)}-(?:${kinds.join("|")})-${BACKUP_TIMESTAMP_PATTERN}\\.vbundle$`,
+    `^${escapeRegExp(assistantId)}-(?:${kinds.join("|")})-${BACKUP_TIMESTAMP_PATTERN}\\.tar\\.gz$`,
   );
 }
 
 /**
- * Modification times of the `.vbundle` backups this CLI has written for
+ * Modification times of the `.tar.gz` backups this CLI has written for
  * `assistantId` (every kind in `CLI_BACKUP_KINDS`), as ISO timestamps.
  * Missing directory yields `[]`.
  */

package/src/lib/cloud-client.ts

@@ -146,13 +146,10 @@ const ORG_ID_CACHE_TTL_MS = 60_000; // 60 seconds
  * orgs in another tab). Clearing the entry forces the next `authHeaders`
  * call to refetch the org ID from the cloud.
  *
- * Exported so other modules (e.g. local-runtime-client) can implement the
+ * Exported so cloud API consumers can implement the
  * same retry pattern without needing direct access to the cache map.
  */
-export function invalidateOrgIdCache(
-  token: string,
-  cloudUrl?: string,
-): void {
+export function invalidateOrgIdCache(token: string, cloudUrl?: string): void {
   orgIdCache.delete(`${token}::${cloudUrl ?? ""}`);
 }
 
@@ -658,9 +655,9 @@ export async function hatchAssistant(
   }
 
   if (response.status === 401 || response.status === 403) {
-    const detail = CloudErrorDetailSchema
-      .catch({})
-      .parse(await response.json().catch(() => ({})));
+    const detail = CloudErrorDetailSchema.catch({}).parse(
+      await response.json().catch(() => ({})),
+    );
     throw new Error(
       detail.detail ??
         "Invalid or expired token. Run `cadet login` to re-authenticate.",
@@ -671,9 +668,9 @@ export async function hatchAssistant(
     throw new Error("Insufficient balance to hatch a new assistant.");
   }
 
-  const errorBody = CloudErrorDetailSchema
-    .catch({})
-    .parse(await response.json().catch(() => ({})));
+  const errorBody = CloudErrorDetailSchema.catch({}).parse(
+    await response.json().catch(() => ({})),
+  );
   throw new Error(
     errorBody.detail ??
       `Platform API error: ${response.status} ${response.statusText}`,
@@ -987,7 +984,7 @@ export async function platformImportPreflightFromGcs(
     {
       method: "POST",
       headers: await authHeaders(token, cloudUrl),
-      signal: AbortSignal.timeout(120_000),
+      signal: AbortSignal.timeout(30 * 60_000),
       body: JSON.stringify({ bundle_key: bundleKey }),
     },
   );
@@ -1010,7 +1007,7 @@ export async function platformImportBundleFromGcs(
       method: "POST",
       headers: await authHeaders(token, cloudUrl),
       body: JSON.stringify({ bundle_key: bundleKey }),
-      signal: AbortSignal.timeout(60_000),
+      signal: AbortSignal.timeout(30 * 60_000),
     },
   );
 

package/src/lib/cloud-login-poll.ts

@@ -0,0 +1,75 @@
+import { z } from "zod";
+import { loopbackSafeFetch } from "./loopback-fetch.js";
+
+const requestSchema = z.object({
+  request_id: z.string().regex(/^[a-f0-9]{64}$/),
+  poll_secret: z.string().regex(/^[a-f0-9]{64}$/),
+  verification_uri: z.string().url(),
+  user_code: z.string().min(1),
+  interval: z.number().min(1).max(10),
+});
+const resultSchema = z.object({ session_token: z.string().min(1) });
+
+/** Browser approval and polling work when the terminal and browser are on different hosts. */
+export async function pollingCloudLogin(
+  cloudUrl: string,
+  options: {
+    timeoutMs?: number;
+    fetch?: (
+      input: string | URL | Request,
+      init?: RequestInit,
+    ) => Promise<Response>;
+    log?: (message: string) => void;
+  } = {},
+): Promise<string> {
+  const request = options.fetch ?? loopbackSafeFetch;
+  const log = options.log ?? console.log;
+  const signal = AbortSignal.timeout(options.timeoutMs ?? 300_000);
+  const origin = new URL(cloudUrl).origin;
+  try {
+    const started = await request(`${origin}/v1/auth/cli/start`, {
+      method: "POST",
+      signal,
+    });
+    if (!started.ok)
+      throw new Error(`Could not start terminal login (${started.status}).`);
+    const login = requestSchema.parse(await started.json());
+    log(`Open this URL to log in: ${login.verification_uri}`);
+    log(
+      `Confirm code ${login.user_code} in your browser. Waiting up to 5 minutes...`,
+    );
+    while (!signal.aborted) {
+      const response = await request(`${origin}/v1/auth/cli/poll`, {
+        method: "POST",
+        signal,
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          request_id: login.request_id,
+          poll_secret: login.poll_secret,
+        }),
+      });
+      if (response.status === 200)
+        return resultSchema.parse(await response.json()).session_token;
+      if (response.status === 410)
+        throw new Error("Login request expired. Run cadet login again.");
+      if (response.status !== 202)
+        throw new Error(`Login polling failed (${response.status}).`);
+      await new Promise<void>((resolve, reject) => {
+        const abort = () => {
+          clearTimeout(timer);
+          reject(new Error("Login timed out after 5 minutes."));
+        };
+        const timer = setTimeout(() => {
+          signal.removeEventListener("abort", abort);
+          resolve();
+        }, login.interval * 1000);
+        signal.addEventListener("abort", abort, { once: true });
+        if (signal.aborted) abort();
+      });
+    }
+    throw new Error("Login timed out after 5 minutes.");
+  } catch (error) {
+    if (signal.aborted) throw new Error("Login timed out after 5 minutes.");
+    throw error;
+  }
+}

package/src/lib/cloud-login.ts

@@ -6,6 +6,7 @@
  * login when the user picks that provider).
  */
 
+import { pollingCloudLogin } from "./cloud-login-poll.js";
 import { randomBytes } from "crypto";
 import { createServer } from "http";
 import type { AddressInfo } from "net";
@@ -27,7 +28,8 @@ import {
   readCloudToken,
   saveCloudToken,
 } from "./cloud-client.js";
-import { fetchAssistantIngressUrl, fetchCurrentVersion } from "./upgrade-lifecycle.js";
+import { fetchAssistantIngressUrl } from "./upgrade-lifecycle.js";
+import { fetchCurrentVersion } from "./http-client.js";
 import {
   CALLBACK_PATH,
   buildAuthorizeUrl,
@@ -37,7 +39,7 @@ import {
   generatePkcePair,
 } from "./workos-pkce.js";
 
-const LOGIN_TIMEOUT_MS = 120_000; // 2 minutes
+const LOGIN_TIMEOUT_MS = 300_000;
 
 function escapeHtml(s: string): string {
   return s
@@ -258,6 +260,7 @@ export function startLoopbackListener(
 
 /** App-held WorkOS PKCE login */
 export async function workosPkceLogin(cloudUrl: string): Promise<string> {
+  if (!process.stdin.isTTY) return pollingCloudLogin(cloudUrl);
   const clientId = await fetchWorkosClientId(cloudUrl);
   const { verifier, challenge } = generatePkcePair();
   const state = randomBytes(32).toString("hex");