@mycadet/cli 0.12.7 → 0.12.9-dev.202610131452.9acab64

package/src/lib/__tests__/docker.test.ts

@@ -8,6 +8,7 @@ import {
   collectWatchTargets,
   dockerResourceNames,
   ensureDockerDaemonRunning,
+  pullImage,
   resolveAvatarDevicePath,
   resolveDockerHatchMode,
   resolveDockerProviderCredentialSetupAction,
@@ -158,6 +159,38 @@ describe("resolveDockerProviderCredentialSetupAction", () => {
       }),
     ).toBe("skip");
   });
+
+  test("detached hatch with a pre-collected key configures instead of deferring", () => {
+    expect(
+      resolveDockerProviderCredentialSetupAction({
+        provider: "fireworks",
+        guardianAccessToken: "guardian-token",
+        detached: true,
+        precollectedKey: "fw-key-123",
+      }),
+    ).toBe("configure");
+  });
+
+  test("pre-collected key without a guardian token reports missing-token (no silent defer)", () => {
+    expect(
+      resolveDockerProviderCredentialSetupAction({
+        provider: "fireworks",
+        detached: true,
+        precollectedKey: "fw-key-123",
+      }),
+    ).toBe("missing-token");
+  });
+
+  test("an explicitly skipped key still counts as answered — configure runs and reports the gap", () => {
+    expect(
+      resolveDockerProviderCredentialSetupAction({
+        provider: "fireworks",
+        guardianAccessToken: "guardian-token",
+        detached: true,
+        precollectedKey: "",
+      }),
+    ).toBe("configure");
+  });
 });
 
 describe("buildServiceRunArgs — gateway", () => {
@@ -384,25 +417,48 @@ describe("collectWatchTargets", () => {
 });
 
 /**
- * Build a fake `exec` that records calls and fails the probes named in `fail`.
- * Injected into `ensureDockerDaemonRunning` so these cases need no `mock.module`
- * (which is process-global and would leak across the CLI's single-process test
- * run) and no real Docker/Colima subprocesses.
+ * Build a STATEFUL fake `exec` modeling the Docker daemon + Colima interplay:
+ * `docker info` succeeds only while `daemonUp`; a `colima start` heals the
+ * daemon (unless the fake is told to model the zombie state, where Colima's
+ * state file says "already running, ignoring" but the daemon stays dead —
+ * only the stop → start cycle recovers). Injected into
+ * `ensureDockerDaemonRunning` so these cases need no `mock.module` (which is
+ * process-global and would leak across the CLI's single-process test run) and
+ * no real Docker/Colima subprocesses.
  */
-function fakeExec(fail: { dockerInfo?: boolean; colimaStatus?: boolean }) {
+function fakeExec(
+  opts: {
+    /** Daemon already reachable when the test starts. */
+    daemonUpAtStart?: boolean;
+    /** `colima start` exits nonzero instead of healing. */
+    startFails?: boolean;
+    /** First `colima start` is a zombie no-op that does NOT heal the daemon. */
+    zombieFirstStart?: boolean;
+  } = {},
+) {
   const calls: Array<{ cmd: string; args: string[] }> = [];
+  let daemonUp = opts.daemonUpAtStart ?? false;
+  let starts = 0;
   const exec = async (cmd: string, args: string[] = []): Promise<void> => {
     calls.push({ cmd, args });
-    if (cmd === "docker" && args[0] === "info" && fail.dockerInfo) {
-      throw new Error("Cannot connect to the Docker daemon");
+    if (cmd === "docker" && args[0] === "info") {
+      if (!daemonUp) throw new Error("Cannot connect to the Docker daemon");
+      return;
+    }
+    if (cmd === "colima" && args[0] === "start") {
+      starts++;
+      if (opts.startFails) throw new Error("colima start exited 1");
+      if (!opts.zombieFirstStart || starts > 1) daemonUp = true;
+      return;
     }
-    if (cmd === "colima" && args[0] === "status" && fail.colimaStatus) {
-      throw new Error("colima is not running");
+    if (cmd === "colima" && args[0] === "stop") {
+      daemonUp = false;
+      return;
     }
   };
   const ran = (cmd: string, sub: string): boolean =>
     calls.some((c) => c.cmd === cmd && c.args[0] === sub);
-  return { exec: exec as typeof import("../step-runner.js").exec, ran };
+  return { exec, ran };
 }
 
 describe("ensureDockerDaemonRunning", () => {
@@ -410,30 +466,122 @@ describe("ensureDockerDaemonRunning", () => {
   // Colima, because that switches the active `docker context` and points
   // `docker start` at a VM that never held the instance's containers.
   test("reuses an already-reachable daemon (e.g. Docker Desktop) and never touches Colima", async () => {
-    const { exec, ran } = fakeExec({ dockerInfo: false });
+    const { exec, ran } = fakeExec({ daemonUpAtStart: true });
 
     await ensureDockerDaemonRunning(exec);
 
     expect(ran("docker", "info")).toBe(true);
-    expect(ran("colima", "status")).toBe(false);
     expect(ran("colima", "start")).toBe(false);
+    expect(ran("colima", "stop")).toBe(false);
   });
 
-  test("starts Colima only when no daemon is reachable", async () => {
-    const { exec, ran } = fakeExec({ dockerInfo: true, colimaStatus: true });
+  test("starts Colima when no daemon is reachable and confirms the daemon answered", async () => {
+    const { exec, ran } = fakeExec();
 
-    await ensureDockerDaemonRunning(exec);
+    await ensureDockerDaemonRunning(exec, { settleTimeoutMs: 0 });
 
     expect(ran("docker", "info")).toBe(true);
     expect(ran("colima", "start")).toBe(true);
+    expect(ran("colima", "stop")).toBe(false);
   });
 
-  test("does not restart Colima when it is already running", async () => {
-    const { exec, ran } = fakeExec({ dockerInfo: true, colimaStatus: false });
+  // Regression (v0.12.8 release feedback): a zombie Colima — stale state file
+  // saying "already running" while the daemon inside is dead — used to sail
+  // through wake (no `colima status` oracle anymore) and leave every later
+  // docker command dying on the unreachable socket.
+  test("recovers a zombie Colima: start no-ops, daemon stays dead → stop --force → start → daemon up", async () => {
+    const { exec, ran } = fakeExec({ zombieFirstStart: true });
 
-    await ensureDockerDaemonRunning(exec);
+    await ensureDockerDaemonRunning(exec, { settleTimeoutMs: 0 });
 
-    expect(ran("colima", "status")).toBe(true);
-    expect(ran("colima", "start")).toBe(false);
+    expect(ran("colima", "start")).toBe(true);
+    expect(ran("colima", "stop")).toBe(true);
+  });
+
+  test("never deletes the Colima VM — the VM disk holds every image and volume", async () => {
+    const { exec, ran } = fakeExec({ zombieFirstStart: true });
+
+    await ensureDockerDaemonRunning(exec, { settleTimeoutMs: 0 });
+
+    expect(ran("colima", "delete")).toBe(false);
+  });
+
+  test("throws an actionable error when even the restart cannot bring the daemon up", () => {
+    // A start that always exits nonzero: the first failure surfaces its
+    // output, the recovery stop+start runs, and the final wait still finds
+    // no daemon → the helper throws instead of letting hatch proceed.
+    const { exec } = fakeExec({ startFails: true });
+    expect(
+      ensureDockerDaemonRunning(exec, { settleTimeoutMs: 0 }),
+    ).rejects.toThrow(/Failed to restart Colima/);
+  });
+});
+
+describe("pullImage", () => {
+  function fakePull(
+    opts: {
+      failFirstPullWith?: string;
+      failAllPullsWith?: string;
+    } = {},
+  ) {
+    const calls: Array<{ cmd: string; args: string[] }> = [];
+    let pulls = 0;
+    const exec = async (cmd: string, args: string[] = []): Promise<void> => {
+      calls.push({ cmd, args });
+      if (cmd === "docker" && args[0] === "pull") {
+        pulls++;
+        if (opts.failAllPullsWith) throw new Error(opts.failAllPullsWith);
+        if (opts.failFirstPullWith && pulls === 1) {
+          throw new Error(opts.failFirstPullWith);
+        }
+      }
+      // `docker logout` (and anything else) succeeds silently.
+    };
+    const ran = (sub: string): boolean =>
+      calls.some((c) => c.cmd === "docker" && c.args[0] === sub);
+    return { exec, ran };
+  }
+
+  test("pulls without touching stored credentials on success", async () => {
+    const { exec, ran } = fakePull();
+
+    await pullImage("mycadet/mycadet-assistant:v1", () => {}, exec);
+
+    expect(ran("pull")).toBe(true);
+    expect(ran("logout")).toBe(false);
+  });
+
+  test("clears stale Docker Hub credentials and retries once on an expired-token error", async () => {
+    const { exec, ran } = fakePull({
+      failFirstPullWith:
+        "Error response from daemon: authentication required - personal access token is expired",
+    });
+
+    await pullImage("mycadet/mycadet-assistant:v1", () => {}, exec);
+
+    expect(ran("logout")).toBe(true);
+  });
+
+  test("wraps the failure with actionable copy when the auth retry also fails", () => {
+    const { exec } = fakePull({
+      failAllPullsWith:
+        "Error response from daemon: authentication required - personal access token is expired",
+    });
+
+    expect(
+      pullImage("mycadet/mycadet-assistant:v1", () => {}, exec),
+    ).rejects.toThrow("Failed to pull mycadet/mycadet-assistant:v1");
+  });
+
+  test("rethrows non-auth pull errors raw and never logs out", () => {
+    const { exec, ran } = fakePull({
+      failAllPullsWith:
+        "Cannot connect to the Docker daemon at unix:///var/run/docker.sock",
+    });
+
+    expect(
+      pullImage("mycadet/mycadet-assistant:v1", () => {}, exec),
+    ).rejects.toThrow("Cannot connect to the Docker daemon");
+    expect(ran("logout")).toBe(false);
   });
 });

package/src/lib/__tests__/job-polling.test.ts

@@ -1,7 +1,7 @@
 import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
 
 import { pollJobUntilDone } from "../job-polling.js";
-import type { UnifiedJobStatus } from "../platform-client.js";
+import type { UnifiedJobStatus } from "../cloud-client.js";
 
 describe("pollJobUntilDone", () => {
   test("returns terminal 'complete' after N processing polls", async () => {
@@ -203,7 +203,7 @@ describe("pollJobUntilDone", () => {
       expect(refreshes).toBe(1);
       expect(calls).toBe(2);
       // The 401 branch logs its own distinct warning (not the generic
-      // "polling failed, retrying" one) so operators can distinguish an
+      // "polling failed:" one) so operators can distinguish an
       // auth refresh from a transient-error retry in the output.
       expect(warnSpy).toHaveBeenCalledWith(
         expect.stringContaining("refreshing auth"),

package/src/lib/__tests__/local-gateway-cli.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, test } from "bun:test";
+
+import type { LocalInstanceResources } from "../assistant-config.js";
+import { gatewayCliInvocation } from "../local.js";
+
+function fakeResources(instanceDir: string): LocalInstanceResources {
+  // gatewayCliInvocation only reads instanceDir; the rest of the resources
+  // shape is irrelevant here.
+  return { instanceDir } as unknown as LocalInstanceResources;
+}
+
+describe("gatewayCliInvocation", () => {
+  test("runs the gateway package's CLI entry through bun", () => {
+    const invocation = gatewayCliInvocation();
+    expect(invocation.args[0]).toBe("run");
+    expect(invocation.args[1]).toMatch(/gateway\/src\/cli\/index\.ts$/);
+  });
+
+  test("pins CADET_WORKSPACE_DIR to the instance dir for named instances", () => {
+    const invocation = gatewayCliInvocation(
+      fakeResources("/data/assistants/testy"),
+    );
+    expect(invocation.env.CADET_WORKSPACE_DIR).toBe(
+      "/data/assistants/testy/workspace",
+    );
+  });
+
+  test("pins GATEWAY_SECURITY_DIR to the instance dir for named instances", () => {
+    const invocation = gatewayCliInvocation(
+      fakeResources("/data/assistants/testy"),
+    );
+    expect(invocation.env.GATEWAY_SECURITY_DIR).toBe(
+      "/data/assistants/testy/gateway-security",
+    );
+  });
+
+  test("leaves the workspace resolution untouched for the default instance", () => {
+    delete process.env.CADET_WORKSPACE_DIR;
+    const invocation = gatewayCliInvocation();
+    expect(invocation.env.CADET_WORKSPACE_DIR).toBeUndefined();
+  });
+});

package/src/lib/__tests__/local-runtime-client.test.ts

@@ -14,7 +14,7 @@ const TOKEN = "local-bearer-token";
 
 // All tests in this file exercise the local/docker code path (cloud="local"),
 // which builds `{runtimeUrl}/v1/migrations/<subpath>` URLs and uses
-// guardian-token bearer auth. The platform path (cloud="cadet") is covered
+// guardian-token bearer auth. The cloud path (cloud="cadet") is covered
 // by `runtime-url.test.ts` (URL construction) and the teleport tests
 // (call-site wiring).
 const ENTRY: Pick<AssistantEntry, "cloud" | "runtimeUrl" | "assistantId"> = {
@@ -384,7 +384,7 @@ describe("localRuntimePollJobStatus", () => {
 });
 
 // ---------------------------------------------------------------------------
-// Platform-managed assistants (cloud="cadet") route through the platform's
+// Cloud assistants (cloud="cadet") route through the cloud's
 // wildcard runtime proxy at `/v1/assistants/<id>/migrations/...` with
 // platform-token auth (NOT guardian-token bearer). This block asserts the
 // actual URL and headers built by the helpers — not mocked, not abstracted.
@@ -588,7 +588,7 @@ describe("localRuntimeIdentity", () => {
   });
 
   // ---------------------------------------------------------------------
-  // 401-retry parity with platformRequestSignedUrl (Codex P2 regression
+  // 401-retry parity with cloudRequestSignedUrl (Codex P2 regression
   // guard). localRuntimeIdentity is the first network call in the
   // backup/teleport export flow for cadet-cloud assistants, so a stale
   // Cadet-Organization-Id cache entry would surface as a hard abort
@@ -613,7 +613,7 @@ describe("localRuntimeIdentity", () => {
         orgIdFetchedAs.push(`org-${orgIdFetchedAs.length + 1}`);
         return new Response(
           JSON.stringify({
-            results: [{ id: orgIdFetchedAs[orgIdFetchedAs.length - 1]! }],
+            results: [{ id: orgIdFetchedAs[orgIdFetchedAs.length - 1]!, name: "My Cadet" }],
           }),
           { status: 200 },
         );

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

@@ -49,7 +49,7 @@ describe("resolveRuntimeMigrationUrl", () => {
     );
   });
 
-  test("cadet (platform-managed) cloud uses wildcard-proxy /v1/assistants/<id>/migrations/<subpath>", () => {
+  test("cadet (cloud-managed) cloud uses wildcard-proxy /v1/assistants/<id>/migrations/<subpath>", () => {
     const entry = makeEntry({
       cloud: "cadet",
       runtimeUrl: "https://cloud.mycadet.ai",

package/src/lib/assistant-api-key-resolution.ts

@@ -8,8 +8,8 @@
 import {
   readGatewayCredential,
   reprovisionAssistantApiKey,
-  verifyGatewayManagedCredential,
-} from "./platform-client.js";
+  verifyGatewayCloudCredential,
+} from "./cloud-client.js";
 
 /** Where the key came from, so callers can report what they did. */
 export type AssistantApiKeySource =
@@ -39,13 +39,13 @@ export interface ResolvedAssistantApiKey {
  * Three steps, in order: the key the registration just issued, the key the
  * assistant already holds, then a rotation.
  *
- * A stored key the platform has rejected is skipped, because reinjecting it
+ * A stored key the cloud has rejected is skipped, because reinjecting it
  * repairs nothing while looking like a repair. The verdict is asked for
  * before the key is read, so the key returned is one the verdict covers: a
  * repair that lands between the two requests is then read, not overwritten
  * by the value it replaced. Rotation is still withheld when the gateway is
  * merely unreachable: rotating without being able to store the replacement
- * would start the platform's grace clock on a key the assistant still needs,
+ * would start the cloud's grace clock on a key the assistant still needs,
  * with nothing to hand it in exchange.
  */
 export async function resolveAssistantApiKeyForInjection(
@@ -55,7 +55,7 @@ export async function resolveAssistantApiKeyForInjection(
     return { apiKey: args.registrationApiKey, source: "registration" };
   }
 
-  const status = await verifyGatewayManagedCredential(
+  const status = await verifyGatewayCloudCredential(
     args.runtimeUrl,
     args.bearerToken,
   );

package/src/lib/assistant-client.ts

@@ -14,10 +14,10 @@
  * The auth scheme follows the assistant's topology, so callers never pick it.
  * Platform-managed entries in particular have no local guardian token: they
  * authenticate against the wildcard runtime proxy at
- * `{platformUrl}/v1/assistants/<id>/<rest>` with the stored cloud credential.
+ * `{cloudUrl}/v1/assistants/<id>/<rest>` with the stored cloud credential.
  */
 
-import { isManagedCloud } from "./managed-cloud.js";
+import { isCloudHome } from "./cloud-values.js";
 import { resolveAssistant } from "./assistant-config.js";
 import { GATEWAY_PORT } from "./constants.js";
 import {
@@ -29,8 +29,8 @@ import { loopbackSafeFetch } from "./loopback-fetch.js";
 import {
   authHeaders,
   invalidateOrgIdCache,
-  readPlatformToken,
-} from "./platform-client.js";
+  readCloudToken,
+} from "./cloud-client.js";
 
 const DEFAULT_TIMEOUT_MS = 30_000;
 const FALLBACK_RUNTIME_URL = `http://127.0.0.1:${GATEWAY_PORT}`;
@@ -54,7 +54,7 @@ export interface AssistantClientOpts {
    * sent as `X-Session-Token: <sessionToken>` and the org id is
    * sent via the `Cadet-Organization-Id` header.
    *
-   * Platform-managed assistants do NOT need this: they are detected from the
+   * Cloud assistants do NOT need this: they are detected from the
    * lockfile entry and authenticated from the stored platform token.
    */
   sessionToken?: string;
@@ -75,7 +75,7 @@ export class AssistantClient {
   private readonly _assistantId: string;
   /**
    * The credential for the current mode. Mutable: a 401 on the guardian path
-   * refreshes it in place (see request), and the platform path fills it in on
+   * refreshes it in place (see request), and the cloud path fills it in on
    * first use (see resolveAuthHeaders).
    */
   private token: string | undefined;
@@ -103,7 +103,7 @@ export class AssistantClient {
     }
 
     this._assistantId = entry.assistantId;
-    const platformManaged = !opts?.sessionToken && isManagedCloud(entry.cloud);
+    const platformManaged = !opts?.sessionToken && isCloudHome(entry.cloud);
     const platformHost = stripTrailingSlashes(entry.runtimeUrl);
 
     // SECURITY: a cloud credential is account-scoped, far broader than the
@@ -155,7 +155,7 @@ export class AssistantClient {
    * error rather than letting an anonymous request fall through to a bare 403.
    */
   private requirePlatformToken(): string {
-    const token = readPlatformToken();
+    const token = readCloudToken();
     if (!token) {
       throw new Error(
         "Not logged in. Run `cadet login` first to authenticate with Cadet Cloud.",

package/src/lib/assistant-config.ts

@@ -63,19 +63,11 @@ export type LocalInstanceResources = Omit<
   [key: string]: unknown;
 };
 
-/** Docker image metadata for the service group. Enables rollback to known-good digests. */
+/** Docker image metadata for the service group. Enables rollback to known-good refs. */
 export interface ContainerInfo {
   assistantImage: string;
   gatewayImage: string;
   cesImage: string;
-  /** sha256 digest of the assistant image at time of hatch/upgrade */
-  assistantDigest?: string;
-  /** sha256 digest of the gateway image at time of hatch/upgrade */
-  gatewayDigest?: string;
-  /** sha256 digest of the CES image at time of hatch/upgrade */
-  cesDigest?: string;
-  /** Docker network name for the service group */
-  networkName?: string;
   /**
    * Host-side port the assistant HTTP API is published on. Dynamically
    * allocated at hatch time so concurrent instances don't collide on the
@@ -159,10 +151,29 @@ export type AssistantLookupResult =
 interface LockfileData {
   assistants?: Record<string, unknown>[];
   activeAssistant?: string;
-  platformBaseUrl?: string;
+  cloudBaseUrl?: string;
+  tunnel?: RootProcessRecord;
+  app?: RootProcessRecord;
   [key: string]: unknown;
 }
 
+/**
+ * A CLI-managed OS process recorded at the lockfile root, keyed by what it is
+ * for — `tunnel` (the auto-tunnel agent fronting the edge) and `app` (the
+ * nginx ingress edge). `cadet ps` renders these alongside the per-assistant
+ * process trees, and the stop paths verify the pid before signaling it.
+ */
+export interface RootProcessRecord {
+  pid: number;
+  /** Which tunnel provider owns the process; "tunnel" entries only. */
+  provider?: string;
+  /** The assistant the process fronts, so `cadet ps` can nest the row. */
+  assistantId?: string;
+  startedAt: string;
+}
+
+export type RootProcessKind = "tunnel" | "app";
+
 /**
  * Derive the daemon PID file path from a resources object. The PID file
  * lives inside the instance's workspace directory. When no resources are
@@ -224,6 +235,40 @@ function withCliLockfileLock<T>(fn: () => T): T {
   return locked.value;
 }
 
+/** Record a CLI-managed root process (tunnel agent, app edge) by pid. */
+export function stampRootProcess(
+  kind: RootProcessKind,
+  record: RootProcessRecord,
+): void {
+  withCliLockfileLock(() => {
+    const data = readLockfile();
+    data[kind] = record;
+    writeLockfileUnlocked(data);
+  });
+}
+
+/** Drop the recorded root process entry, e.g. once the process is stopped. */
+export function clearRootProcess(kind: RootProcessKind): void {
+  withCliLockfileLock(() => {
+    const data = readLockfile();
+    if (data[kind] === undefined) return;
+    delete data[kind];
+    writeLockfileUnlocked(data);
+  });
+}
+
+/**
+ * Read the root-level process entries for `cadet ps`. Read-only: no lock, so
+ * a concurrently-updating lockfile is fine — the pid is verified separately.
+ */
+export function readRootProcesses(): {
+  tunnel?: RootProcessRecord;
+  app?: RootProcessRecord;
+} {
+  const data = readLockfile();
+  return { tunnel: data.tunnel, app: data.app };
+}
+
 /**
  * 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.
@@ -746,13 +791,14 @@ export async function allocateLocalResources(
 }
 
 /**
- * Return `platformBaseUrl` from the lockfile, if set. This is the value
+ * Return `cloudBaseUrl` from the lockfile, if set. This is the value
  * persisted by {@link syncConfigToLockfile} the last time the active
  * assistant was hatched/waked, and is the source of truth for "which
  * platform does the currently-active assistant target".
  */
 export function getLockfilePlatformBaseUrl(): string | undefined {
-  const url = readLockfile().platformBaseUrl;
+  const lockfile = readLockfile();
+  const url = lockfile.cloudBaseUrl ?? lockfile.platformBaseUrl;
   if (typeof url === "string" && url.trim()) return url.trim();
   return undefined;
 }