@mycadet/cli 0.12.8 → 0.12.9-dev.202610131620.d833e01

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

@@ -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`,

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

@@ -429,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,

package/src/lib/hatch-local.ts

@@ -21,6 +21,7 @@ import {
   setActiveAssistant,
 } from "./assistant-config.js";
 import type { AssistantEntry } from "./assistant-config.js";
+import { green, yellow } from "./color.js";
 import { buildHatchConfigValues, writeInitialConfig } from "./config-utils.js";
 import {
   generateLocalSigningKey,
@@ -379,14 +380,18 @@ export async function hatchLocal(
       ) {
         const delayMs = 2000 * 2 ** (attempt - 1);
         reporter.error(
-          `⚠️  Guardian token lease attempt ${attempt}/${maxLeaseAttempts} failed — retrying in ${delayMs / 1000}s: ${err}`,
+          yellow(
+            `⚠️  Guardian token lease attempt ${attempt}/${maxLeaseAttempts} failed — retrying in ${delayMs / 1000}s: ${err}`,
+          ),
         );
         await new Promise((r) => setTimeout(r, delayMs));
       } else {
         reporter.error(
-          `⚠️  Guardian token lease failed${err instanceof GuardianLeasePermanentError ? " (not retrying — a malformed 200 will not fix itself)" : ` after ${maxLeaseAttempts} attempts`}: ${err}\n` +
-            `   The assistant is running but guardian-token.json was not written.\n` +
-            `   Run \`cadet restart ${JSON.stringify(instanceName)} --repair-guardian\` to re-lease a token.`,
+          yellow(
+            `⚠️  Guardian token lease failed${err instanceof GuardianLeasePermanentError ? ", not retrying — a malformed 200 will not fix itself" : ` after ${maxLeaseAttempts} attempts`}: ${err}\n` +
+              `   The assistant is running but guardian-token.json was not written.\n` +
+              `   Run \`cadet restart ${JSON.stringify(instanceName)} --repair-guardian\` to re-lease a token.`,
+          ),
         );
       }
     }
