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

package/src/lib/ensure-binary.ts

@@ -0,0 +1,171 @@
+import { spawnSync } from "node:child_process";
+import type { Readable, Writable } from "node:stream";
+
+/**
+ * Consolidated missing-dependency flow for interactive commands: probe for a
+ * binary, and when it is absent, offer to install it — naming no commands —
+ * then run the right package manager for the platform and verify. Callers
+ * supply the recipes; everything else (prompt, package-manager discovery,
+ * fallback copy) lives here so every command behaves the same.
+ */
+
+export interface EnsureBinaryOptions {
+  /** The binary as invoked on PATH, e.g. "nginx". */
+  binary: string;
+  /** What the running command needs it for, e.g. "the tunnel edge". */
+  purpose: string;
+  /**
+   * Package-manager name → full install argv (sudo included where needed),
+   * e.g. `{ brew: ["brew", "install", "nginx"] }`. The first entry whose
+   * package manager is available wins. Leave out a platform rather than
+   * guessing at an unreliable package ID — the manual hint covers it.
+   */
+  packages: Record<string, string[]>;
+  /** Shown when the user declines or auto-install fails. */
+  manualHint: string;
+  /** Probe: a version-ish string when the binary is usable, null otherwise. */
+  probe: () => string | null;
+  /** Check that a package manager exists. Default: `<pm> --version` probe. */
+  pmAvailable?: (pm: string) => boolean;
+  /** Run an install argv; true on success. Default: inherit-stdio spawnSync. */
+  runInstall?: (argv: string[]) => boolean;
+  /** Confirm the install. Default: promptLine "[Y/n]" on Enter-as-yes. */
+  confirmInstall?: () => Promise<boolean>;
+  streams?: {
+    input?: NodeJS.ReadStream | Readable;
+    output?: NodeJS.WriteStream | Writable;
+  };
+}
+
+/**
+ * Prompt-then-install a missing binary. Returns the probe result — the
+ * existing version when the binary was already present, the fresh one after a
+ * successful install — or null when the binary is missing and the user
+ * declines, no package manager matches, or the install fails. Non-interactive
+ * callers (no TTY) never hang: they get the manual hint and null.
+ */
+export async function ensureBinaryInstalled(
+  opts: EnsureBinaryOptions,
+): Promise<string | null> {
+  const output = opts.streams?.output ?? process.stdout;
+
+  const existing = opts.probe();
+  if (existing) return existing;
+
+  output.write(
+    `\n${opts.binary} is required for ${opts.purpose}, but it isn't installed.\n`,
+  );
+
+  const confirm = opts.confirmInstall ?? defaultConfirm(opts);
+  let install = false;
+  try {
+    install = await confirm();
+  } catch {
+    install = false;
+  }
+  if (!install) {
+    output.write(`Skipping install. ${opts.manualHint}\n`);
+    return null;
+  }
+
+  const pmAvailable = opts.pmAvailable ?? probePackageManager;
+  const argv = Object.entries(opts.packages).find(([pm]) =>
+    pmAvailable(pm),
+  )?.[1];
+  if (!argv) {
+    output.write(`⚠ No supported package manager found. ${opts.manualHint}\n`);
+    return null;
+  }
+
+  const ok = opts.runInstall ? opts.runInstall(argv) : runInstallArgv(argv);
+  const version = ok ? opts.probe() : null;
+  if (!version) {
+    output.write(
+      `⚠ Couldn't install ${opts.binary} automatically. ${opts.manualHint}\n`,
+    );
+    return null;
+  }
+  output.write(`✅ Installed ${opts.binary} (${version}).\n`);
+  return version;
+}
+
+/** Default confirm: visible prompt, Enter = yes, non-TTY throws. */
+function defaultConfirm(opts: EnsureBinaryOptions): () => Promise<boolean> {
+  return async () => {
+    const input = opts.streams?.input ?? process.stdin;
+    const output = opts.streams?.output ?? process.stdout;
+    // Readable has no isTTY; only a real terminal answers the prompt.
+    if (!("isTTY" in input) || !input.isTTY) {
+      throw new Error("Install confirm requires an interactive terminal.");
+    }
+    const answer = (
+      await readLineText(`Install ${opts.binary} now? [Y/n] `, {
+        input,
+        output,
+      })
+    )
+      .trim()
+      .toLowerCase();
+    return answer === "" || answer === "y" || answer === "yes";
+  };
+}
+
+/** Default installer: blocking spawn with inherited stdio (passwords flow). */
+function runInstallArgv(argv: string[]): boolean {
+  const [command, ...args] = argv;
+  if (!command) return false;
+  const result = spawnSync(command, args, { stdio: "inherit" });
+  return !result.error && result.status === 0;
+}
+
+/** Default package-manager check: the manager answers `--version`. */
+function probePackageManager(pm: string): boolean {
+  const result = spawnSync(pm, ["--version"], {
+    stdio: "ignore",
+    shell: process.platform === "win32",
+    windowsHide: true,
+  });
+  return !result.error && result.status === 0;
+}
+
+/**
+ * Read one visible line from stdin (Enter submits). Shared by the binary
+ * install confirm and the ngrok authtoken paste-in, so both degrade the same
+ * way on a non-interactive terminal (the caller decides what empty means).
+ */
+export async function readLineText(
+  prompt: string,
+  streams: { input?: Readable; output?: Writable } = {},
+): Promise<string> {
+  const input = streams.input ?? process.stdin;
+  const output = streams.output ?? process.stdout;
+
+  output.write(prompt);
+
+  return new Promise((resolve, reject) => {
+    let line = "";
+    const onData = (chunk: Buffer | string): void => {
+      line += typeof chunk === "string" ? chunk : chunk.toString("utf-8");
+      const newline = line.indexOf("\n");
+      if (newline !== -1) {
+        done(line.slice(0, newline).replace(/\r$/, ""));
+      }
+    };
+    const cleanup = (): void => {
+      input.removeListener("data", onData);
+      input.removeListener("error", onError);
+      input.pause();
+    };
+    const done = (value: string): void => {
+      cleanup();
+      resolve(value);
+    };
+    const onError = (err: Error): void => {
+      cleanup();
+      reject(err);
+    };
+    input.resume();
+    input.on("data", onData);
+    input.on("error", onError);
+  });
+}

