@mycadet/cli 0.12.10 → 0.13.0-dev.202610171617.9ea363e

package/src/lib/__tests__/http-client-version.test.ts

@@ -0,0 +1,29 @@
+import { afterAll, afterEach, expect, spyOn, test } from "bun:test";
+import { fetchCurrentVersion } from "../http-client.js";
+
+const request = spyOn(globalThis, "fetch");
+afterEach(() => request.mockReset());
+afterAll(() => request.mockRestore());
+
+test("reads the gateway's version through the public health endpoint", async () => {
+  request.mockResolvedValueOnce(
+    Response.json({ version: "1.2.3", status: "ok" }),
+  );
+  expect(await fetchCurrentVersion("http://127.0.0.1:7830")).toBe("1.2.3");
+  expect(request.mock.calls[0][0]).toBe("http://127.0.0.1:7830/healthz");
+});
+
+test("an unverified gateway response never supplies a release version", async () => {
+  for (const value of [{}, null, { version: "" }, { version: 123 }]) {
+    request.mockResolvedValueOnce(Response.json(value));
+    expect(await fetchCurrentVersion("http://127.0.0.1:7830")).toBeUndefined();
+  }
+  request.mockResolvedValueOnce(new Response("not JSON"));
+  expect(await fetchCurrentVersion("http://127.0.0.1:7830")).toBeUndefined();
+  request.mockResolvedValueOnce(
+    Response.json({ version: "1.2.3" }, { status: 503 }),
+  );
+  expect(await fetchCurrentVersion("http://127.0.0.1:7830")).toBeUndefined();
+  request.mockRejectedValueOnce(new Error("offline"));
+  expect(await fetchCurrentVersion("http://127.0.0.1:7830")).toBeUndefined();
+});

package/src/lib/__tests__/runtime-url.test.ts

@@ -1,10 +1,7 @@
 import { describe, expect, test } from "bun:test";
 
 import type { AssistantEntry } from "../assistant-config.js";
