@mycadet/cli 0.12.11 → 0.13.0

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.ts

@@ -28,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,

package/src/lib/cloud-releases.ts

@@ -1,3 +1,6 @@
+import { z } from "zod";
+
+import { CADET_GITHUB_REPOSITORY } from "./github-repository.js";
 import { getCloudUrl } from "./cloud-client.js";
 import { dockerhubImages } from "./docker.js";
 import type { ServiceName } from "./docker.js";
@@ -22,12 +25,40 @@ function releasesOptsFor(channel: ReleaseChannel): { channel?: "preview" } {
   return channel === "preview" ? { channel: "preview" } : {};
 }
 
-export interface ReleaseListItem {
-  version: string;
-  is_stable?: boolean;
-  assistant_image_ref?: string | null;
-  gateway_image_ref?: string | null;
-  credential_executor_image_ref?: string | null;
+const ReleaseListItemSchema = z.object({
+  version: z.string().min(1),
+  is_stable: z.boolean().optional(),
+  assistant_image_ref: z.string().nullable().optional(),
+  gateway_image_ref: z.string().nullable().optional(),
+  credential_executor_image_ref: z.string().nullable().optional(),
+});
+
+export type ReleaseListItem = z.infer<typeof ReleaseListItemSchema>;
+
+const STABLE_VERSION = /^(?:v)?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+const GitHubReleaseSchema = z.object({
+  tag_name: z.string().regex(STABLE_VERSION),
+  draft: z.literal(false),
+  prerelease: z.literal(false),
+});
+
+async function fetchLatestGitHubStableVersion(): Promise<string | null> {
+  try {
+    const response = await loopbackSafeFetch(
+      `https://api.github.com/repos/${CADET_GITHUB_REPOSITORY}/releases/latest`,
+      {
+        headers: { Accept: "application/vnd.github+json" },
+        signal: AbortSignal.timeout(10_000),
+      },
+    );
+    if (!response.ok) {
+      return null;
+    }
+    const parsed = GitHubReleaseSchema.safeParse(await response.json());
+    return parsed.success ? parsed.data.tag_name.replace(/^v/, "") : null;
+  } catch {
+    return null;
+  }
 }
 
 /**
@@ -56,15 +87,21 @@ export async function fetchReleases(opts?: {
       `${cloudUrl}/v1/releases/?${filter}&limit=${RELEASES_FETCH_LIMIT}`,
       { signal: AbortSignal.timeout(10_000) },
     );
-    if (!response.ok) return null;
-    return (await response.json()) as ReleaseListItem[];
+    if (!response.ok) {
+      return null;
+    }
+    const parsed = z
+      .array(ReleaseListItemSchema)
+      .safeParse(await response.json());
+    return parsed.success ? parsed.data : null;
   } catch {
     return null;
   }
 }
 
 /**
- * Fetch the latest release version for a channel from the Cadet Cloud API.
+ * Fetch the latest release version from Cadet Cloud, falling back to GitHub
+ * for stable releases when the cloud has no usable result.
  * Returns the version string (e.g. "0.7.0") or null if unavailable.
  * The releases endpoint returns entries ordered newest-first, so the first
  * entry is the latest for the requested channel.
@@ -73,7 +110,14 @@ export async function fetchLatestVersion(
   channel: ReleaseChannel = "stable",
 ): Promise<string | null> {
   const releases = await fetchReleases(releasesOptsFor(channel));
-  return releases?.[0]?.version ?? null;
+  if (channel === "preview") {
+    return releases?.[0]?.version ?? null;
+  }
+  const latest = releases?.find(
+    (release) =>
+      release.is_stable !== false && STABLE_VERSION.test(release.version),
+  );
+  return latest?.version ?? fetchLatestGitHubStableVersion();
 }
 
 /**

package/src/lib/cloud-values.ts

@@ -1,3 +1,3 @@
 export function isCloudHome(cloud: unknown): boolean {
-  return cloud === "cloud" || cloud === "cadet";
+  return cloud === "cloud";
 }

package/src/lib/confirm-action.ts

@@ -1,6 +1,6 @@
 /**
- * Shared interactive confirmation for destructive CLI commands (retire, unpair,
- * …). Per cli/AGENTS.md, a command that removes assistant state must print the
+ * Shared interactive confirmation for destructive CLI commands (retire,
+ * devices revoke, …). Per cli/AGENTS.md, a command that removes assistant state must print the
  * resolved identity and require confirmation, with a `--yes` bypass for
  * automation.
  */

package/src/lib/docker.ts

@@ -296,6 +296,8 @@ export interface HatchDockerParams {
   /** Extra env vars forwarded into the assistant container. */
   flagEnvVars?: Record<string, string>;
   setupProviderCredentials?: boolean;
+  /** Whole-installation state installed into stopped containers before startup. */
+  initialArchive?: string;
   /**
    * Path to a local source tree to build images from before hatching. When
    * provided, this path is used directly as the repo root and no file
@@ -812,6 +814,7 @@ export const SERVICE_START_ORDER: ServiceName[] = [
 /** Start all three containers in dependency order. */
 export async function startContainers(
   opts: {
+    createOnly?: boolean;
     signingKey?: string;
     bootstrapSecret?: string;
     cesServiceToken?: string;
@@ -832,8 +835,13 @@ export async function startContainers(
     avatarDevicePath: resolveAvatarDevicePath(),
   });
   for (const service of SERVICE_START_ORDER) {
-    log(`🚀 Starting ${service} container...`);
-    await exec("docker", runArgs[service]());
+    const args = runArgs[service]();
+    if (opts.createOnly) {
+      args[0] = "create";
+      args.splice(args.indexOf("-d"), 1);
+    }
+    log(`${opts.createOnly ? "Creating" : "Starting"} ${service} container...`);
+    await exec("docker", args);
   }
 }
 
@@ -849,14 +857,23 @@ export async function stopContainers(
 /** Stop containers without removing them (preserves state for `docker start`). */
 export async function sleepContainers(
   res: ReturnType<typeof dockerResourceNames>,
+  options: { timeoutMs?: number } = {},
 ): Promise<void> {
   for (const container of [
-    res.cesContainer,
-    res.gatewayContainer,
     res.assistantContainer,
+    res.gatewayContainer,
+    res.cesContainer,
   ]) {
     try {
-      await exec("docker", ["stop", container]);
+      const status = await execOutput("docker", ["inspect", "--format", "{{.State.Status}}", container]);
+      if (status === "exited" || status === "created") continue;
+      if (status !== "running") throw new Error(`${container} is ${status}; cannot stop gracefully.`);
+      await exec("docker", ["kill", "--signal=SIGTERM", container]);
+      const deadline = Date.now() + (options.timeoutMs ?? 60_000);
+      while (await execOutput("docker", ["inspect", "--format", "{{.State.Running}}", container]) === "true") {
+        if (Date.now() >= deadline) throw new Error(`${container} did not stop gracefully.`);
+        await new Promise((resolve) => setTimeout(resolve, 250));
+      }
     } catch (err) {
       const msg =
         err instanceof Error ? err.message.toLowerCase() : String(err);
@@ -1630,7 +1647,9 @@ export async function hatchDocker(params: HatchDockerParams): Promise<void> {
     }
 
     const cesServiceToken = randomBytes(32).toString("hex");
-    const signingKey = randomBytes(32).toString("hex");
+    const signingKey = params.initialArchive
+      ? undefined
+      : randomBytes(32).toString("hex");
 
     // When launched by a remote hatch startup script, the env var
     // GUARDIAN_BOOTSTRAP_SECRET is already set with the laptop's secret.
@@ -1669,8 +1688,26 @@ export async function hatchDocker(params: HatchDockerParams): Promise<void> {
       ...flagEnvVars,
       CADET_DEVICE_ID: hostDeviceId,
     };
+    const runtimeUrl = `http://localhost:${gatewayPort}`;
+    const dockerEntry: AssistantEntry = {
+      assistantId: instanceName,
+      runtimeUrl,
+      cloud: "docker",
+      hatchedAt: new Date().toISOString(),
+      guardianBootstrapSecret: ownSecret,
+      containerInfo: {
+        assistantImage: imageTags.assistant,
+        gatewayImage: imageTags.gateway,
+        cesImage: imageTags["credential-executor"],
+        assistantPort,
+      },
+    };
+    if (params.initialArchive) {
+      saveAssistantEntry(dockerEntry);
+    }
     await startContainers(
       {
+        createOnly: !!params.initialArchive,
         signingKey,
         bootstrapSecret,
         cesServiceToken,
@@ -1688,29 +1725,29 @@ export async function hatchDocker(params: HatchDockerParams): Promise<void> {
     );
     const containersUpAt = Date.now();
 
-    const runtimeUrl = `http://localhost:${gatewayPort}`;
-    const dockerEntry: AssistantEntry = {
-      assistantId: instanceName,
-      runtimeUrl,
-      cloud: "docker",
-      hatchedAt: new Date().toISOString(),
-      guardianBootstrapSecret: ownSecret,
-      containerInfo: {
-        assistantImage: imageTags.assistant,
-        gatewayImage: imageTags.gateway,
-        cesImage: imageTags["credential-executor"],
-        assistantPort,
-      },
-    };
     emitProgress(5, 6, "Saving configuration...");
     saveAssistantEntry(dockerEntry);
     setActiveAssistant(instanceName);
 
+    if (params.initialArchive) {
+      const { initializeRootArchive, DockerRootStorage } =
+        await import("./root-backup.js");
+      await initializeRootArchive(dockerEntry, params.initialArchive);
+      const storage = new DockerRootStorage(dockerEntry);
+      storage.initialRunning = new Set(Object.values(storage.containers));
+      await storage.resume();
+    }
+
     emitProgress(6, 6, "Waiting for services...");
     // Hatch always detaches; only watch mode keeps the log stream attached.
     const waitDetached = !watch;
-    const { ready, guardianAccessToken, notReadyReason } =
-      await waitForGatewayAndLease({
+    const { ready, guardianAccessToken, notReadyReason } = params.initialArchive
+      ? {
+          ready: true,
+          guardianAccessToken: undefined,
+          notReadyReason: undefined,
+        }
+      : await waitForGatewayAndLease({
         bootstrapSecret: ownSecret,
         containerName: res.assistantContainer,
         detached: waitDetached,

package/src/lib/github-repository.ts

@@ -0,0 +1,2 @@
+/** Source repository for published Cadet releases. */
+export const CADET_GITHUB_REPOSITORY = "vargasjr-dev/mycadet-temp";