package/src/lib/environments/__tests__/paths.test.ts

@@ -39,26 +39,33 @@ const {
   getConfigDir,
   getConfigDirs,
   getDefaultPorts,
+  getInputHistoryPath,
   getLockfilePath,
   getLockfilePaths,
   getMultiInstanceDir,
+  getSharedStateDir,
 } = await import("../paths.js");
 type EnvironmentDefinition =
   import("@mycadet/environments").EnvironmentDefinition;
 
 const prod: EnvironmentDefinition = {
   name: "production",
-  platformUrl: "https://cloud.mycadet.ai",
+  cloudUrl: "https://cloud.mycadet.ai",
   webUrl: "https://mycadet.ai",
 };
 
 const dev: EnvironmentDefinition = {
   name: "dev",
-  platformUrl: "https://dev-cloud.mycadet.ai",
+  cloudUrl: "https://dev-cloud.mycadet.ai",
   webUrl: "https://dev.mycadet.ai",
 };
 
-const XDG_ENV_VARS = ["XDG_DATA_HOME", "XDG_CONFIG_HOME", "APPDATA"] as const;
+const XDG_ENV_VARS = [
+  "XDG_DATA_HOME",
+  "XDG_CONFIG_HOME",
+  "XDG_STATE_HOME",
+  "APPDATA",
+] as const;
 
 describe("path helpers", () => {
   let savedEnv: Record<string, string | undefined>;
@@ -224,6 +231,25 @@ describe("path helpers", () => {
     });
   });
 
