@mycadet/cli 0.12.10 → 0.13.0

package/src/commands/backup.ts

@@ -1,409 +1,54 @@
-import { isCloudHome } from "../lib/cloud-values.js";
-import { mkdirSync, writeFileSync } from "fs";
-import { dirname, join } from "path";
-
-import type { AssistantEntry } from "../lib/assistant-config.js";
+import { stat } from "node:fs/promises";
+import { join } from "node:path";
 import { findAssistantByName } from "../lib/assistant-config.js";
-import { getBackupsDir, formatSize } from "../lib/backup-ops.js";
-import { loadGuardianToken, leaseGuardianToken } from "../lib/guardian-token";
-import { pollJobUntilDone } from "../lib/job-polling.js";
-import {
-  MigrationInProgressError,
-  localRuntimeExportToGcs,
-  localRuntimeIdentity,
-  localRuntimePollJobStatus,
-} from "../lib/local-runtime-client.js";
-import {
-  cloudRequestSignedUrl,
-  readCloudToken,
-} from "../lib/cloud-client.js";
-import { loopbackSafeFetch } from "../lib/loopback-fetch.js";
-
-// Default timeout for the runtime-direct export request. Overridable via
-// --export-timeout.
-const DEFAULT_EXPORT_TIMEOUT_MS = 300_000;
+import { formatSize, getBackupsDir } from "../lib/backup-ops.js";
+import { readCloudToken } from "../lib/cloud-client.js";
+import { isCloudHome } from "../lib/cloud-values.js";
+import { createRootBackup } from "../lib/root-backup.js";
+import { createPlatformBackup } from "../lib/teleport-backup.js";
 
 export const backup = Object.assign(
   async function backup(): Promise<void> {
-  const args = process.argv.slice(3);
-
-  if (args.includes("--help") || args.includes("-h")) {
-    console.log(
-      "Usage: cadet backup <name> [--output <path>] [--export-timeout <seconds>]",
-    );
-    console.log("");
-    console.log(
-      "Export a backup of a running assistant as a .vbundle archive.",
-    );
-    console.log("");
-    console.log("Arguments:");
-    console.log("  <name>                   Name of the assistant to back up");
-    console.log("");
-    console.log("Options:");
-    console.log("  --output <path>          Path to save the .vbundle file");
-    console.log(
-      "                           defaults to ~/.local/share/cadet/backups/<name>-<timestamp>.vbundle",
-    );
-    console.log(
-      `  --export-timeout <secs>  Export request timeout in seconds, defaults to ${DEFAULT_EXPORT_TIMEOUT_MS / 1000}`,
-    );
-    console.log("");
-    console.log("Examples:");
-    console.log("  cadet backup my-assistant");
-    console.log(
-      "  cadet backup my-assistant --output ~/Desktop/backup.vbundle",
-    );
-    console.log("  cadet backup my-assistant --export-timeout 600");
-    process.exit(0);
-  }
-
-  const name = args[0];
-  if (!name || name.startsWith("-")) {
-    console.error(
-      "Usage: cadet backup <name> [--output <path>] [--export-timeout <seconds>]",
-    );
-    process.exit(1);
-  }
-
-  // Parse flags
-  let outputArg: string | undefined;
-  let exportTimeoutMs = DEFAULT_EXPORT_TIMEOUT_MS;
-  for (let i = 1; i < args.length; i++) {
-    if (args[i] === "--output" && args[i + 1]) {
-      outputArg = args[i + 1];
-    } else if (args[i] === "--export-timeout" && args[i + 1]) {
-      const seconds = Number(args[i + 1]);
-      if (!Number.isFinite(seconds) || seconds <= 0) {
-        console.error(
-          `Error: --export-timeout must be a positive number of seconds (got '${args[i + 1]}').`,
-        );
-        process.exit(1);
-      }
-      exportTimeoutMs = seconds * 1000;
-    }
-  }
-
-  // Look up the instance
-  const entry = findAssistantByName(name);
-  if (!entry) {
-    console.error(`No assistant found with name '${name}'.`);
-    console.error("Run 'cadet hatch' first, or check the instance name.");
-    process.exit(1);
-  }
-
-  // Detect topology and route platform assistants through Django export
-  const cloud =
-    entry.cloud || (entry.project ? "gcp" : entry.sshUser ? "custom" : "local");
-
-  if (cloud === "apple-container") {
-    console.error(
-      `Error: '${name}' uses the Apple Containers runtime. Backup is not yet supported for this topology.`,
-    );
-    process.exit(1);
-  }
-
-  if (isCloudHome(cloud)) {
-    await backupPlatform(entry, name, outputArg);
-    return;
-  }
-
-  // Obtain an auth token
-  let accessToken: string;
-  const tokenData = loadGuardianToken(entry.assistantId);
-  if (tokenData && new Date(tokenData.accessTokenExpiresAt) > new Date()) {
-    accessToken = tokenData.accessToken;
-  } else {
-    try {
-      const freshToken = await leaseGuardianToken(
-        entry.runtimeUrl,
-        entry.assistantId,
-        entry.guardianBootstrapSecret,
+    const args = process.argv.slice(3);
+    if (args.includes("--help") || args.includes("-h")) {
+      console.log("Usage: cadet backup <name>");
+      console.log(
+        "Local/Docker: gracefully stop services, capture all persistent roots as tar.gz, then resume.",
       );
-      accessToken = freshToken.accessToken;
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      if (msg.includes("ECONNREFUSED") || msg.includes("fetch failed")) {
-        console.error(
-          `Error: Could not connect to assistant '${name}'. Is it running?`,
-        );
-        console.error(`Try: cadet wake ${name}`);
-        process.exit(1);
-      }
-      throw err;
-    }
-  }
-
-  // Call the export endpoint
-  let response: Response;
-  try {
-    response = await loopbackSafeFetch(
-      `${entry.runtimeUrl}/v1/migrations/export`,
-      {
-        method: "POST",
-        headers: {
-          Authorization: `Bearer ${accessToken}`,
-          "Content-Type": "application/json",
-        },
-        body: JSON.stringify({ description: "CLI backup" }),
-        signal: AbortSignal.timeout(exportTimeoutMs),
-      },
-    );
-
-    // Retry once with a fresh token on 401 — the cached token may be stale
-    // after a container restart that generated a new gateway signing key.
-    if (response.status === 401) {
-      let refreshedToken: string | null = null;
-      try {
-        const freshToken = await leaseGuardianToken(
-          entry.runtimeUrl,
-          entry.assistantId,
-          entry.guardianBootstrapSecret,
-        );
-        refreshedToken = freshToken.accessToken;
-      } catch {
-        // If token refresh fails, fall through to the !response.ok handler below
-      }
-      if (refreshedToken) {
-        accessToken = refreshedToken;
-        response = await loopbackSafeFetch(
-          `${entry.runtimeUrl}/v1/migrations/export`,
-          {
-            method: "POST",
-            headers: {
-              Authorization: `Bearer ${accessToken}`,
-              "Content-Type": "application/json",
-            },
-            body: JSON.stringify({ description: "CLI backup" }),
-            signal: AbortSignal.timeout(exportTimeoutMs),
-          },
-        );
-      }
-    }
-  } catch (err) {
-    if (err instanceof Error && err.name === "TimeoutError") {
-      console.error(
-        `Error: Export request timed out after ${exportTimeoutMs / 1000} seconds.`,
+      console.log(
+        "Cloud: create a backup through the cloud API using your cloud session.",
       );
-      process.exit(1);
+      console.log("Example: cadet backup my-assistant");
+      return;
     }
-    const msg = err instanceof Error ? err.message : String(err);
-    if (msg.includes("ECONNREFUSED") || msg.includes("fetch failed")) {
-      console.error(
-        `Error: Could not connect to assistant '${name}'. Is it running?`,
-      );
-      console.error(`Try: cadet wake ${name}`);
-      process.exit(1);
+    const name = args[0];
+    if (!name || name.startsWith("-"))
+      throw new Error("Usage: cadet backup <name>");
+    if (args.length > 1) throw new Error(`Unknown backup option: ${args[1]}`);
+    const entry = findAssistantByName(name);
+    if (!entry) throw new Error(`No assistant found with name '${name}'.`);
+    if (isCloudHome(entry.cloud)) {
+      const token = readCloudToken();
+      if (!token) throw new Error("Not logged in. Run 'cadet login' first.");
+      await createPlatformBackup(entry, token);
+      console.log("Cloud backup is ready.");
+      return;
     }
-    throw err;
-  }
-
-  if (!response.ok) {
-    const body = await response.text();
-    console.error(`Error: Export failed (${response.status}): ${body}`);
-    process.exit(1);
-  }
-
-  // Read the response body
-  const arrayBuffer = await response.arrayBuffer();
-  const data = new Uint8Array(arrayBuffer);
-
-  // Determine output path
-  const isoTimestamp = new Date().toISOString().replace(/[:.]/g, "-");
-  const outputPath =
-    outputArg || join(getBackupsDir(), `${name}-${isoTimestamp}.vbundle`);
-
-  // Ensure parent directory exists
-  mkdirSync(dirname(outputPath), { recursive: true });
-
-  // Write the archive to disk
-  writeFileSync(outputPath, data);
-
-  // Print success
-  const manifestSha = response.headers.get("X-Vbundle-Manifest-Sha256");
-  console.log(`Backup saved to ${outputPath}`);
-  console.log(`Size: ${formatSize(data.byteLength)}`);
-  if (manifestSha) {
-    console.log(`Manifest SHA-256: ${manifestSha}`);
-  }
-},
-  { description: "Export a backup of a running assistant" },
-);
-
-
-// ---------------------------------------------------------------------------
-// Platform-managed (cloud="cadet") backup over GCS.
-//
-// The runtime exports the bundle straight to a cloud-issued signed GCS
-// URL; the CLI then downloads from GCS to local disk. Bytes never flow
-// through Django. Same architectural shape as the cloud-source half of
-// `cadet teleport`. Output format and success log lines match mode 1
-// (runtime-direct local backup) so users see one consistent UX.
-//
-// Lifecycle: the GCS bucket has a 1-day TTL on `uploads/<org>/*` objects
-// (see `mycadet-platform/django/app/assistant/migration/views.py`
-// and `migration/services.py`). Backup is single-shot with no import to
-// trigger best-effort cleanup, so the bundle sits in GCS up to 24h before
-// TTL deletion. No explicit cleanup endpoint exists; relying on TTL is
-// intentional.
-// ---------------------------------------------------------------------------
-async function backupPlatform(
-  entry: AssistantEntry,
-  name: string,
-  outputArg?: string,
-): Promise<void> {
-  const cloudToken = readCloudToken();
-  if (!cloudToken) {
-    console.error(
-      "Not logged in. Run 'cadet login' first.",
-    );
-    process.exit(1);
-  }
-  // Pin upload, download, and runtime requests to the same platform instance
-  // the assistant lives on. Using `getCloudUrl()` instead would target
-  // whatever the lockfile / env-var resolves to, which may differ from
-  // `entry.runtimeUrl` for staging/dev assistants and end up signing URLs
-  // for the wrong GCS bucket. Mirrors the teleport bundleCloudUrl
-  // threading at `cli/src/commands/teleport.ts:1311-1312`.
-  const cloudUrl = entry.runtimeUrl;
-  // Track the working platform token across kickoff/poll/download so a
-  // 401-driven refresh during polling stays consistent through the final
-  // signed-download request.
-  let exportPlatformToken = cloudToken;
-
-  // Step 0 — Ask the source runtime which version it's running. The bundle
-  // is produced by the daemon (not the CLI), and the CLI version can drift
-  // from the daemon version, so the daemon's version is the authoritative
-  // value to record as the bundle's `min_runtime_version`. Stamping with
-  // `cliPkg.version` here would record an inaccurate compatibility band on
-  // the signed-URL request.
-  let runtimeIdentity: { version: string };
-  try {
-    runtimeIdentity = await localRuntimeIdentity(entry, exportPlatformToken);
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    console.error(
-      `Error: Could not fetch runtime identity from '${name}': ${msg}`,
-    );
-    process.exit(1);
-  }
-
-  // Step 1 — Request a signed upload URL.
-  const { url: uploadUrl, bundleKey } = await cloudRequestSignedUrl(
-    {
-      operation: "upload",
-      minRuntimeVersion: runtimeIdentity.version,
-      maxRuntimeVersion: null,
-    },
-    exportPlatformToken,
-    cloudUrl,
-  );
-
-  // Step 2 — Kick off runtime export-to-GCS through the cloud's
-  // wildcard runtime proxy. `localRuntimeExportToGcs` builds the
-  // `/v1/assistants/<id>/migrations/export-to-gcs` URL for cloud="cadet"
-  // and uses platform-token auth (no guardian-token bootstrap).
-  let jobId: string;
-  try {
-    ({ jobId } = await localRuntimeExportToGcs(entry, exportPlatformToken, {
-      uploadUrl,
-      description: "CLI backup",
-    }));
-  } catch (err) {
-    if (err instanceof MigrationInProgressError) {
-      console.error(
-        `Error: Another backup or teleport export is already in progress on '${entry.assistantId}' (job ${err.existingJobId}). Wait for it to finish, then re-run.`,
+    if (entry.cloud && !["local", "docker"].includes(entry.cloud)) {
+      throw new Error(
+        `Backup for '${entry.cloud}' must run on its host; only local, Docker and cloud backups are supported.`,
       );
-      process.exit(1);
     }
-    throw err;
-  }
-
-  console.log(`Export started (job ${jobId})...`);
-
-  // Step 3 — Poll the job through the wildcard proxy. The dedicated
-  // `/v1/migrations/jobs/{id}/` endpoint queries platform-side ImportJob
-  // records and would 404 on runtime-created job IDs.
-  const terminal = await pollJobUntilDone({
-    label: "platform export",
-    poll: () => localRuntimePollJobStatus(entry, exportPlatformToken, jobId),
-    refreshOn401: async () => {
-      const refreshed = readCloudToken();
-      if (!refreshed) {
-        throw new Error(
-          "Platform auth expired during export and no credential was found on disk. Run 'cadet login' and retry.",
-        );
-      }
-      exportPlatformToken = refreshed;
-    },
-  });
-
-  if (terminal.status === "failed") {
-    console.error(`Error: Export failed: ${terminal.error}`);
-    process.exit(1);
-  }
-
-  // Step 4 — Request a signed download URL for the same bundle and fetch
-  // it from GCS directly. No auth on signed URLs.
-  // Use `exportPlatformToken` (not the original `cloudToken`) so a
-  // poll-loop 401 refresh doesn't get clobbered here — otherwise a long
-  // export that recovered mid-poll via re-auth would still 401 on the
-  // download-URL request and abort an otherwise successful run.
-  //
-  // We deliberately do NOT send `targetRuntimeVersion` here. This flow
-  // saves the bundle to disk for offline storage; there is no target
-  // runtime to gate against, and the user can later restore the file
-  // into any compatible runtime. Sending the CLI's version would
-  // incorrectly block older CLIs from backing up newer assistants.
-  // The cloud treats `target_runtime_version` as optional and skips
-  // the version check when it's omitted.
-  const { url: bundleUrl } = await cloudRequestSignedUrl(
-    {
-      operation: "download",
-      bundleKey,
-    },
-    exportPlatformToken,
-    cloudUrl,
-  );
-
-  let downloadResponse: Response;
-  try {
-    downloadResponse = await fetch(bundleUrl);
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    console.error(`Error: Failed to fetch bundle from GCS: ${msg}`);
-    process.exit(1);
-  }
-  if (!downloadResponse.ok) {
-    const body = await downloadResponse.text().catch(() => "");
-    console.error(
-      `Error: Failed to fetch bundle from GCS (${downloadResponse.status}): ${body}`,
-    );
-    process.exit(1);
-  }
-
-  const arrayBuffer = await downloadResponse.arrayBuffer();
-  const data = new Uint8Array(arrayBuffer);
-
-  // Step 5 — Write to disk using the same path resolution mode 1 uses.
-  const isoTimestamp = new Date().toISOString().replace(/[:.]/g, "-");
-  const outputPath =
-    outputArg || join(getBackupsDir(), `${name}-${isoTimestamp}.vbundle`);
-  mkdirSync(dirname(outputPath), { recursive: true });
-  writeFileSync(outputPath, data);
-
-  // Step 6 — Print success. Manifest SHA is included only if the runtime
-  // surfaced it via the unified job result; the export-to-gcs runtime
-  // route does not set the legacy `X-Vbundle-Manifest-Sha256` response
-  // header.
-  console.log(`Backup saved to ${outputPath}`);
-  console.log(`Size: ${formatSize(data.byteLength)}`);
-  const manifestSha =
-    terminal.status === "complete" &&
-    terminal.result &&
-    typeof terminal.result === "object"
-      ? (terminal.result as Record<string, unknown>).manifest_sha256
-      : undefined;
-  if (typeof manifestSha === "string") {
-    console.log(`Manifest SHA-256: ${manifestSha}`);
-  }
-}
+    const path = join(
+      getBackupsDir(),
+      `${entry.assistantId}-${new Date().toISOString().replace(/[:.]/g, "-")}.tar.gz`,
+    );
+    await createRootBackup(entry, path);
+    console.log(`Backup saved to ${path}`);
+    console.log(`Size: ${formatSize((await stat(path)).size)}`);
+  },
+  {
+    description:
+      "Back up persistent local/Docker roots or create a cloud backup",
+  },
+);

package/src/commands/client.ts

@@ -831,9 +831,9 @@ async function handleLocalEndpoints(
   }
 
   // Pairing: the three-step device-code exchange that registers an assistant
-  // paired on another machine (guardian token + paired lockfile entry), the
-  // write counterpart of unpair. The exchange runs here rather than in the
-  // browser, so the device code and the credentials it buys never reach it.
+  // paired on another machine (guardian token + paired lockfile entry). The
+  // exchange runs here rather than in the browser, so the device code and the
+  // credentials it buys never reach it.
   if (
     PAIRING_START_PATTERN.test(pathname) ||
     PAIRING_POLL_PATTERN.test(pathname) ||

package/src/commands/completions.ts

@@ -12,12 +12,10 @@ const ASSISTANT_NAME_COMMANDS = new Set([
   "restart",
   "restore",
   "retire",
-  "rollback",
   "sleep",
   "teleport",
   "terminal",
   "tunnel",
-  "unpair",
   "upgrade",
   "use",
   "wake",