@mycadet/cli 0.0.1 → 0.12.6-dev.202610072225.d7acd73

package/src/lib/cli-error.ts

@@ -0,0 +1,94 @@
+/**
+ * Structured CLI error reporting for upgrade/rollback commands.
+ *
+ * When a CLI command fails, it can emit a machine-readable JSON object
+ * prefixed with `CLI_ERROR:` to stderr so that consumers (e.g. the
+ * desktop app) can parse it reliably. Modeled after the DAEMON_ERROR
+ * protocol in `assistant/src/daemon/startup-error.ts`.
+ */
+
+/** Known error categories emitted by CLI commands. */
+export type CliErrorCategory =
+  | "CLI_UPDATE_FAILED"
+  | "DOCKER_NOT_RUNNING"
+  | "IMAGE_PULL_FAILED"
+  | "MISSING_VERSION"
+  | "READINESS_TIMEOUT"
+  | "ROLLBACK_FAILED"
+  | "ROLLBACK_NO_STATE"
+  | "VERSION_DIRECTION"
+  | "AUTH_FAILED"
+  | "NETWORK_ERROR"
+  | "UNSUPPORTED_TOPOLOGY"
+  | "ASSISTANT_NOT_FOUND"
+  | "PLATFORM_API_ERROR"
+  | "UNKNOWN";
+
+interface CliErrorPayload {
+  error: CliErrorCategory;
+  message: string;
+  detail?: string;
+}
+
+const CLI_ERROR_PREFIX = "CLI_ERROR:";
+
+/**
+ * Write a structured error line to stderr. The line is prefixed with
+ * `CLI_ERROR:` followed by JSON, making it unambiguous even if other
+ * stderr output precedes it.
+ */
+export function emitCliError(
+  category: CliErrorCategory,
+  message: string,
+  detail?: string,
+): void {
+  const payload: CliErrorPayload = { error: category, message, detail };
+  const line = `${CLI_ERROR_PREFIX}${JSON.stringify(payload)}`;
+  process.stderr.write(line + "\n");
+}
+
+/**
+ * Inspect an error string and return the most appropriate
+ * {@link CliErrorCategory} for common upgrade/rollback failures.
+ */
+export function categorizeUpgradeError(err: unknown): CliErrorCategory {
+  const msg = String(err).toLowerCase();
+
+  if (
+    msg.includes("cannot connect to the docker") ||
+    msg.includes("is docker running")
+  ) {
+    return "DOCKER_NOT_RUNNING";
+  }
+
+  if (
+    msg.includes("manifest unknown") ||
+    msg.includes("manifest not found") ||
+    msg.includes("pull access denied") ||
+    msg.includes("repository does not exist")
+  ) {
+    return "IMAGE_PULL_FAILED";
+  }
+
+  if (msg.includes("timeout") || msg.includes("readyz")) {
+    return "READINESS_TIMEOUT";
+  }
+
+  if (
+    msg.includes("401") ||
+    msg.includes("403") ||
+    msg.includes("unauthorized")
+  ) {
+    return "AUTH_FAILED";
+  }
+
+  if (
+    msg.includes("enotfound") ||
+    msg.includes("econnrefused") ||
+    msg.includes("network")
+  ) {
+    return "NETWORK_ERROR";
+  }
+
+  return "UNKNOWN";
+}

package/src/lib/client-identity.ts