+  describe("getSharedStateDir", () => {
+    test("is not environment-scoped: ~/.local/state/cadet for every env", () => {
+      expect(getSharedStateDir()).toBe(
+        join(TEST_HOME, ".local", "state", "cadet"),
+      );
+    });
+
+    test("respects XDG_STATE_HOME", () => {
+      process.env.XDG_STATE_HOME = "/custom/state";
+      expect(getSharedStateDir()).toBe("/custom/state/cadet");
+    });
+
+    test("holds the shared terminal input history file", () => {
+      expect(getInputHistoryPath()).toBe(
+        join(getSharedStateDir(), "input-history"),
+      );
+    });
+  });
+
   describe("getDefaultPorts", () => {
     test("returns production defaults for production", () => {
       const ports = getDefaultPorts(prod);

package/src/lib/environments/__tests__/resolve.test.ts

@@ -8,7 +8,7 @@ import {
 
 const ENV_VARS_TO_SAVE = [
   "CADET_ENVIRONMENT",
-  "CADET_PLATFORM_URL",
+  "CADET_CLOUD_URL",
   "CADET_ASSISTANT_PLATFORM_URL",
   "CADET_LOCKFILE_DIR",
 ] as const;
@@ -37,33 +37,33 @@ describe("getCurrentEnvironment", () => {
   test("returns production seed when no override, no env var", () => {
     const env = getCurrentEnvironment();
     expect(env.name).toBe("production");
-    expect(env.platformUrl).toBe("https://cloud.mycadet.ai");
+    expect(env.cloudUrl).toBe("https://cloud.mycadet.ai");
   });
 
   test("returns dev seed when CADET_ENVIRONMENT=dev", () => {
     process.env.CADET_ENVIRONMENT = "dev";
     const env = getCurrentEnvironment();
     expect(env.name).toBe("dev");
-    expect(env.platformUrl).toBe("https://dev-cloud.mycadet.ai");
+    expect(env.cloudUrl).toBe("https://dev-cloud.mycadet.ai");
   });
 
   test("returns staging seed when CADET_ENVIRONMENT=staging", () => {
     process.env.CADET_ENVIRONMENT = "staging";
-    expect(getCurrentEnvironment().platformUrl).toBe(
+    expect(getCurrentEnvironment().cloudUrl).toBe(
       "https://staging-cloud.mycadet.ai",
     );
   });
 
   test("returns local seed with localhost URL", () => {
     process.env.CADET_ENVIRONMENT = "local";
-    expect(getCurrentEnvironment().platformUrl).toBe("http://localhost:8000");
+    expect(getCurrentEnvironment().cloudUrl).toBe("http://localhost:8000");
   });
 
   test("override argument takes priority over CADET_ENVIRONMENT env var", () => {
     process.env.CADET_ENVIRONMENT = "staging";
     const env = getCurrentEnvironment("dev");
     expect(env.name).toBe("dev");
-    expect(env.platformUrl).toBe("https://dev-cloud.mycadet.ai");
+    expect(env.cloudUrl).toBe("https://dev-cloud.mycadet.ai");
   });
 
   test("empty override argument falls through to env var", () => {
@@ -85,7 +85,7 @@ describe("getCurrentEnvironment", () => {
     try {
       const env = getCurrentEnvironment("no-such-env");
       expect(env.name).toBe("production");
-      expect(env.platformUrl).toBe("https://cloud.mycadet.ai");
+      expect(env.cloudUrl).toBe("https://cloud.mycadet.ai");
       expect(stderr).toHaveBeenCalledWith(
         expect.stringContaining('unknown environment "no-such-env"'),
       );
@@ -105,7 +105,7 @@ describe("getCurrentEnvironment", () => {
     try {
       const env = getCurrentEnvironment();
       expect(env.name).toBe("production");
-      expect(env.platformUrl).toBe("https://cloud.mycadet.ai");
+      expect(env.cloudUrl).toBe("https://cloud.mycadet.ai");
       expect(stderr).toHaveBeenCalledWith(
         expect.stringContaining('unknown environment "nope"'),
       );
@@ -128,49 +128,49 @@ describe("getCurrentEnvironment", () => {
     }
   });
 
-  test("CADET_PLATFORM_URL overrides platformUrl on the resolved definition", () => {
+  test("CADET_CLOUD_URL overrides cloudUrl on the resolved definition", () => {
     process.env.CADET_ENVIRONMENT = "dev";
-    process.env.CADET_PLATFORM_URL = "https://custom.example.com";
+    process.env.CADET_CLOUD_URL = "https://custom.example.com";
     const env = getCurrentEnvironment();
     expect(env.name).toBe("dev");
-    expect(env.platformUrl).toBe("https://custom.example.com");
+    expect(env.cloudUrl).toBe("https://custom.example.com");
   });
 
-  test("CADET_PLATFORM_URL override does not affect the seed table", () => {
-    process.env.CADET_PLATFORM_URL = "https://custom.example.com";
+  test("CADET_CLOUD_URL override does not affect the seed table", () => {
+    process.env.CADET_CLOUD_URL = "https://custom.example.com";
     getCurrentEnvironment();
-    delete process.env.CADET_PLATFORM_URL;
+    delete process.env.CADET_CLOUD_URL;
     const env = getCurrentEnvironment();
-    expect(env.platformUrl).toBe("https://cloud.mycadet.ai");
+    expect(env.cloudUrl).toBe("https://cloud.mycadet.ai");
   });
 
-  test("CADET_ASSISTANT_PLATFORM_URL overrides assistantPlatformUrl", () => {
+  test("CADET_ASSISTANT_PLATFORM_URL overrides assistantCloudUrl", () => {
     process.env.CADET_ASSISTANT_PLATFORM_URL =
       "http://host.docker.internal:8000";
     const env = getCurrentEnvironment();
-    expect(env.assistantPlatformUrl).toBe("http://host.docker.internal:8000");
+    expect(env.assistantCloudUrl).toBe("http://host.docker.internal:8000");
   });
 
-  test("CADET_ASSISTANT_PLATFORM_URL does not shadow platformUrl", () => {
+  test("CADET_ASSISTANT_PLATFORM_URL does not shadow cloudUrl", () => {
     process.env.CADET_ASSISTANT_PLATFORM_URL = "http://override";
     const env = getCurrentEnvironment();
-    expect(env.platformUrl).toBe("https://cloud.mycadet.ai");
+    expect(env.cloudUrl).toBe("https://cloud.mycadet.ai");
   });
 
-  test("does not auto-materialize a new environment from CADET_PLATFORM_URL alone", () => {
+  test("does not auto-materialize a new environment from CADET_CLOUD_URL alone", () => {
     // Unknown env names fall back to production (parity with daemon + Swift).
-    // The per-field CADET_PLATFORM_URL override is intentionally dropped on
+    // The per-field CADET_CLOUD_URL override is intentionally dropped on
     // the fallback path — fallback returns a pristine production seed so a
     // typo'd env var can't accidentally stitch together a new environment.
     process.env.CADET_ENVIRONMENT = "my-custom";
-    process.env.CADET_PLATFORM_URL = "https://my-custom.example.com";
+    process.env.CADET_CLOUD_URL = "https://my-custom.example.com";
     const stderr = spyOn(process.stderr, "write").mockImplementation(
       () => true,
     );
     try {
       const env = getCurrentEnvironment();
       expect(env.name).toBe("production");
-      expect(env.platformUrl).toBe("https://cloud.mycadet.ai");
+      expect(env.cloudUrl).toBe("https://cloud.mycadet.ai");
       expect(stderr).toHaveBeenCalledWith(
         expect.stringContaining('unknown environment "my-custom"'),
       );
@@ -232,7 +232,7 @@ describe("getSeed", () => {
     const seed = getSeed("dev");
     expect(seed).toBeDefined();
     expect(seed?.name).toBe("dev");
-    expect(seed?.platformUrl).toBe("https://dev-cloud.mycadet.ai");
+    expect(seed?.cloudUrl).toBe("https://dev-cloud.mycadet.ai");
   });
 
   test("returns undefined for an unknown name", () => {
@@ -242,10 +242,10 @@ describe("getSeed", () => {
   test("returned seed is a copy — mutations do not affect the table", () => {
     const seed = getSeed("dev");
     if (seed) {
-      seed.platformUrl = "mutated";
+      seed.cloudUrl = "mutated";
     }
     const second = getSeed("dev");
-    expect(second?.platformUrl).toBe("https://dev-cloud.mycadet.ai");
+    expect(second?.cloudUrl).toBe("https://dev-cloud.mycadet.ai");
   });
 
   test("all five canonical seeds exist", () => {

package/src/lib/environments/paths.ts

@@ -82,18 +82,26 @@ export function getLogDir(env: EnvironmentDefinition): string {
 }
 
 /**
- * Path to the interactive CLI's input history file.
+ * The interactive CLI's shared state directory — `$XDG_STATE_HOME/cadet`.
  *
- * Follows the XDG Base Directory spec: history files are state data
- * (persistent across runs but not portable / user-owned content), so they
- * belong under `$XDG_STATE_HOME`, mirroring `bash`, `zsh`, `psql`, and `gh`.
- * Defaults to `~/.local/state/cadet/input-history`.
+ * Follows the XDG Base Directory spec: session state is data that persists
+ * across runs but is not portable user-owned content, mirroring `bash`,
+ * `zsh`, `psql`, and `gh`. Defaults to `~/.local/state/cadet`.
  *
- * Not environment-scoped: terminal input history is per-user, not per-assistant,
- * so dev and prod CLIs share the same history file.
+ * Not environment-scoped: it holds per-user state (the terminal input
+ * history, below) that dev and prod CLIs share.
+ */
+export function getSharedStateDir(): string {
+  return join(xdgStateHome(), "cadet");
+}
+
+/**
+ * Path to the interactive CLI's input history file, inside
+ * {@link getSharedStateDir}. Defaults to
+ * `~/.local/state/cadet/input-history`.
  */
 export function getInputHistoryPath(): string {
-  return join(xdgStateHome(), "cadet", "input-history");
+  return join(getSharedStateDir(), "input-history");
 }
 
 /**

package/src/lib/environments/resolve.ts

@@ -43,9 +43,9 @@ export function environmentFromVersion(version: string): string {
  *
  * Per-field env-var overrides are honored on the resolved definition as
  * ad-hoc escape hatches (they do not materialize new environments):
- *   - `CADET_PLATFORM_URL` overrides `platformUrl`
+ *   - `CADET_CLOUD_URL` overrides `cloudUrl`
  *   - `CADET_WEB_URL` overrides `webUrl`
- *   - `CADET_ASSISTANT_PLATFORM_URL` overrides `assistantPlatformUrl`
+ *   - `CADET_ASSISTANT_PLATFORM_URL` overrides `assistantCloudUrl`
  *   - `CADET_LOCKFILE_DIR` overrides `lockfileDirOverride` (legacy e2e
  *     test hook)
  *
@@ -67,10 +67,8 @@ export function getCurrentEnvironment(
   const seed = SEEDS[name];
   if (!seed) {
     if (name !== DEFAULT_ENVIRONMENT_NAME) {
-      // Warn on stderr instead of throwing, to match the silent-fallback
-      // behavior in assistant/src/util/platform.ts:getXdgCadetConfigDirName,
-      // which silently falls back to production; the CLI agrees so neither
-      // writer ends up in a disjoint state on a typo.
+      // Warn on stderr instead of throwing: an unknown environment falls back
+      // to production, so a typo never splits writes between two states.
       process.stderr.write(
         `warning: unknown environment "${name}"; falling back to "${DEFAULT_ENVIRONMENT_NAME}". ` +
           `Add it to packages/environments/src/seeds.ts and rebuild if this was intentional.\n`,
@@ -87,9 +85,9 @@ export function getCurrentEnvironment(
 
   const resolved: EnvironmentDefinition = { ...seed };
 
-  const platformUrlOverride = process.env.CADET_PLATFORM_URL?.trim();
-  if (platformUrlOverride) {
-    resolved.platformUrl = platformUrlOverride;
+  const cloudUrlOverride = process.env.CADET_CLOUD_URL?.trim();
+  if (cloudUrlOverride) {
+    resolved.cloudUrl = cloudUrlOverride;
   }
 
   const webUrlOverride = process.env.CADET_WEB_URL?.trim();
@@ -97,10 +95,10 @@ export function getCurrentEnvironment(
     resolved.webUrl = webUrlOverride;
   }
 
-  const assistantPlatformUrlOverride =
+  const assistantCloudUrlOverride =
     process.env.CADET_ASSISTANT_PLATFORM_URL?.trim();
-  if (assistantPlatformUrlOverride) {
-    resolved.assistantPlatformUrl = assistantPlatformUrlOverride;
+  if (assistantCloudUrlOverride) {
+    resolved.assistantCloudUrl = assistantCloudUrlOverride;
   }
 
   const lockfileDirOverride = process.env.CADET_LOCKFILE_DIR?.trim();

package/src/lib/flag-args.test.ts

@@ -75,7 +75,7 @@ describe("parseFeatureFlagArgs", () => {
       "process.exit",
     );
     expect(errorSpy).toHaveBeenCalledWith(
-      'Error: invalid flag key "UPPER". Keys must be kebab-case (e.g. "browser")',
+      'Error: invalid flag key "UPPER". Keys must be kebab-case, e.g. "browser"',
     );
 
     exitSpy.mockRestore();

package/src/lib/flag-args.ts

@@ -38,7 +38,7 @@ export function parseFeatureFlagArgs(args: string[]): {
 
       if (!ALLOWED_KEY_RE.test(key)) {
         console.error(
-          `Error: invalid flag key "${key}". Keys must be kebab-case (e.g. "browser")`,
+          `Error: invalid flag key "${key}". Keys must be kebab-case, e.g. "browser"`,
         );
         process.exit(1);
       }

package/src/lib/guardian-token.ts

@@ -49,7 +49,11 @@ const GuardianTokenFieldsSchema = z
       .union([z.string(), z.number()])
       .optional()
       .catch(undefined),
-    refreshAfter: z.string().optional().catch(undefined),
+    refreshAfter: z
+      .union([z.string(), z.number()])
+      .transform((v) => (typeof v === "number" ? new Date(v).toISOString() : v))
+      .optional()
+      .catch(undefined),
     isNew: z.boolean().optional().catch(undefined),
     deviceId: z.string().optional().catch(undefined),
   })
@@ -425,7 +429,7 @@ export async function refreshGuardianTokenResult(
     console.warn(
       `Refusing to refresh the guardian token over an insecure URL (${gatewayUrl}). ` +
         "The refresh token is only sent over https or a loopback address: " +
-        "use an https URL (e.g. a tunnel) or connect over loopback.",
+        "use an https URL, e.g. a tunnel, or connect over loopback.",
     );
     return {
       ok: false,
@@ -590,6 +594,20 @@ async function waitForGatewayReady(gatewayUrl: string): Promise<void> {
   }
 }
 
+export class GuardianLeasePermanentError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "GuardianLeasePermanentError";
+  }
+}
+
+function describeJsonType(value: unknown): string {
+  if (value === undefined) return "absent";
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+
 export async function leaseGuardianToken(
   gatewayUrl: string,
   assistantId: string,
@@ -621,7 +639,8 @@ export async function leaseGuardianToken(
     throw new Error(`guardian/init failed (${response.status}): ${body}`);
   }
 
-  const parsed = parseGuardianTokenFields(await response.json());
+  const rawBody: unknown = await response.json();
+  const parsed = parseGuardianTokenFields(rawBody);
   if (
     parsed.guardianPrincipalId == null ||
     parsed.accessToken == null ||
@@ -631,8 +650,21 @@ export async function leaseGuardianToken(
     parsed.refreshAfter == null ||
     parsed.isNew == null
   ) {
-    throw new Error(
-      `guardian/init returned a malformed token response (${response.status})`,
+    const raw = z.record(z.string(), z.unknown()).catch({}).parse(rawBody);
+    const requiredFields: (keyof typeof parsed)[] = [
+      "guardianPrincipalId",
+      "accessToken",
+      "accessTokenExpiresAt",
+      "refreshToken",
+      "refreshTokenExpiresAt",
+      "refreshAfter",
+      "isNew",
+    ];
+    const unusable = requiredFields
+      .filter((field) => parsed[field] == null)
+      .map((field) => `${field} arrived as ${describeJsonType(raw[field])}`);
+    throw new GuardianLeasePermanentError(
+      `guardian/init returned a malformed token response (${response.status}) — ${unusable.join(", ")}`,
     );
   }
   const tokenData: GuardianTokenData = {