@mycadet/cli 0.12.10 → 0.13.0

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
@@ -305,7 +307,6 @@ export interface HatchDockerParams {
    * also enables hot-reload.
    */
   sourcePath?: string | null;
-  analyze?: boolean;
   /**
    * Name of an existing container whose network namespace the assistant,
    * gateway, and credential-executor join (`--network=container:<name>`),
@@ -813,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;
@@ -833,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);
   }
 }
 
@@ -850,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);
@@ -1631,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.
@@ -1670,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,
@@ -1689,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,
@@ -1719,7 +1755,6 @@ export async function hatchDocker(params: HatchDockerParams): Promise<void> {
         logFd,
         runtimeUrl,
         containersUpAt,
-        analyze: params.analyze ?? false,
       });
 
     if (!ready && !(watch && repoRoot)) {
@@ -1828,7 +1863,6 @@ async function waitForGatewayAndLease(opts: {
   logFd: number | "ignore";
   runtimeUrl: string;
   containersUpAt: number;
-  analyze: boolean;
 }): Promise<{
   ready: boolean;
   guardianAccessToken?: string;
@@ -1844,7 +1878,6 @@ async function waitForGatewayAndLease(opts: {
     logFd,
     runtimeUrl,
     containersUpAt,
-    analyze,
   } = opts;
 
   const log = (msg: string): void => {
@@ -1964,14 +1997,12 @@ async function waitForGatewayAndLease(opts: {
   const containersUpToReadyMs = readyAt - start;
   const elapsedSec = (containersUpToReadyMs / 1000).toFixed(1);
   log(`Assistant ready after ${elapsedSec}s`);
-  if (analyze) {
-    console.info(
-      `[cadet-hatch-timing] ${JSON.stringify({
-        containers_up_to_ready_ms: containersUpToReadyMs,
-        instance: instanceName,
-      })}`,
-    );
-  }
+  console.info(
+    `[cadet-hatch-timing] ${JSON.stringify({
+      containers_up_to_ready_ms: containersUpToReadyMs,
+      instance: instanceName,
+    })}`,
+  );
 
   // Lease guardian token. The /readyz check confirms both gateway and
   // assistant are reachable. Retry with backoff in case there is a brief

package/src/lib/ensure-binary.ts

@@ -31,6 +31,8 @@ export interface EnsureBinaryOptions {
   runInstall?: (argv: string[]) => boolean;
   /** Confirm the install. Default: promptLine "[Y/n]" on Enter-as-yes. */
   confirmInstall?: () => Promise<boolean>;
+  platform?: NodeJS.Platform;
+  confirmHomebrewInstall?: () => Promise<boolean>;
   streams?: {
     input?: NodeJS.ReadStream | Readable;
     output?: NodeJS.WriteStream | Writable;
@@ -69,9 +71,60 @@ export async function ensureBinaryInstalled(
   }
 
   const pmAvailable = opts.pmAvailable ?? probePackageManager;
-  const argv = Object.entries(opts.packages).find(([pm]) =>
-    pmAvailable(pm),
-  )?.[1];
+  let argv = Object.entries(opts.packages).find(([pm]) => pmAvailable(pm))?.[1];
+  if (
+    !argv &&
+    (opts.platform ?? process.platform) === "darwin" &&
+    opts.packages.brew
+  ) {
+    const brew = ["/opt/homebrew/bin/brew", "/usr/local/bin/brew"].find(
+      pmAvailable,
+    );
+    if (brew) {
+      const prefix = brew.slice(0, -"/bin/brew".length);
+      process.env.PATH = `${prefix}/bin:${prefix}/sbin:${process.env.PATH ?? ""}`;
+      argv = [brew, ...opts.packages.brew.slice(1)];
+    }
+  }
+  if (
+    !argv &&
+    (opts.platform ?? process.platform) === "darwin" &&
+    opts.packages.brew
+  ) {
+    output.write(
+      "Homebrew is required to install this dependency, but it isn't installed.\n",
+    );
+    const confirmHomebrew =
+      opts.confirmHomebrewInstall ?? defaultConfirm(opts, "Homebrew");
+    let approved = false;
+    try {
+      approved = await confirmHomebrew();
+    } catch {
+      /* No interactive approval. */
+    }
+    if (approved) {
+      const bootstrap = [
+        "/bin/bash",
+        "-c",
+        '/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/7a3f48c7e498d7df3237fd41c30f4d492857edf4/install.sh)"',
+      ];
+      const installed = opts.runInstall
+        ? opts.runInstall(bootstrap)
+        : runInstallArgv(bootstrap);
+      const brew = installed
+        ? ["brew", "/opt/homebrew/bin/brew", "/usr/local/bin/brew"].find(
+            pmAvailable,
+          )
+        : undefined;
+      if (brew) {
+        const prefix =
+          brew === "brew" ? "" : brew.slice(0, -"/bin/brew".length);
+        if (prefix)
+          process.env.PATH = `${prefix}/bin:${prefix}/sbin:${process.env.PATH ?? ""}`;
+        argv = [brew, ...opts.packages.brew.slice(1)];
+      }
+    }
+  }
   if (!argv) {
     output.write(`⚠ No supported package manager found. ${opts.manualHint}\n`);
     return null;
@@ -90,7 +143,10 @@ export async function ensureBinaryInstalled(
 }
 
 /** Default confirm: visible prompt, Enter = yes, non-TTY throws. */
-function defaultConfirm(opts: EnsureBinaryOptions): () => Promise<boolean> {
+function defaultConfirm(
+  opts: EnsureBinaryOptions,
+  binary = opts.binary,
+): () => Promise<boolean> {
   return async () => {
     const input = opts.streams?.input ?? process.stdin;
     const output = opts.streams?.output ?? process.stdout;
@@ -99,7 +155,7 @@ function defaultConfirm(opts: EnsureBinaryOptions): () => Promise<boolean> {
       throw new Error("Install confirm requires an interactive terminal.");
     }
     const answer = (
-      await readLineText(`Install ${opts.binary} now? [Y/n] `, {
+      await readLineText(`Install ${binary} now? [Y/n] `, {
         input,
         output,
       })
@@ -114,7 +170,10 @@ function defaultConfirm(opts: EnsureBinaryOptions): () => Promise<boolean> {
 function runInstallArgv(argv: string[]): boolean {
   const [command, ...args] = argv;
   if (!command) return false;
-  const result = spawnSync(command, args, { stdio: "inherit" });
+  const result = spawnSync(command, args, {
+    stdio: "inherit",
+    windowsHide: true,
+  });
   return !result.error && result.status === 0;
 }
 

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";

package/src/lib/guardian-token.ts

@@ -7,7 +7,6 @@ import {
   mkdirSync,
   openSync,
   readFileSync,
-  rmdirSync,
   statSync,
   unlinkSync,
   writeFileSync,
@@ -79,27 +78,6 @@ function getGuardianTokenPath(assistantId: string): string {
   return guardianTokenPath(resolveConfigDir(process.env), assistantId);
 }
 
-/**
- * Best-effort removal of an assistant's stored guardian token (used by
- * `cadet unpair` to forget a paired connection). Never throws if the token
- * file or its per-assistant directory is already absent.
- */
-export function deleteGuardianToken(assistantId: string): void {
-  const tokenPath = getGuardianTokenPath(assistantId);
-  try {
-    unlinkSync(tokenPath);
-  } catch {
-    /* already gone */
-  }
-  // Clean up the now-empty per-assistant directory; rmdir throws if it still
-  // holds other files, in which case we leave it.
-  try {
-    rmdirSync(dirname(tokenPath));
-  } catch {
-    /* not empty or absent */
-  }
-}
-
 function getPersistedDeviceIdPath(): string {
   return join(getConfigDir(getCurrentEnvironment()), "device-id");
 }
@@ -454,7 +432,7 @@ export async function refreshGuardianTokenResult(
     return {
       ok: false,
       status: 401,
-      error: "Guardian token expired. Re-run `cadet hatch` or `cadet wake`.",
+      error: "Guardian refresh token expired",
     };
   }
 

package/src/lib/hatch-local.ts

@@ -1,3 +1,4 @@
+import { persistRootSigningKey } from "./root-signing-key.js";
 import {
   existsSync,
   lstatSync,
@@ -52,7 +53,6 @@ import {
 import { logHatchNextSteps } from "./hatch-next-steps.js";
 import { printInstanceDetails } from "./instance-details.js";
 import { checkProviderApiKey } from "./api-key-check.js";
-import { loopbackSafeFetch } from "./loopback-fetch.js";
 import {
   describeLoginError,
   ensureCloudLoginInteractive,
@@ -156,13 +156,13 @@ export interface HatchLocalParams {
   name?: string | null;
   /** Build from a local source tree and hot-reload on change. */
   watch?: boolean;
-  /** Stay attached after hatch and poll the gateway until it stops. */
-  keepAlive?: boolean;
   /** Hatch-time config values (key → value). */
   configValues?: Record<string, string>;
   /** Extra env vars forwarded into the assistant process. */
   flagEnvVars?: Record<string, string>;
   setupProviderCredentials?: boolean;
+  /** Whole-installation state installed before the first service startup. */
+  initialArchive?: string;
   /**
    * Show the per-service startup logs (assistant, credential executor,
    * gateway) and the extended next steps. Off by default — the happy path
@@ -192,13 +192,7 @@ export interface HatchLocalResult {
 export async function hatchLocal(
   params: HatchLocalParams = {},
 ): Promise<HatchLocalResult> {
-  const {
-    name,
-    watch = false,
-    keepAlive = false,
-    configValues = {},
-    flagEnvVars = {},
-  } = params;
+  const { name, watch = false, configValues = {}, flagEnvVars = {} } = params;
   const reporter = params.reporter ?? consoleLifecycleReporter;
   const verbose = params.verbose ?? false;
   const setupProviderCredentials = params.setupProviderCredentials !== false;
@@ -300,7 +294,20 @@ export async function hatchLocal(
       const defaultWorkspaceConfigPath = writeInitialConfig(hatchConfigValues);
 
       reporter.progress(3, 6, "Starting assistant...");
-      const signingKey = generateLocalSigningKey();
+      const signingKey = params.initialArchive
+        ? await (
+            await import("./root-backup.js")
+          ).initializeRootArchive(
+            {
+              assistantId: instanceName,
+              cloud: "local",
+              runtimeUrl: "",
+              resources,
+            },
+            params.initialArchive,
+          )
+        : generateLocalSigningKey();
+      persistRootSigningKey(resources.instanceDir, signingKey);
       const bootstrapSecret = generateLocalSigningKey();
       let runtimeUrl = `http://127.0.0.1:${resources.gatewayPort}`;
       try {
@@ -454,46 +461,5 @@ export async function hatchLocal(
     guardianAccessToken,
   };
 
-  if (keepAlive) {
-    const healthUrl = `http://127.0.0.1:${resources.gatewayPort}/healthz`;
-    const healthTarget = "Gateway";
-    const POLL_INTERVAL_MS = 5000;
-    const MAX_FAILURES = 3;
-    let consecutiveFailures = 0;
-
-    const shutdown = async (): Promise<void> => {
-      reporter.log("\nShutting down local processes...");
-      await stopLocalProcesses(resources);
-      process.exit(0);
-    };
-
-    process.on("SIGTERM", () => void shutdown());
-    process.on("SIGINT", () => void shutdown());
-
-    // Poll the health endpoint until it stops responding.
-    while (true) {
-      await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
-      try {
-        const res = await loopbackSafeFetch(healthUrl, {
-          signal: AbortSignal.timeout(3000),
-        });
-        if (res.ok) {
-          consecutiveFailures = 0;
-        } else {
-          consecutiveFailures++;
-        }
-      } catch {
-        consecutiveFailures++;
-      }
-      if (consecutiveFailures >= MAX_FAILURES) {
-        reporter.log(
-          `\n⚠️  ${healthTarget} stopped responding — shutting down.`,
-        );
-        await stopLocalProcesses(resources);
-        process.exit(1);
-      }
-    }
-  }
-
   return result;
 }

package/src/lib/hatch-next-steps.ts

@@ -1,8 +1,21 @@
+import { getCurrentEnvironment } from "./environments/resolve.js";
+
+function cliCommand(): string {
+  // Production keeps the bare `cadet` binary; every non-production
+  // environment installs as `cadet-<env>` (the same rule as the config and
+  // state dirs — see environments/paths.ts).
+  const env = getCurrentEnvironment();
+  return env.name === "production" ? "cadet" : `cadet-${env.name}`;
+}
+
 export function logHatchNextSteps(log: (message: string) => void): void {
+  const command = cliCommand();
   log("Next steps:");
-  log("  - Run `cadet client` to interact with your cadet via the terminal");
   log(
-    "  - Run `cadet tunnel` to make your cadet publicly accessible and interact with it via the browser",
+    `  - Run \`${command} client\` to interact with your cadet via the terminal`,
+  );
+  log(
+    `  - Run \`${command} tunnel\` to make your cadet publicly accessible and interact with it via the browser`,
   );
   log("");
 }