-import {
-  resolveRuntimeMigrationUrl,
-  resolveRuntimeUrl,
-} from "../runtime-url.js";
+import { resolveRuntimeUrl } from "../runtime-url.js";
 
 function makeEntry(
   overrides: Partial<AssistantEntry> & {
@@ -20,75 +17,6 @@ function makeEntry(
   };
 }
 
-describe("resolveRuntimeMigrationUrl", () => {
-  test("local cloud uses gateway-loopback /v1/migrations/<subpath>", () => {
-    const entry = makeEntry({
-      cloud: "local",
-      runtimeUrl: "http://localhost:7821",
-      assistantId: "ast-local-1",
-    });
-    expect(resolveRuntimeMigrationUrl(entry, "export-to-gcs")).toBe(
-      "http://localhost:7821/v1/migrations/export-to-gcs",
-    );
-    expect(resolveRuntimeMigrationUrl(entry, "import-from-gcs")).toBe(
-      "http://localhost:7821/v1/migrations/import-from-gcs",
-    );
-    expect(resolveRuntimeMigrationUrl(entry, "jobs/job-abc")).toBe(
-      "http://localhost:7821/v1/migrations/jobs/job-abc",
-    );
-  });
-
-  test("docker cloud uses gateway-loopback /v1/migrations/<subpath>", () => {
-    const entry = makeEntry({
-      cloud: "docker",
-      runtimeUrl: "http://localhost:7831",
-      assistantId: "ast-docker-1",
-    });
-    expect(resolveRuntimeMigrationUrl(entry, "export-to-gcs")).toBe(
-      "http://localhost:7831/v1/migrations/export-to-gcs",
-    );
-  });
-
-  test("cadet (cloud-managed) cloud uses wildcard-proxy /v1/assistants/<id>/migrations/<subpath>", () => {
-    const entry = makeEntry({
-      cloud: "cadet",
-      runtimeUrl: "https://cloud.mycadet.ai",
-      assistantId: "11111111-2222-3333-4444-555555555555",
-    });
-    expect(resolveRuntimeMigrationUrl(entry, "export-to-gcs")).toBe(
-      "https://cloud.mycadet.ai/v1/assistants/11111111-2222-3333-4444-555555555555/migrations/export-to-gcs",
-    );
-    expect(resolveRuntimeMigrationUrl(entry, "import-from-gcs")).toBe(
-      "https://cloud.mycadet.ai/v1/assistants/11111111-2222-3333-4444-555555555555/migrations/import-from-gcs",
-    );
-    expect(resolveRuntimeMigrationUrl(entry, "jobs/job-xyz")).toBe(
-      "https://cloud.mycadet.ai/v1/assistants/11111111-2222-3333-4444-555555555555/migrations/jobs/job-xyz",
-    );
-  });
-
-  test("dev platform URL still routes through the wildcard prefix", () => {
-    const entry = makeEntry({
-      cloud: "cadet",
-      runtimeUrl: "https://dev-cloud.mycadet.ai",
-      assistantId: "ast-dev-1",
-    });
-    expect(resolveRuntimeMigrationUrl(entry, "export-to-gcs")).toBe(
-      "https://dev-cloud.mycadet.ai/v1/assistants/ast-dev-1/migrations/export-to-gcs",
-    );
-  });
-
-  test("a non-cadet, non-local cloud (e.g. gcp) uses the local-shape URL", () => {
-    const entry = makeEntry({
-      cloud: "gcp",
-      runtimeUrl: "http://10.0.0.5:7821",
-      assistantId: "ast-gcp-1",
-    });
-    expect(resolveRuntimeMigrationUrl(entry, "export-to-gcs")).toBe(
-      "http://10.0.0.5:7821/v1/migrations/export-to-gcs",
-    );
-  });
-});
-
 describe("resolveRuntimeUrl", () => {
   test("local cloud uses gateway-loopback /v1/<subpath>", () => {
     const entry = makeEntry({
@@ -112,9 +40,9 @@ describe("resolveRuntimeUrl", () => {
     );
   });
 
-  test("cadet cloud uses wildcard-proxy /v1/assistants/<id>/<subpath>", () => {
+  test("cloud home uses wildcard-proxy /v1/assistants/<id>/<subpath>", () => {
     const entry = makeEntry({
-      cloud: "cadet",
+      cloud: "cloud",
       runtimeUrl: "https://cloud.mycadet.ai",
       assistantId: "11111111-2222-3333-4444-555555555555",
     });

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. */
@@ -154,6 +136,8 @@ interface LockfileData {
   cloudBaseUrl?: string;
   tunnel?: RootProcessRecord;
   app?: RootProcessRecord;
+  /** The nginx edge's shell selection; see readEdgeShellSelection. */
+  edgeShell?: unknown;
   [key: string]: unknown;
 }
 
@@ -170,6 +154,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 +235,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);
   });
 }
@@ -269,6 +266,27 @@ export function readRootProcesses(): {
   return { tunnel: data.tunnel, app: data.app };
 }
 
+/**
+ * The nginx edge's shell selection, persisted at the lockfile root beside the
+ * `app` record that tracks the edge's process. The edge is a CLI-managed
+ * server rather than a per-cadet setting, and that record is lifecycle-scoped
+ * (cleared when the edge stops), so the selection lives on its own root key
+ * to survive restarts. Read raw: the lockfile is user-editable disk state,
+ * so the shape check lives with the readers.
+ */
+export function readEdgeShellSelection(): unknown {
+  return readLockfile().edgeShell;
+}
+
+/** Persist the nginx edge's shell selection under the lockfile lock. */
+export function saveEdgeShellSelection(shell: "web" | "app"): void {
+  withCliLockfileLock(() => {
+    const data = readLockfile();
+    data.edgeShell = shell;
+    writeLockfileUnlocked(data);
+  });
+}
+
 /**
  * Try to extract a port number from a URL string (e.g. `http://localhost:7830`).
  * Returns undefined if the URL is malformed or has no explicit port.
@@ -442,7 +460,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 `[]`.
  */