@@ -398,8 +403,10 @@ export async function hatchLocal(
 
   if (provider !== undefined && provider !== null && !guardianAccessToken) {
     reporter.error(
-      `⚠️  Provider credential setup skipped because the guardian token was not leased.\n` +
-        `   The assistant is still hatched. Run \`cadet setup --provider ${provider}\` after fixing the connection.`,
+      yellow(
+        `⚠️  Provider credential setup skipped because the guardian token was not leased.\n` +
+          `   The assistant is still hatched. Run \`cadet setup --provider ${provider}\` after fixing the connection.`,
+      ),
     );
   } else if (provider !== undefined) {
     await configureHatchProviderApiKey({
@@ -429,7 +436,7 @@ export async function hatchLocal(
   }
 
   reporter.log("");
-  reporter.log(`✅ Local assistant hatched!`);
+  reporter.log(green(`✅ Local assistant hatched!`, process.stdout));
   printInstanceDetails(
     {
       name: instanceName,
@@ -438,7 +445,7 @@ export async function hatchLocal(
     },
     (message) => reporter.log(message),
   );
-  logHatchNextSteps((message) => reporter.log(message), verbose);
+  logHatchNextSteps((message) => reporter.log(message));
 
   const result: HatchLocalResult = {
     assistantId: instanceName,

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

@@ -1,12 +1,8 @@
-export function logHatchNextSteps(
-  log: (message: string) => void,
-  verbose = false,
-): void {
+export function logHatchNextSteps(log: (message: string) => void): void {
   log("Next steps:");
-  log("  cadet client");
-  if (verbose) {
-    log('  cadet message "hello"');
-    log("  cadet events");
-  }
+  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",
+  );
   log("");
 }

package/src/lib/job-polling.ts

@@ -166,7 +166,7 @@ export async function pollJobUntilDone(
         throw err;
       }
       const msg = err instanceof Error ? err.message : String(err);
-      console.warn(`${options.label} polling failed, retrying... (${msg})`);
+      console.warn(`${options.label} polling failed: ${msg}. Retrying...`);
       if (Date.now() >= deadline) {
         throw new Error(
           `Timed out waiting for ${options.label} after ${Math.round(

package/src/lib/local.ts

@@ -937,7 +937,7 @@ async function startDaemonWatchFromSource(
   }
   writeFileSync(pidFile, String(daemonPid), "utf-8");
 
-  console.log("   Assistant started in watch mode (bun --watch)");
+  console.log("   Assistant started in watch mode with bun --watch");
   return trackDaemonSpawn(child);
 }
 
@@ -984,6 +984,41 @@ function resolveGatewayDir(resources?: LocalInstanceResources): string {
   }
 }
 
+/**
+ * How to invoke a `gateway <subcommand>` CLI process so it resolves the same
+ * workspace AND gateway security dir as the locally spawned gateway server:
+ * run the gateway package's CLI entry through bun with the spawn state root
+ * as cwd and the instance-pinned CADET_WORKSPACE_DIR / GATEWAY_SECURITY_DIR
+ * the server was given (the file-backed pairing store must resolve
+ * identically in both processes). Callers pass the resolved assistant
+ * entry's `resources` (undefined for the default instance, where both
+ * processes fall back to the same cwd-relative paths).
+ */
+export function gatewayCliInvocation(resources?: LocalInstanceResources): {
+  command: string;
+  args: string[];
+  cwd: string;
+  env: Record<string, string | undefined>;
+} {
+  return {
+    command: resolveBunExecutable(),
+    args: ["run", join(resolveGatewayDir(resources), "src/cli/index.ts")],
+    cwd: spawnStateRoot(),
+    env: {
+      ...process.env,
+      ...(resources
+        ? {
+            CADET_WORKSPACE_DIR: join(resources.instanceDir, "workspace"),
+            GATEWAY_SECURITY_DIR: join(
+              resources.instanceDir,
+              "gateway-security",
+            ),
+          }
+        : {}),
+    },
+  };
+}
+
 function resolveCesDir(resources?: LocalInstanceResources): string {
   const runtimeCesDir = localRuntimeCesDir(resources);
   if (runtimeCesDir) return runtimeCesDir;
@@ -1118,9 +1153,7 @@ export async function startCes(
     // Source tree / bunx: run the CES entry point via bun.
     const cesDir = runtimeCesDir ?? resolveCesDir(resources);
     const cesEntry = join(cesDir, "src/main.ts");
-    const bunArgs = watch
-      ? ["--watch", "run", cesEntry]
-      : ["run", cesEntry];
+    const bunArgs = watch ? ["--watch", "run", cesEntry] : ["run", cesEntry];
     const cesLogFd = openLogFile("hatch.log");
     ces = spawn(resolveBunExecutable(), bunArgs, {
       cwd: spawnStateRoot(),

package/src/lib/nginx-ingress.ts

@@ -177,8 +177,6 @@ function remoteWebIngressConfig(
   return {
     remote: EDGE_SERVED_REMOTE,
     apiBaseUrl: "/v1",
-    cloudDisabled: true,
-    disableCloud: true,
     ...(opts.assistantName ? { assistantName: opts.assistantName } : {}),
     ...(opts.assistantId ? { assistantId: opts.assistantId } : {}),
     ...(opts.hubUrl ? { hubUrl: opts.hubUrl } : {}),
@@ -191,7 +189,7 @@ function remoteWebIngressConfig(
  * fingerprint matches, so this must change whenever the generated index or
  * nginx template does.
  */
-export const EDGE_TEMPLATE_VERSION = 9;
+export const EDGE_TEMPLATE_VERSION = 10;
 
 /**
  * Stable fingerprint of the SPA config injected into the served index and
@@ -1162,13 +1160,13 @@ export async function ensureTunnelEdge(opts: {
     case "nginx-missing":
       throw new Error(
         "nginx is not installed, so the tunnel edge cannot start. " +
-          "Install it (macOS: `brew install nginx`, Linux: `sudo apt install nginx`) " +
+          "See https://nginx.org/en/docs/install.html for how to install, " +
           "or point NGINX_BIN at an existing binary.",
       );
     case "web-dist-missing":
       throw new Error(
         "Unable to locate built web assets for the remote web edge. " +
-          "Build the SPA (`cd clients/web && VITE_CLOUD_MODE=false bun run build`) " +
+          "Build the SPA with `cd clients/web && VITE_CLOUD_MODE=false bun run build`, " +
           "or install @mycadet/web so its packaged dist directory is available.",
       );
     case "unreachable":

package/src/lib/pair.ts

@@ -50,6 +50,6 @@ export function formatWebApproveFailure(
   return [
     `${rejection} ${gatewayUrl} (assistant "${assistantReference}", environment "${envName}").`,
     `Codes are minted by the gateway that serves the pair page, expire after ${CODE_TTL_MINUTES} minutes, and are single-use.`,
-    "If the pair page came from a different assistant or environment (e.g. the desktop app's), re-run with that environment's CADET_ENVIRONMENT and that assistant's name.",
+    "If the pair page came from a different assistant or environment, such as the desktop app's, re-run with that environment's CADET_ENVIRONMENT and that assistant's name.",
   ].join("\n");
 }

package/src/lib/step-runner.ts

@@ -112,11 +112,16 @@ export function execWithStdin(
 export function execOutput(
   command: string,
   args: string[],
-  options: { cwd?: string; timeoutMs?: number } = {},
+  options: {
+    cwd?: string;
+    timeoutMs?: number;
+    env?: Record<string, string | undefined>;
+  } = {},
 ): Promise<string> {
   return new Promise((resolve, reject) => {
     const child = spawn(command, args, {
       cwd: options.cwd,
+      env: options.env,
       stdio: ["pipe", "pipe", "pipe"],
       windowsHide: true,
     });

package/src/lib/sync-cloud-assistants.ts

@@ -88,7 +88,7 @@ export async function syncCloudAssistants(
     log?.("Fetching Cadet Cloud assistants…");
     cloudAssistants = await fetchCloudAssistants(token);
     log?.(
-      `Cadet Cloud returned ${cloudAssistants.length} assistant(s): ${cloudAssistants.map((a) => a.name || a.id).join(", ") || "(none)"}`,
+      `Cadet Cloud returned ${cloudAssistants.length} ${cloudAssistants.length === 1 ? "assistant" : "assistants"}: ${cloudAssistants.map((a) => a.name || a.id).join(", ") || "(none)"}`,
     );
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
@@ -118,7 +118,7 @@ export async function syncCloudAssistants(
   );
   const existingCloudIds = new Set(existingCloudById.keys());
   log?.(
-    `Lockfile has ${existingCloudIds.size} cloud assistant(s): ${[...existingCloudIds].join(", ") || "(none)"}`,
+    `Lockfile has ${existingCloudIds.size} ${existingCloudIds.size === 1 ? "cloud assistant" : "cloud assistants"}: ${[...existingCloudIds].join(", ") || "(none)"}`,
   );
 
   let added = 0;

package/src/lib/tunnels/cloudflare.ts

@@ -2,6 +2,8 @@ import type { ProviderMeta, ProviderTunnelResult } from "../tunnel.js";
 
 import { execFileSync, spawn, type ChildProcess } from "node:child_process";
 
+import { ensureBinaryInstalled } from "../ensure-binary.js";
+
 import { GATEWAY_PORT } from "../constants.js";
 import {
   clearIngressUrl,
@@ -138,18 +140,26 @@ export interface RunCloudflareTunnelOptions {
 export async function runCloudflareTunnel(
   opts: RunCloudflareTunnelOptions = {},
 ): Promise<ProviderTunnelResult> {
-  const version = getCloudflareTunnelVersion();
+  const version = await ensureBinaryInstalled({
+    binary: "cloudflared",
+    purpose: "the cloudflare tunnel",
+    packages: {
+      brew: ["brew", "install", "cloudflare/cloudflare/cloudflared"],
+      winget: [
+        "winget",
+        "install",
+        "--silent",
+        "--accept-package-agreements",
+        "--accept-source-agreements",
+        "Cloudflare.cloudflared",
+      ],
+      choco: ["choco", "install", "-y", "cloudflared"],
+    },
+    manualHint:
+      "See https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/ for how to install",
+    probe: getCloudflareTunnelVersion,
+  });
   if (!version) {
-    console.error("Error: cloudflared is not installed.");
-    console.error("");
-    console.error("Install cloudflared:");
-    console.error("  macOS:   brew install cloudflare/cloudflare/cloudflared");
-    console.error("  Linux:   https://pkg.cloudflare.com/index.html");
-    console.error(
-      "  Windows: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/",
-    );
-    console.error("");
-    console.error("No Cloudflare account is required for quick tunnels.");
     process.exit(1);
   }