@@ -0,0 +1,72 @@
+/**
+ * Stable per-install client identity for the CLI.
+ *
+ * Generates a UUID on first use and persists it to
+ * `~/.config/cadet/client-id` so the daemon's event hub can
+ * track this terminal across SSE reconnects and CLI restarts.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { randomUUID } from "crypto";
+import { homedir } from "os";
+import { join } from "path";
+
+export const CLI_INTERFACE_ID = "cli";
+export const WEB_INTERFACE_ID = "web";
+
+let cached: string | null = null;
+
+function getConfigDir(): string {
+  const configHome = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+  return join(configHome, "cadet");
+}
+
+/**
+ * Returns a stable UUID identifying this CLI installation.
+ * Generated once and persisted to `~/.config/cadet/client-id`.
+ */
+export function getClientId(): string {
+  if (cached) return cached;
+
+  const configDir = getConfigDir();
+  const idFile = join(configDir, "client-id");
+
+  try {
+    if (existsSync(idFile)) {
+      const stored = readFileSync(idFile, "utf-8").trim();
+      if (stored) {
+        cached = stored;
+        return stored;
+      }
+    }
+  } catch {
+    /* best-effort read */
+  }
+
+  const id = randomUUID();
+  try {
+    mkdirSync(configDir, { recursive: true });
+    writeFileSync(idFile, id, "utf-8");
+  } catch {
+    /* best-effort persist — transient id still works for this session */
+  }
+
+  cached = id;
+  return id;
+}
+
+/**
+ * Headers that identify this CLI client to the assistant daemon.
+ * Attach to all requests so the ClientRegistry can track connected
+ * clients and their capabilities.
+ *
+ * @param interfaceId - Override the interface ID (default: "cli").
+ */
+export function getClientRegistrationHeaders(
+  interfaceId: string = CLI_INTERFACE_ID,
+): Record<string, string> {
+  return {
+    "X-Cadet-Client-Id": getClientId(),
+    "X-Cadet-Interface-Id": interfaceId,
+  };
+}

package/src/lib/cloudflare-tunnel.ts

