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

package/src/commands/tunnel.ts

@@ -20,9 +20,11 @@ import {
   getDefaultWorkspaceDir,
   isLocalContainerEntry,
   parseGatewayPortFromEntryUrls,
+  saveShellMode,
 } from "../lib/ingress-config.js";
 import {
   ensureTunnelEdge,
+  formatEdgeMode,
   getNginxVersion,
   type TunnelEdge,
 } from "../lib/nginx-ingress.js";
@@ -51,9 +53,10 @@ interface TunnelArgs {
   domain: string | null;
   clearDomain: boolean;
   foreground: boolean;
+  shell: "web" | "app" | null;
 }
 
-const FLAGS_WITH_VALUES = ["--provider", "--domain"] as const;
+const FLAGS_WITH_VALUES = ["--provider", "--domain", "--shell"] as const;
 
 function parseArgs(): TunnelArgs {
   const args = process.argv.slice(3);
@@ -61,6 +64,7 @@ function parseArgs(): TunnelArgs {
   let domain: string | null = null;
   let clearDomain = false;
   let foreground = false;
+  let shell: "web" | "app" | null = null;
 
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -70,9 +74,7 @@ function parseArgs(): TunnelArgs {
       );
       console.log("");
       console.log("Front a locally running assistant with an HTTPS tunnel.");
-      console.log(
-        "The tunnel URL is saved to the workspace config as the ingress base URL.",
-      );
+      console.log("The tunnel URL is saved to the workspace config as the ingress base URL.");
       console.log("");
       console.log(
         "How far that URL reaches depends on the provider; omit --provider for",
@@ -114,6 +116,19 @@ function parseArgs(): TunnelArgs {
       console.log(
         "                                tunnel without one. Cannot be combined with --domain.",
       );
+      console.log(
+        "  --shell <web|app>             Which client bundle the edge serves as the outer shell:",
+      );
+      console.log(
+        "                                web (default) serves the web SPA directly; app serves the",
+      );
+      console.log(
+        "                                app bundle as the outer shell and iframes the web UI from",
+      );
+      console.log(
+        "                                /web/assistant/. Saved to the workspace config so `cadet wake`",
+      );
+      console.log("                                restores it; changing it restarts the nginx edge.");
       console.log(
         `  --foreground                  Stream the tunnel's logs to this terminal. By default the tunnel`,
       );
@@ -191,6 +206,20 @@ function parseArgs(): TunnelArgs {
       i++;
     } else if (arg === "--clear-domain") {
       clearDomain = true;
+    } else if (arg === "--shell") {
+      const next = args[i + 1];
+      if (!next || next.startsWith("-")) {
+        console.error("Error: --shell requires a value: web or app.");
+        process.exit(1);
+      }
+      if (next !== "web" && next !== "app") {
+        console.error(
+          `Error: unknown shell '${next}'. Valid shells: web, app.`,
+        );
+        process.exit(1);
+      }
+      shell = next;
+      i++;
     } else if (arg === "--foreground") {
       foreground = true;
     } else if (arg.startsWith("-")) {
@@ -230,7 +259,7 @@ function parseArgs(): TunnelArgs {
     process.exit(1);
   }
 
-  return { assistantName, provider, domain, clearDomain, foreground };
+  return { assistantName, provider, domain, clearDomain, foreground, shell };
 }
 
 /** A tunnelable assistant plus the gateway port and workspace the edge fronts. */
@@ -456,7 +485,7 @@ export const tunnel = Object.assign(
       );
       return;
     }
-    const { assistantName, provider, domain, clearDomain, foreground } =
+    const { assistantName, provider, domain, clearDomain, foreground, shell } =
       parseArgs();
 
     if (!foreground) {
@@ -474,6 +503,15 @@ export const tunnel = Object.assign(
     const preserveIngressUrl =
       provider === "tailscale" && guardTailnetOnlyWebhookIngress(workspaceDir);
 
+    // Persist the shell mode like the reserved domain: parsed once, saved to
+    // the CLI lockfile beside the nginx edge record it configures, and read
+    // back by every later edge restore (wake/upgrade), so the choice outlives
+    // the command that made it.
+    if (shell) {
+      saveShellMode(shell);
+      console.log(`Shell mode saved: ${shell}.`);
+    }
+
     if (clearDomain) {
       clearReservedDomain();
       console.log("Cleared the saved reserved domain.");
@@ -514,7 +552,10 @@ export const tunnel = Object.assign(
     }
 
     console.log(
-      `${edge.started ? "Started" : "Reusing"} the nginx edge on 127.0.0.1:${edge.port}.`,
+      `${edge.started ? "Started" : "Reusing"} the nginx edge on 127.0.0.1:${edge.port} (${formatEdgeMode(
+        edge.includesWebApp,
+        edge.shellMode,
+      )}).`,
     );
 
     const baseTunnelOpts = {

package/src/commands/upgrade.ts

@@ -22,6 +22,7 @@ import {
   pullImage,
   startContainers,
   stopContainers,
+  sleepContainers,
 } from "../lib/docker";
 import {
   fetchLatestStableVersion,
@@ -67,6 +68,7 @@ import {
   stripVersionPrefix,
   versionsEqual,
 } from "../lib/version-compat.js";
+import { fetchCurrentVersion } from "../lib/http-client.js";
 import { loopbackSafeFetch } from "../lib/loopback-fetch.js";
 import {
   generateLocalSigningKey,
@@ -117,7 +119,7 @@ function parseArgs(): UpgradeArgs {
       console.log("Usage: cadet upgrade [<name>] [options]");
       console.log("");
       console.log("Upgrade an assistant to a newer version.");
-      console.log("To roll back to a previous version, use `cadet rollback`.");
+      console.log("To roll back to a previous version, use `cadet restore` with a backup.");
       console.log("");
       console.log("Arguments:");
       console.log(
@@ -294,7 +296,7 @@ async function upgradeDocker(
   }
 
   // Reject downgrades — `cadet upgrade` only handles forward version changes.
-  // Users should use `cadet rollback --version <version>` for downgrades.
+  // Downgrades require a versioned backup restore.
   if (!currentVersion && versionTag) {
     console.warn(
       "⚠️  Could not determine current version from health endpoint — skipping version-direction check.\n",
@@ -303,7 +305,7 @@ async function upgradeDocker(
   if (currentVersion && versionTag) {
     const cmp = compareVersions(versionTag, currentVersion);
     if (cmp !== null && cmp < 0) {
-      const msg = `Cannot upgrade to an older version (${versionTag} < ${currentVersion}). Use \`cadet rollback --version ${versionTag}\` instead.`;
+      const msg = `Cannot upgrade to an older version (${versionTag} < ${currentVersion}). Use \`cadet restore --from <backup-path> --version ${versionTag}\` instead.`;
       console.error(msg);
       emitCliError("VERSION_DIRECTION", msg);
       process.exit(1);
@@ -345,22 +347,6 @@ async function upgradeDocker(
     );
   }
 
-  // Persist rollback state to lockfile BEFORE any destructive changes.
-  // This enables the `cadet rollback` command to restore the previous version.
-  if (entry.containerInfo) {
-    const rollbackEntry: AssistantEntry = {
-      ...entry,
-      previousContainerInfo: { ...entry.containerInfo },
-      previousVersion: currentVersion,
-      previousDbMigrationVersion: preMigrationState.dbVersion,
-      previousWorkspaceMigrationId: preMigrationState.lastWorkspaceMigrationId,
-    };
-    saveAssistantEntry(rollbackEntry);
-    if (currentVersion) {
-      console.log(`   Saved rollback state: ${currentVersion}\n`);
-    }
-  }
-
   // Record version transition start in workspace git history
   await commitWorkspaceViaGateway(
     entry.runtimeUrl,
@@ -440,7 +426,7 @@ async function upgradeDocker(
   const assistantPort =
     entry.containerInfo?.assistantPort ?? ASSISTANT_INTERNAL_PORT;
 
-  // Create pre-upgrade backup (best-effort, daemon must be running)
+  // Capture complete persistent roots before replacing any services.
   await broadcastUpgradeEvent(
     entry.runtimeUrl,
     entry.assistantId,
@@ -456,20 +442,7 @@ async function upgradeDocker(
     // Clean up old pre-upgrade backups, keep last 3
     pruneOldBackups(entry.assistantId, 3);
   } else {
-    console.warn("⚠️  Pre-upgrade backup failed, continuing with upgrade\n");
-  }
-
-  // Persist the backup path so `cadet rollback` can restore the exact backup
-  // created for this upgrade attempt — never a stale backup from a prior cycle.
-  // Re-read the entry to pick up the rollback state saved earlier.
-  {
-    const current = findAssistantByName(entry.assistantId);
-    if (current) {
-      saveAssistantEntry({
-        ...current,
-        preUpgradeBackupPath: backupPath ?? undefined,
-      });
-    }
+    throw new Error("Pre-upgrade root backup failed; upgrade aborted before replacing services.");
   }
 
   await broadcastUpgradeEvent(
@@ -479,6 +452,7 @@ async function upgradeDocker(
   );
 
   console.log("🛑 Stopping existing containers...");
+  await sleepContainers(res);
   await stopContainers(res);
   console.log("✅ Containers stopped\n");
 
@@ -512,11 +486,6 @@ async function upgradeDocker(
         cesImage: imageTags["credential-executor"],
         assistantPort,
       },
-      previousContainerInfo: entry.containerInfo,
-      previousDbMigrationVersion: preMigrationState.dbVersion,
-      previousWorkspaceMigrationId: preMigrationState.lastWorkspaceMigrationId,
-      // Preserve the backup path so `cadet rollback` can restore it later
-      preUpgradeBackupPath: backupPath ?? undefined,
     };
     saveAssistantEntry(updatedEntry);
     // Refresh the host-served web bundle before clients reload on completion.
@@ -586,6 +555,7 @@ async function upgradeDocker(
           );
         }
 
+        await sleepContainers(res);
         await stopContainers(res);
 
         await startContainers(
@@ -652,14 +622,12 @@ async function upgradeDocker(
               entry.runtimeUrl,
               entry.assistantId,
               backupPath,
-              { kind: "docker", assistantId: entry.assistantId },
+              {},
             );
             if (restored) {
               console.log("   ✅ Data restored successfully\n");
             } else {
-              console.warn(
-                "   ⚠️  Data restore failed (rollback continues without data restoration)\n",
-              );
+              throw new Error(`Root restore failed; rollback recovery is incomplete. Backup: ${backupPath}`);
             }
           } else {
             console.log(
@@ -683,11 +651,6 @@ async function upgradeDocker(
                 previousImageRefs["credential-executor"],
               assistantPort,
             },
-            previousContainerInfo: undefined,
-            previousDbMigrationVersion: undefined,
-            previousWorkspaceMigrationId: undefined,
-            // Clear the backup path — the upgrade that created it just failed
-            preUpgradeBackupPath: undefined,
           };
           saveAssistantEntry(rolledBackEntry);
 
@@ -815,40 +778,6 @@ async function ensureGuardianTokenAfterLocalUpgrade(
   }
 }
 
-async function fetchLocalUpgradeState(
-  entry: AssistantEntry,
-  adminUrl: string,
-): Promise<{
-  currentVersion?: string;
-  preMigrationState: {
-    dbVersion?: number;
-    lastWorkspaceMigrationId?: string;
-  };
-}> {
-  try {
-    const healthResp = await loopbackSafeFetch(
-      `${adminUrl}/healthz?include=migrations`,
-      {
-        signal: AbortSignal.timeout(5000),
-      },
-    );
-    if (healthResp.ok) {
-      const health = (await healthResp.json()) as {
-        version?: string;
-        migrations?: { dbVersion?: number; lastWorkspaceMigrationId?: string };
-      };
-      return {
-        currentVersion: health.version,
-        preMigrationState: health.migrations ?? {},
-      };
-    }
-  } catch {
-    // Best-effort — sleeping assistants and unhealthy gateways can still be restarted.
-  }
-
-  return { preMigrationState: {} };
-}
-
 async function upgradeLocal(
   entry: AssistantEntry,
   version: string | null,
@@ -861,6 +790,7 @@ async function upgradeLocal(
     process.exit(1);
   }
 
+  const originalResources = { ...entry.resources };
   const signingKey = resolveExistingLocalSigningKey(entry.resources);
   if (entry.resources.signingKey !== signingKey) {
     entry.resources.signingKey = signingKey;
@@ -869,10 +799,7 @@ async function upgradeLocal(
 
   const targetVersion = await targetVersionFromCli(version);
   const adminUrl = localAdminUrl(entry);
-  const { currentVersion, preMigrationState } = await fetchLocalUpgradeState(
-    entry,
-    adminUrl,
-  );
+  const currentVersion = await fetchCurrentVersion(adminUrl);
 
   if (!currentVersion && targetVersion) {
     console.warn(
@@ -882,7 +809,7 @@ async function upgradeLocal(
   if (currentVersion && targetVersion) {
     const cmp = compareVersions(targetVersion, currentVersion);
     if (cmp !== null && cmp < 0) {
-      const msg = `Cannot upgrade to an older version (${targetVersion} < ${currentVersion}). Use \`cadet rollback --version ${targetVersion}\` instead.`;
+      const msg = `Cannot upgrade to an older version (${targetVersion} < ${currentVersion}). Use \`cadet restore --from <backup-path> --version ${targetVersion}\` instead.`;
       console.error(msg);
       emitCliError("VERSION_DIRECTION", msg);
       process.exit(1);
@@ -938,7 +865,7 @@ async function upgradeLocal(
     console.log(`   Backup saved: ${backupPath}\n`);
     pruneOldBackups(entry.assistantId, 3);
   } else {
-    console.warn("⚠️  Pre-upgrade backup failed, continuing with upgrade\n");
+    throw new Error("Pre-upgrade root backup failed; upgrade aborted before replacing services.");
   }
 
   let bootstrapSecret = entry.guardianBootstrapSecret;
@@ -949,20 +876,8 @@ async function upgradeLocal(
     entryChanged = true;
   }
 
-  if (
-    entryChanged ||
-    backupPath ||
-    currentVersion ||
-    preMigrationState.dbVersion !== undefined ||
-    preMigrationState.lastWorkspaceMigrationId !== undefined
-  ) {
-    saveAssistantEntry({
-      ...entry,
-      previousVersion: currentVersion,
-      previousDbMigrationVersion: preMigrationState.dbVersion,
-      previousWorkspaceMigrationId: preMigrationState.lastWorkspaceMigrationId,
-      preUpgradeBackupPath: backupPath ?? undefined,
-    });
+  if (entryChanged) {
+    saveAssistantEntry(entry);
   }
 
   await broadcastUpgradeEvent(
@@ -982,64 +897,69 @@ async function upgradeLocal(
     runtimeVersion: runtimeInstall.version,
     runtimeInstallDir: runtimeInstall.installDir,
   };
-  saveAssistantEntry({
-    ...entry,
-    previousVersion: currentVersion,
-    previousDbMigrationVersion: preMigrationState.dbVersion,
-    previousWorkspaceMigrationId: preMigrationState.lastWorkspaceMigrationId,
-    preUpgradeBackupPath: backupPath ?? undefined,
-  });
+  saveAssistantEntry(entry);
   console.log(`   Runtime installed: ${runtimeInstall.installDir}\n`);
 
-  console.log("🛑 Stopping local assistant processes...");
-  await stopLocalProcesses(entry.resources);
-  console.log("✅ Local assistant processes stopped\n");
-
-  console.log("🚀 Starting upgraded local assistant...");
-  const previousAppVersion = process.env.APP_VERSION;
-  process.env.APP_VERSION = stripVersionPrefix(targetVersion);
   try {
-    // Bring CES, daemon, and gateway up in parallel, the way the Docker
-    // topology starts its sibling processes together. startCes always
-    // launches the CES sibling.
-    await Promise.all([
-      startCes(false, entry.resources),
-      startLocalDaemon(false, entry.resources, { signingKey }),
-      startGateway(false, entry.resources, { signingKey, bootstrapSecret }),
-    ]);
-  } finally {
-    if (previousAppVersion === undefined) {
-      delete process.env.APP_VERSION;
-    } else {
-      process.env.APP_VERSION = previousAppVersion;
-    }
-  }
-  await ensureGuardianTokenAfterLocalUpgrade(
-    entry,
-    entry.resources.gatewayPort,
-    bootstrapSecret,
-  );
-  console.log("✅ Local assistant processes started\n");
+    console.log("🛑 Stopping local assistant processes...");
+    await stopLocalProcesses(entry.resources);
+    console.log("✅ Local assistant processes stopped\n");
 
-  const workspaceDir = join(entry.resources.instanceDir, "workspace");
-  await restoreTunnelEdgeAndAutoTunnel(
-    entry.assistantId,
-    entry.resources.gatewayPort,
-    workspaceDir,
-  );
+    console.log("🚀 Starting upgraded local assistant...");
+    const previousAppVersion = process.env.APP_VERSION;
+    process.env.APP_VERSION = stripVersionPrefix(targetVersion);
+    try {
+      // Bring CES, daemon, and gateway up in parallel, the way the Docker
+      // topology starts its sibling processes together. startCes always
+      // launches the CES sibling.
+      await Promise.all([
+        startCes(false, entry.resources),
+        startLocalDaemon(false, entry.resources, { signingKey }),
+        startGateway(false, entry.resources, { signingKey, bootstrapSecret }),
+      ]);
+    } finally {
+      if (previousAppVersion === undefined) {
+        delete process.env.APP_VERSION;
+      } else {
+        process.env.APP_VERSION = previousAppVersion;
+      }
+    }
+    await ensureGuardianTokenAfterLocalUpgrade(
+      entry,
+      entry.resources.gatewayPort,
+      bootstrapSecret,
+    );
+    console.log("✅ Local assistant processes started\n");
 
-  console.log("Waiting for assistant to become ready...");
-  const ready = await waitForReady(adminUrl);
-  if (!ready) {
-    await broadcastUpgradeEvent(
-      adminUrl,
+    const workspaceDir = join(entry.resources.instanceDir, "workspace");
+    await restoreTunnelEdgeAndAutoTunnel(
       entry.assistantId,
-      buildCompleteEvent(currentVersion ?? "unknown", false),
+      entry.resources.gatewayPort,
+      workspaceDir,
     );
-    const msg = `Upgrade to ${targetVersion} failed: local assistant did not become ready.`;
-    console.error(`\n❌ ${msg}`);
-    emitCliError("READINESS_TIMEOUT", msg);
-    process.exit(1);
+
+    console.log("Waiting for assistant to become ready...");
+    const ready = await waitForReady(adminUrl);
+    if (!ready) {
+      await broadcastUpgradeEvent(
+        adminUrl,
+        entry.assistantId,
+        buildCompleteEvent(currentVersion ?? "unknown", false),
+      );
+      const msg = `Upgrade to ${targetVersion} failed: local assistant did not become ready.`;
+      console.error(`\n❌ ${msg}`);
+      throw new Error(msg);
+    }
+  } catch (error) {
+    console.error("Local upgrade failed; restoring the previous runtime and service roots...");
+    await stopLocalProcesses(entry.resources);
+    entry.resources = originalResources;
+    saveAssistantEntry(entry);
+    const restored = await restoreBackup(adminUrl, entry.assistantId, backupPath, { resume: false });
+    if (!restored) throw new Error(`Local recovery failed; services remain stopped. Backup: ${backupPath}`, { cause: error });
+    await Promise.all([startCes(false, entry.resources), startLocalDaemon(false, entry.resources, { signingKey }), startGateway(false, entry.resources, { signingKey, bootstrapSecret })]);
+    if (!await waitForReady(adminUrl)) throw new Error(`Previous local runtime did not recover. Backup: ${backupPath}`, { cause: error });
+    throw error;
   }
 
   await broadcastUpgradeEvent(
@@ -1228,7 +1148,7 @@ async function upgradePlatform(
   }
 
   if (resolution.isDowngrade && resolution.target && currentVersion) {
-    const msg = `Cannot upgrade to an older version (${resolution.target} < ${currentVersion}). Use \`cadet rollback --version ${resolution.target}\` instead.`;
+    const msg = `Cannot upgrade to an older version (${resolution.target} < ${currentVersion}). Use \`cadet restore --from <backup-path> --version ${resolution.target}\` instead.`;
     console.error(msg);
     emitCliError("VERSION_DIRECTION", msg);
     process.exit(1);
@@ -1389,6 +1309,8 @@ async function upgradePrepare(
     description: `Pre-upgrade snapshot before ${currentVersion} → ${targetVersion}`,
   });
 
+  if (!backupPath) throw new Error("Pre-upgrade root backup failed; update preparation aborted.");
+
   // 5. Prune old backups (keep 3)
   if (backupPath) {
     pruneOldBackups(entry.assistantId, 3);
@@ -1460,11 +1382,11 @@ async function resolveLatestStableTag(): Promise<string> {
   const latestVersion = await fetchLatestStableVersion();
   if (!latestVersion) {
     console.error(
-      "Error: Could not determine the latest stable release from the Cadet Cloud API.",
+      "Error: Could not determine the latest stable release from Cadet Cloud or GitHub Releases.",
     );
     emitCliError(
       "UNKNOWN",
-      "Could not determine the latest stable release from the cloud API",
+      "Could not determine the latest stable release from Cadet Cloud or GitHub Releases",
     );
     process.exit(1);
   }

package/src/commands/wake.ts

@@ -201,7 +201,7 @@ class WakeExit extends Error {}
  * refusals so the caller decides between exiting (single path) and
  * continuing to the next entry (`--all`).
  */
-async function wakeAssistant(
+export async function wakeAssistant(
   entry: AssistantEntry,
   opts: WakeAssistantOptions,
 ): Promise<void> {

package/src/index.ts

@@ -31,7 +31,6 @@ import { ps } from "./commands/ps";
 import { restore } from "./commands/restore";
 import { retire } from "./commands/retire";
 import { restart } from "./commands/restart";
-import { rollback } from "./commands/rollback";
 import { setup } from "./commands/setup";
 import { sleep } from "./commands/sleep";
 import { debug } from "./commands/debug";
@@ -39,7 +38,6 @@ import { teleport } from "./commands/teleport";
 import { terminal } from "./commands/terminal";
 import { tunnel } from "./commands/tunnel";
 import { uninstall } from "./commands/uninstall";
-import { unpair } from "./commands/unpair";
 import { upgrade } from "./commands/upgrade";
 import { use } from "./commands/use";
 import { voice } from "./commands/voice";
@@ -73,14 +71,12 @@ const commands = {
   restore,
   retire,
   restart,
-  rollback,
   setup,
   sleep,
   teleport,
   terminal,
   tunnel,
   uninstall,
-  unpair,
   upgrade,
   use,
   voice,

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();
+});