@@ -0,0 +1,232 @@
+import { execFileSync, spawn, type ChildProcess } from "node:child_process";
+
+import { GATEWAY_PORT } from "./constants.js";
+import {
+  clearIngressUrl,
+  getDefaultWorkspaceDir,
+  saveIngressUrl,
+} from "./ingress-config.js";
+
+// ── Cloudflare Tunnel ─────────────────────────────────────────────────────────
+
+const CLOUDFLARED_TIMEOUT_MS = 30_000;
+
+// Quick-tunnel hostnames follow the pattern <word>-<word>-<word>.trycloudflare.com
+const QUICK_TUNNEL_URL_RE = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/;
+
+/**
+ * Check whether cloudflared is installed and on PATH.
+ * Returns the version string if found, null otherwise.
+ */
+export function getCloudflareTunnelVersion(): string | null {
+  try {
+    const output = execFileSync("cloudflared", ["version"], {
+      encoding: "utf-8",
+      timeout: 5_000,
+      stdio: ["ignore", "pipe", "ignore"],
+      windowsHide: true,
+    });
+    return output.trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Spawn a cloudflared quick-tunnel process forwarding HTTP traffic to
+ * `targetPort`.  The child process writes its public URL to stderr during
+ * startup — use {@link waitForCloudflareTunnelUrl} to extract it.
+ */
+export function startCloudflareTunnelProcess(targetPort: number): ChildProcess {
+  return spawn(
+    "cloudflared",
+    ["tunnel", "--url", `http://localhost:${targetPort}`, "--no-autoupdate"],
+    // Keep stdio as pipes so we can parse the URL from output.
+    { stdio: ["ignore", "pipe", "pipe"], windowsHide: true },
+  );
+}
+
+/**
+ * Listen to a running cloudflared process's stdout/stderr and resolve with
+ * the public quick-tunnel URL once cloudflared prints it.
+ *
+ * cloudflared emits a line containing the trycloudflare.com URL during
+ * startup — typically within 5–15 seconds on a normal internet connection.
+ *
+ * Rejects when:
+ * - The URL does not appear within `timeoutMs`.
+ * - The child process exits before the URL is found.
+ */
+export function waitForCloudflareTunnelUrl(
+  child: ChildProcess,
+  timeoutMs: number = CLOUDFLARED_TIMEOUT_MS,
+): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(
+        new Error(
+          `cloudflared tunnel URL did not appear within ${timeoutMs / 1000}s. ` +
+            `Ensure cloudflared is working: try running 'cloudflared tunnel --url http://localhost:7840' manually.`,
+        ),
+      );
+    }, timeoutMs);
+
+    let resolved = false;
+
+    function scanLine(line: string): void {
+      if (resolved) return;
+      const match = QUICK_TUNNEL_URL_RE.exec(line);
+      if (match) {
+        resolved = true;
+        clearTimeout(timer);
+        resolve(match[0]);
+      }
+    }
+
+    // Buffer incomplete lines across chunks
+    let stdoutBuf = "";
+    let stderrBuf = "";
+
+    child.stdout?.on("data", (chunk: Buffer) => {
+      stdoutBuf += chunk.toString();
+      const lines = stdoutBuf.split("\n");
+      stdoutBuf = lines.pop() ?? "";
+      for (const line of lines) scanLine(line);
+    });
+
+    child.stderr?.on("data", (chunk: Buffer) => {
+      stderrBuf += chunk.toString();
+      const lines = stderrBuf.split("\n");
+      stderrBuf = lines.pop() ?? "";
+      for (const line of lines) scanLine(line);
+    });
+
+    child.on("exit", (code) => {
+      if (resolved) return;
+      clearTimeout(timer);
+      reject(
+        new Error(
+          `cloudflared exited with code ${code ?? "unknown"} before the tunnel URL appeared.`,
+        ),
+      );
+    });
+  });
+}
+
+/**
+ * Run the cloudflared quick-tunnel workflow:
+ * 1. Verify cloudflared is installed.
+ * 2. Start a quick tunnel pointing at the local edge port.
+ * 3. Parse the public URL from cloudflared output.
+ * 4. Persist the URL to the workspace config as the ingress base URL.
+ * 5. Block until the process exits or the user presses Ctrl+C.
+ * 6. Clear the ingress URL from config on exit.
+ *
+ * No Cloudflare account is required — quick tunnels are free and ephemeral.
+ */
+export interface RunCloudflareTunnelOptions {
+  /** Local edge port to forward. Defaults to the global GATEWAY_PORT. */
+  port?: number;
+  /** Workspace directory for config read/write. Defaults to ~/.cadet/workspace. */
+  workspaceDir?: string;
+  /** Lockfile entry to mirror the ingress URL onto (`ingressUrl`). */
+  assistantId?: string;
+}
+
+export async function runCloudflareTunnel(
+  opts: RunCloudflareTunnelOptions = {},
+): Promise<void> {
+  const version = 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);
+  }
+
+  console.log(`Using ${version}`);
+
+  const workspaceDir = opts.workspaceDir ?? getDefaultWorkspaceDir();
+  const port = opts.port ?? GATEWAY_PORT;
+
+  console.log(`Starting cloudflared quick tunnel to localhost:${port}...`);
+  console.log("No Cloudflare account required — quick tunnels are free.");
+  console.log("");
+
+  let publicUrl: string | undefined;
+  const child = startCloudflareTunnelProcess(port);
+
+  const cleanup = (): void => {
+    if (!child.killed) child.kill("SIGTERM");
+    if (publicUrl) {
+      console.log("\nClearing ingress URL from config...");
+      clearIngressUrl(workspaceDir, opts.assistantId);
+    }
+  };
+
+  process.on("SIGINT", () => {
+    cleanup();
+    process.exit(0);
+  });
+  process.on("SIGTERM", () => {
+    cleanup();
+    process.exit(0);
+  });
+
+  child.on("error", (err: Error) => {
+    console.error(`cloudflared process error: ${err.message}`);
+    process.exit(1);
+  });
+
+  child.on("exit", (code) => {
+    // Always clear the saved ingress URL when the tunnel process ends so
+    // webhook integrations don't keep hitting a dead endpoint.
+    if (publicUrl !== undefined) {
+      clearIngressUrl(workspaceDir, opts.assistantId);
+    }
+    if (code !== null && code !== 0) {
+      console.error(`\ncloudflared exited with code ${code}.`);
+      process.exit(1);
+    }
+  });
+
+  // Forward cloudflared output to the console so the user can see startup
+  // progress and any authentication errors.
+  child.stdout?.on("data", (data: Buffer) => {
+    const line = data.toString().trim();
+    if (line) console.log(`[cloudflared] ${line}`);
+  });
+  child.stderr?.on("data", (data: Buffer) => {
+    const line = data.toString().trim();
+    if (line) console.log(`[cloudflared] ${line}`);
+  });
+
+  try {
+    publicUrl = await waitForCloudflareTunnelUrl(child);
+  } catch (err) {
+    cleanup();
+    throw err;
+  }
+
+  console.log("");
+  console.log(`Tunnel established: ${publicUrl}`);
+  console.log(`Forwarding to:     localhost:${port}`);
+  console.log("");
+
+  saveIngressUrl(workspaceDir, publicUrl, opts.assistantId, "cloudflare");
+  console.log("Ingress URL saved to config.");
+  console.log("");
+  console.log("Press Ctrl+C to stop the tunnel and clear the ingress URL.");
+
+  // Keep running until cloudflared exits (e.g., network error or user Ctrl+C)
+  await new Promise<void>((resolve) => {
+    child.on("exit", () => resolve());
+  });
+}

package/src/lib/config-utils.ts

@@ -0,0 +1,98 @@
+import { writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+
+/**
+ * Convert flat dot-notation key=value pairs into a nested config object.
+ *
+ * e.g. {"llm.default.provider": "anthropic", "llm.default.model": "claude-opus-4-6"}
+ *   → {llm: {default: {provider: "anthropic", model: "claude-opus-4-6"}}}
+ */
+export function buildNestedConfig(
+  configValues: Record<string, string>,
+): Record<string, unknown> {
+  const config: Record<string, unknown> = {};
+  for (const [dotKey, value] of Object.entries(configValues)) {
+    const parts = dotKey.split(".");
+    let target: Record<string, unknown> = config;
+    for (let i = 0; i < parts.length - 1; i++) {
+      const part = parts[i];
+      const existing = target[part];
+      if (
+        existing == null ||
+        typeof existing !== "object" ||
+        Array.isArray(existing)
+      ) {
+        target[part] = {};
+      }
+      target = target[part] as Record<string, unknown>;
+    }
+    target[parts[parts.length - 1]] = value;
+  }
+  return config;
+}
+
+/**
+ * Ensure hatch always provides enough initial LLM config for the assistant to
+ * detect a fresh off-platform hatch and seed BYOK profiles.
+ *
+ * @deprecated Part of the workspace-config overlay path — a CLI→Assistant
+ * side channel that bypasses the Assistant's public APIs and has no
+ * equivalent in web/desktop. Two replacement paths are on the table:
+ *
+ *   1. Post-hatch API calls — the CLI calls public Assistant routes after
+ *      boot (`POST /v1/secrets`, plus a small read-only endpoint that
+ *      returns the canonical inference-profile templates so the CLI can
+ *      PATCH them in). See the closed alternatives in PR #32061 and
+ *      PR #32131 for the shape this would take.
+ *   2. Move inference-profile seeds out of workspace config and into
+ *      Assistant code, so there is nothing for the CLI to inject in the
+ *      first place.
+ *
+ * Either path removes the need for this helper.
+ */
+export function buildHatchConfigValues(
+  configValues: Record<string, string>,
+  provider: string | null | undefined,
+): Record<string, string> {
+  if (!provider || configValues["llm.default.provider"]) {
+    return configValues;
+  }
+
+  return {
+    ...configValues,
+    "llm.default.provider": provider,
+  };
+}
+
+/**
+ * Write arbitrary key-value pairs to a temporary JSON file and return its
+ * path. The caller is responsible for getting the file to the daemon — for
+ * the local hatch flow that means setting `CADET_DEFAULT_WORKSPACE_CONFIG_PATH`
+ * on the daemon process; for the Docker hatch flow the caller stages the
+ * file into the workspace volume so the rename-after-consume step in
+ * `mergeDefaultWorkspaceConfig` is a same-filesystem rename.
+ *
+ * Keys use dot-notation to address nested fields. For example:
+ *   "llm.default.provider" → {llm: {default: {provider: ...}}}
+ *   "llm.default.model"    → {llm: {default: {model: ...}}}
+ *
+ * Returns undefined when configValues is empty (nothing to write).
+ *
+ * @deprecated See {@link buildHatchConfigValues} for the replacement
+ * direction. This overlay path is a CLI→Assistant side channel and will be
+ * removed once one of the documented replacements lands.
+ */
+export function writeInitialConfig(
+  configValues: Record<string, string>,
+): string | undefined {
+  if (Object.keys(configValues).length === 0) return undefined;
+
+  const config = buildNestedConfig(configValues);
+  const tempPath = join(
+    tmpdir(),
+    `cadet-default-workspace-config-${process.pid}-${Date.now()}.json`,
+  );
+  writeFileSync(tempPath, JSON.stringify(config, null, 2) + "\n");
+  return tempPath;
+}

package/src/lib/confirm-action.ts

@@ -0,0 +1,61 @@
+/**
+ * Shared interactive confirmation for destructive CLI commands (retire, unpair,
+ * …). Per cli/AGENTS.md, a command that removes assistant state must print the
+ * resolved identity and require confirmation, with a `--yes` bypass for
+ * automation.
+ */
+
+/** True only when we can run an interactive raw-mode confirmation prompt. */
+export function canPromptForConfirmation(): boolean {
+  return (
+    process.stdin.isTTY === true &&
+    process.stdout.isTTY === true &&
+    typeof process.stdin.setRawMode === "function"
+  );
+}
+
+/**
+ * Show `prompt` and resolve true on Enter, false on Esc/q/Ctrl-C. Restores the
+ * prior stdin raw/paused state on exit. Caller must gate on
+ * {@link canPromptForConfirmation} first.
+ *
+ * `unref()`s stdin on cleanup so the resumed handle doesn't keep the process
+ * alive after the prompt resolves.
+ */
+export async function confirmAction(prompt: string): Promise<boolean> {
+  const stdin = process.stdin;
+  const stdout = process.stdout;
+  const wasRaw = stdin.isRaw === true;
+  const wasPaused = stdin.isPaused();
+
+  stdout.write(prompt);
+  stdin.setRawMode(true);
+  stdin.resume();
+
+  return await new Promise<boolean>((resolve) => {
+    const cleanup = () => {
+      stdin.off("data", onData);
+      stdin.setRawMode(wasRaw);
+      if (wasPaused) {
+        stdin.pause();
+      }
+      stdin.unref?.();
+      stdout.write("\n");
+    };
+
+    const onData = (chunk: Buffer) => {
+      const byte = chunk[0];
+      if (byte === 13 || byte === 10) {
+        cleanup();
+        resolve(true);
+        return;
+      }
+      if (byte === 27 || byte === 3 || byte === 113 || byte === 81) {
+        cleanup();
+        resolve(false);
+      }
+    };
+
+    stdin.on("data", onData);
+  });
+}

package/src/lib/constants.ts

@@ -0,0 +1,46 @@
+/**
+ * Canonical internal assistant ID used as the default/fallback across the CLI
+ * and daemon. Mirrors `DAEMON_INTERNAL_ASSISTANT_ID` from
+ * `assistant/src/runtime/assistant-scope.ts`.
+ */
+export const DAEMON_INTERNAL_ASSISTANT_ID = "self" as const;
+
+export const FIREWALL_TAG = "mycadet";
+export const GATEWAY_PORT = process.env.GATEWAY_PORT
+  ? Number(process.env.GATEWAY_PORT)
+  : 7830;
+
+/** Default ports used as scan start points for multi-instance allocation. */
+export const DEFAULT_DAEMON_PORT = 7821;
+export const DEFAULT_GATEWAY_PORT = 7830;
+export const DEFAULT_QDRANT_PORT = 6333;
+export const DEFAULT_CES_PORT = 8090;
+
+export const VALID_REMOTE_HOSTS = [
+  "local",
+  "docker",
+  "custom",
+  "cloud",
+] as const;
+export type RemoteHost = (typeof VALID_REMOTE_HOSTS)[number];
+const ANSI = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  magenta: "\x1b[35m",
+} as const;
+
+/** Hatch identity: the color shown while an assistant hatches. */
+export const HATCH_COLOR = ANSI.magenta;
+
+/** Hatch identity: the ASCII art shown while an assistant hatches. */
+export const HATCH_ART = [
+  `${ANSI.magenta}   .-.-.-.${ANSI.reset}`,
+  `${ANSI.magenta}  |${ANSI.reset}${ANSI.bold} o   o ${ANSI.reset}${ANSI.magenta}|${ANSI.reset}`,
+  `${ANSI.magenta}  |${ANSI.reset}${ANSI.bold}  ---  ${ANSI.reset}${ANSI.magenta}|${ANSI.reset}`,
+  `${ANSI.magenta}  |_|_|_|_|${ANSI.reset}`,
+  `${ANSI.magenta}   | | | |${ANSI.reset}`,
+  `${ANSI.magenta}   ^ ^_^ ^${ANSI.reset}`,
+];
+
+/** Hatch identity: emoji shown when an assistant has hatched. */
+export const HATCHED_EMOJI = "👾";