@mycadet/cli 0.0.1 → 0.12.6-dev.202610080043.b727a33

package/src/lib/random-name.ts

@@ -0,0 +1,146 @@
+import { customAlphabet } from "nanoid";
+
+const nanoidLower = customAlphabet("abcdefghijklmnopqrstuvwxyz0123456789", 6);
+
+const ADJECTIVES = [
+  "brave",
+  "calm",
+  "eager",
+  "fair",
+  "glad",
+  "keen",
+  "bold",
+  "cool",
+  "fast",
+  "warm",
+  "wise",
+  "kind",
+  "pure",
+  "safe",
+  "true",
+  "wild",
+  "free",
+  "deep",
+  "firm",
+  "soft",
+  "rich",
+  "rare",
+  "slim",
+  "vast",
+  "neat",
+  "pale",
+  "dark",
+  "lean",
+  "raw",
+  "dry",
+  "bright",
+  "crisp",
+  "deft",
+  "faint",
+  "grand",
+  "hale",
+  "just",
+  "lush",
+  "mild",
+  "prime",
+  "quick",
+  "sharp",
+  "stark",
+  "swift",
+  "tame",
+  "tight",
+  "vivid",
+  "plush",
+  "dense",
+  "lucid",
+  "fresh",
+  "fleet",
+  "stout",
+  "brisk",
+  "clear",
+  "quiet",
+  "noble",
+  "sleek",
+  "agile",
+  "spry",
+];
+
+const NOUNS = [
+  "fox",
+  "owl",
+  "elk",
+  "ant",
+  "bee",
+  "ram",
+  "eel",
+  "cod",
+  "jay",
+  "yak",
+  "bat",
+  "cub",
+  "doe",
+  "hen",
+  "kit",
+  "pup",
+  "ray",
+  "tern",
+  "wren",
+  "lark",
+  "hawk",
+  "dove",
+  "lynx",
+  "hare",
+  "frog",
+  "newt",
+  "crab",
+  "moth",
+  "seal",
+  "toad",
+  "wolf",
+  "bear",
+  "deer",
+  "swan",
+  "crane",
+  "finch",
+  "robin",
+  "otter",
+  "mink",
+  "vole",
+  "shrew",
+  "pike",
+  "bass",
+  "trout",
+  "perch",
+  "stork",
+  "egret",
+  "heron",
+  "snipe",
+  "quail",
+  "raven",
+  "swift",
+  "grouse",
+  "ibis",
+  "mole",
+  "asp",
+  "koi",
+  "gnu",
+  "dace",
+  "skua",
+];
+
+function randomElement<T>(arr: T[]): T {
+  return arr[Math.floor(Math.random() * arr.length)];
+}
+
+export function generateRandomSuffix(): string {
+  return `${randomElement(ADJECTIVES)}-${randomElement(NOUNS)}-${nanoidLower()}`;
+}
+
+/**
+ * Generate an instance name for a new assistant. Uses the explicit name if
+ * provided, otherwise generates `<adjective>-<noun>-<nanoid>`.
+ */
+export function generateInstanceName(explicitName?: string | null): string {
+  if (explicitName) return explicitName;
+  return generateRandomSuffix();
+}

package/src/lib/retire-apple-container.ts

@@ -0,0 +1,104 @@
+import { createConnection } from "net";
+import { existsSync } from "fs";
+
+import type { AssistantEntry } from "./assistant-config.js";
+
+/**
+ * Retire an Apple Container assistant by sending a retire command to the
+ * macOS app via the management socket. The app handles the full lifecycle:
+ * stop the pod, archive the instance directory, remove the guardian token,
+ * deregister from the platform, and remove the lockfile entry.
+ */
+export async function retireAppleContainer(
+  name: string,
+  entry: AssistantEntry,
+): Promise<void> {
+  console.log(
+    `\u{1F5D1}\ufe0f  Retiring Apple Container assistant '${name}'...\n`,
+  );
+
+  const mgmtSocket = entry.mgmtSocket as string | undefined;
+  if (!mgmtSocket) {
+    console.error(
+      `No management socket found for '${name}'.\n` +
+        "The assistant may not be running. If the macOS app is closed, " +
+        "open it and try again.",
+    );
+    process.exit(1);
+  }
+
+  if (!existsSync(mgmtSocket)) {
+    console.error(
+      `Management socket not found at ${mgmtSocket}.\n` +
+        "The assistant may have been stopped. Open the macOS app and try again.",
+    );
+    process.exit(1);
+  }
+
+  const handshake = JSON.stringify({ action: "retire" }) + "\n";
+
+  return new Promise<void>((resolve, reject) => {
+    const socket = createConnection({ path: mgmtSocket }, () => {
+      socket.write(handshake);
+    });
+
+    const TIMEOUT_MS = 30_000;
+    const chunks: Buffer[] = [];
+    let totalLen = 0;
+
+    socket.setTimeout(TIMEOUT_MS);
+    socket.on("timeout", () => {
+      console.error(
+        "Timed out waiting for retire response from the macOS app.",
+      );
+      socket.destroy();
+      process.exit(1);
+    });
+
+    socket.on("data", (data: Buffer) => {
+      chunks.push(data);
+      totalLen += data.length;
+      const accumulated = Buffer.concat(chunks, totalLen);
+      const nlIndex = accumulated.indexOf(0x0a);
+      if (nlIndex === -1) return;
+
+      const responseLine = accumulated.slice(0, nlIndex).toString("utf-8");
+      socket.destroy();
+
+      let response: { status: string; message?: string };
+      try {
+        response = JSON.parse(responseLine) as {
+          status: string;
+          message?: string;
+        };
+      } catch {
+        reject(new Error("Invalid response from management socket."));
+        return;
+      }
+
+      if (response.status === "ok") {
+        console.log(`\u2705 Apple Container assistant '${name}' retired.`);
+        resolve();
+      } else {
+        reject(
+          new Error(`Retire failed: ${response.message || "unknown error"}`),
+        );
+      }
+    });
+
+    socket.on("error", (err) => {
+      reject(new Error(`Management socket error: ${err.message}`));
+    });
+
+    socket.on("end", () => {
+      if (chunks.length === 0) {
+        reject(
+          new Error(
+            "Management socket closed without responding. " +
+              "The macOS app may have crashed during retire.",
+          ),
+        );
+      }
+    });
+  });
+}

package/src/lib/retire-archive.ts

@@ -0,0 +1,73 @@
+import { mkdirSync } from "fs";
+import { homedir } from "os";
+import { join, posix, win32 } from "path";
+
+function isPathInside(
+  parent: string,
+  candidate: string,
+  pathApi: typeof posix,
+): boolean {
+  const relativePath = pathApi.relative(parent, candidate);
+  return (
+    relativePath !== "" &&
+    relativePath !== ".." &&
+    !relativePath.startsWith(`..${pathApi.sep}`) &&
+    !pathApi.isAbsolute(relativePath)
+  );
+}
+
+export function getRetiredDir(): string {
+  const xdgData =
+    process.env.XDG_DATA_HOME?.trim() || join(homedir(), ".local", "share");
+  const dir = join(xdgData, "cadet", "retired");
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/** Throws if the name contains path separators or traversal segments. */
+export function validateAssistantName(name: string): void {
+  if (
+    !name ||
+    name.includes("/") ||
+    name.includes("\\") ||
+    name === ".." ||
+    name === "."
+  ) {
+    throw new Error(`Invalid assistant name: '${name}'`);
+  }
+}
+
+function safeName(
+  assistantId: string,
+  retiredDir: string,
+  pathApi: typeof posix,
+): string {
+  validateAssistantName(assistantId);
+  // Canonicalize and verify the result stays inside the retired directory
+  const candidate = pathApi.resolve(retiredDir, pathApi.basename(assistantId));
+  if (!isPathInside(retiredDir, candidate, pathApi)) {
+    throw new Error(`Invalid assistant name: '${assistantId}'`);
+  }
+  return pathApi.basename(assistantId);
+}
+
+export function resolveRetiredFilePath(
+  assistantId: string,
+  extension: "tar.gz" | "json",
+  retiredDir: string,
+  hostPlatform: NodeJS.Platform = process.platform,
+): string {
+  const pathApi = hostPlatform === "win32" ? win32 : posix;
+  return pathApi.join(
+    retiredDir,
+    `${safeName(assistantId, retiredDir, pathApi)}.${extension}`,
+  );
+}
+
+export function getArchivePath(assistantId: string): string {
+  return resolveRetiredFilePath(assistantId, "tar.gz", getRetiredDir());
+}
+
+export function getMetadataPath(assistantId: string): string {
+  return resolveRetiredFilePath(assistantId, "json", getRetiredDir());
+}

package/src/lib/retire-local.ts

@@ -0,0 +1,231 @@
+import { spawn } from "child_process";
+import { homedir } from "os";
+import { existsSync, mkdirSync, renameSync, writeFileSync } from "fs";
+import { basename, dirname, join, win32 } from "path";
+
+import {
+  getDaemonPidPath,
+  loadAllAssistants,
+  loadAllAssistantsAcrossEnvs,
+} from "./assistant-config.js";
+import type { AssistantEntry } from "./assistant-config.js";
+import { stopIngressNginx } from "./nginx-ingress.js";
+import { getKnownPidsFromAssistants } from "./orphan-detection.js";
+import {
+  DAEMON_STOP_TIMEOUT_MS,
+  stopOrphanedDaemonProcesses,
+  stopProcessByPidFile,
+} from "./process.js";
+import { getArchivePath, getMetadataPath } from "./retire-archive.js";
+import {
+  consoleLifecycleReporter,
+  type LifecycleReporter,
+} from "./lifecycle-reporter.js";
+
+export interface RetireLocalResult {
+  assistantId: string;
+  /** Whether the instance data directory was archived (false when skipped). */
+  archived: boolean;
+  /** Path to the background tar archive, when archiving was started. */
+  archivePath?: string;
+  /** True when another local assistant shared the data dir, so it was kept. */
+  sharedDataDir?: boolean;
+}
+
+interface RetireArchiveCommand {
+  command: string;
+  args: string[];
+  env?: Record<string, string>;
+}
+
+const WINDOWS_RETIRE_ARCHIVE_SCRIPT = [
+  "$ErrorActionPreference = 'Stop'",
+  "& tar.exe -czf $env:CADET_RETIRE_ARCHIVE_PATH -C $env:CADET_RETIRE_ARCHIVE_PARENT $env:CADET_RETIRE_STAGING_NAME",
+  "if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }",
+  "Remove-Item -LiteralPath $env:CADET_RETIRE_STAGING_DIR -Recurse -Force",
+].join("; ");
+
+export function getRetireArchiveCommand(
+  archivePath: string,
+  stagingDir: string,
+  hostPlatform: NodeJS.Platform = process.platform,
+): RetireArchiveCommand {
+  const archiveParent =
+    hostPlatform === "win32" ? win32.dirname(stagingDir) : dirname(stagingDir);
+  const stagingName =
+    hostPlatform === "win32"
+      ? win32.basename(stagingDir)
+      : basename(stagingDir);
+  if (hostPlatform === "win32") {
+    return {
+      command: "powershell.exe",
+      args: [
+        "-NoProfile",
+        "-NonInteractive",
+        "-Command",
+        WINDOWS_RETIRE_ARCHIVE_SCRIPT,
+      ],
+      env: {
+        CADET_RETIRE_ARCHIVE_PATH: archivePath,
+        CADET_RETIRE_ARCHIVE_PARENT: archiveParent,
+        CADET_RETIRE_STAGING_NAME: stagingName,
+        CADET_RETIRE_STAGING_DIR: stagingDir,
+      },
+    };
+  }
+  return {
+    command: "sh",
+    args: [
+      "-c",
+      'tar czf "$1" -C "$2" "$3" && rm -rf "$4"',
+      "cadet-retire",
+      archivePath,
+      archiveParent,
+      stagingName,
+      stagingDir,
+    ],
+  };
+}
+
+export async function retireLocal(
+  name: string,
+  entry: AssistantEntry,
+  reporter: LifecycleReporter = consoleLifecycleReporter,
+): Promise<RetireLocalResult> {
+  reporter.log("\u{1F5D1}\ufe0f  Stopping local assistant...\n");
+
+  if (!entry.resources) {
+    throw new Error(
+      `Local assistant '${name}' is missing resource configuration. Re-hatch to fix.`,
+    );
+  }
+  const resources = entry.resources;
+  const cadetDir = join(resources.instanceDir, ".cadet");
+
+  // Check whether another local assistant shares the same data directory.
+  const otherSharesDir = loadAllAssistants().some((other) => {
+    if (other.cloud !== "local") return false;
+    if (other.assistantId === name) return false;
+    if (!other.resources) return false;
+    const otherCadetDir = join(other.resources.instanceDir, ".cadet");
+    return otherCadetDir === cadetDir;
+  });
+
+  if (otherSharesDir) {
+    reporter.log(
+      `   Skipping process stop and archive — another local assistant shares ${cadetDir}.`,
+    );
+    reporter.log("\u2705 Local instance retired (config entry removed only).");
+    return { assistantId: name, archived: false, sharedDataDir: true };
+  }
+
+  const daemonPidFile = getDaemonPidPath(resources);
+  const daemonStopped = await stopProcessByPidFile(
+    daemonPidFile,
+    "daemon",
+    undefined,
+    DAEMON_STOP_TIMEOUT_MS,
+  );
+
+  // Stop gateway via PID file — use a longer timeout because the gateway has a
+  // drain window (5s) before it exits.
+  const gatewayPidFile = join(cadetDir, "gateway.pid");
+  await stopProcessByPidFile(gatewayPidFile, "gateway", undefined, 7000);
+
+  // Stop the CES sibling — it is stopped by its PID file, a no-op when the
+  // PID file is absent (e.g. the sibling was never started or already exited).
+  const cesPidFile = join(cadetDir, "ces.pid");
+  const cesStopped = await stopProcessByPidFile(
+    cesPidFile,
+    "credential-executor",
+  );
+  if (cesStopped) {
+    reporter.log("credential-executor stopped.");
+  }
+
+  // Stop Qdrant. The daemon's graceful shutdown tries to stop it via
+  // qdrantManager.stop(), but a daemon that never completes that shutdown
+  // (crash, OOM kill, or the SIGKILL ceiling above) leaves Qdrant running as
+  // an orphan. Check both the current PID file location and the legacy one.
+  const qdrantPidFile = join(
+    cadetDir,
+    "workspace",
+    "data",
+    "qdrant",
+    "qdrant.pid",
+  );
+  const qdrantLegacyPidFile = join(cadetDir, "qdrant.pid");
+  await stopProcessByPidFile(qdrantPidFile, "qdrant", undefined, 5000);
+  await stopProcessByPidFile(qdrantLegacyPidFile, "qdrant", undefined, 5000);
+
+  // Stop the nginx ingress if one is fronting this gateway — it would
+  // otherwise be orphaned when the instance directory is archived.
+  await stopIngressNginx(join(cadetDir, "workspace"));
+
+  // If the PID file didn't track a running daemon, scan for orphaned
+  // daemon processes that may have been started without writing a PID.
+  if (!daemonStopped) {
+    const otherAssistantPids = getKnownPidsFromAssistants(
+      [...loadAllAssistantsAcrossEnvs(), ...loadAllAssistants()].filter(
+        (other) =>
+          other.assistantId !== name ||
+          other.resources?.instanceDir !== resources.instanceDir,
+      ),
+    );
+    await stopOrphanedDaemonProcesses(otherAssistantPids);
+  }
+
+  // For named instances (instanceDir differs from the base directory),
+  // archive and remove the entire instance directory. For the default
+  // instance, archive only the .cadet subdirectory.
+  const isNamedInstance = resources.instanceDir !== homedir();
+  const dirToArchive = isNamedInstance ? resources.instanceDir : cadetDir;
+
+  // Move the data directory out of the way so the path is immediately available
+  // for the next hatch, then kick off the tar archive in the background.
+  const archivePath = getArchivePath(name);
+  const metadataPath = getMetadataPath(name);
+  const stagingDir = `${archivePath}.staging`;
+
+  if (!existsSync(dirToArchive)) {
+    reporter.log(
+      `   No data directory at ${dirToArchive} — nothing to archive.`,
+    );
+    reporter.log("\u2705 Local instance retired.");
+    return { assistantId: name, archived: false };
+  }
+
+  // Ensure the retired archive directory exists before attempting the rename
+  mkdirSync(dirname(stagingDir), { recursive: true });
+
+  try {
+    renameSync(dirToArchive, stagingDir);
+  } catch (err) {
+    // Re-throw so the caller (and the desktop app) knows the archive failed.
+    // If the rename fails, old workspace data stays in place and a subsequent
+    // hatch would inherit stale SOUL.md, IDENTITY.md, and memories.
+    throw new Error(
+      `Failed to archive ${dirToArchive}: ${err instanceof Error ? err.message : err}`,
+    );
+  }
+
+  writeFileSync(metadataPath, JSON.stringify(entry, null, 2) + "\n");
+
+  // Spawn tar + cleanup in the background and detach so the CLI can exit
+  // immediately. The staging directory is removed once the archive is written.
+  const archiveCommand = getRetireArchiveCommand(archivePath, stagingDir);
+  const child = spawn(archiveCommand.command, archiveCommand.args, {
+    stdio: "ignore",
+    detached: true,
+    windowsHide: true,
+    ...(archiveCommand.env
+      ? { env: { ...process.env, ...archiveCommand.env } }
+      : {}),
+  });
+  child.unref();
+
+  reporter.log(`📦 Archiving to ${archivePath} in the background.`);
+  reporter.log("\u2705 Local instance retired.");
+
+  return { assistantId: name, archived: true, archivePath };
+}

package/src/lib/runtime-url.ts

@@ -0,0 +1,143 @@
+import { isManagedCloud } from "./managed-cloud.js";
+import { hostname } from "node:os";
+
+import { getLocalLanIPv4 } from "./local";
+import type { AssistantEntry } from "./assistant-config.js";
+
+/**
+ * Resolve the URL for a runtime migration endpoint, taking the assistant's
+ * topology into account.
+ *
+ * - For local/docker assistants, `runtimeUrl` is the loopback gateway and
+ *   the runtime serves `/v1/migrations/<subpath>` directly. The CLI hits
+ *   that path with guardian-token bearer auth.
+ * - For platform-managed (cloud="cadet") assistants, `runtimeUrl` is the
+ *   platform host (e.g. `https://cloud.mycadet.ai`). The platform's
+ *   `MigrationViewSet` does NOT expose `export-to-gcs` or arbitrary runtime
+ *   migration paths under `/v1/migrations/...`. The wildcard runtime proxy
+ *   at `/v1/assistants/<id>/<path:rest>` is what forwards arbitrary runtime
+ *   paths to the managed runtime — vembda's unified proxy bootstraps the
+ *   guardian token internally for the runtime call. From the CLI side it's
+ *   user-session auth.
+ *
+ * The `subpath` is appended to the migrations namespace verbatim
+ * (e.g. `"export-to-gcs"`, `"import-from-gcs"`, `\`jobs/${jobId}\``).
+ */
+export function resolveRuntimeMigrationUrl(
+  entry: Pick<AssistantEntry, "cloud" | "runtimeUrl" | "assistantId">,
+  subpath: string,
+): string {
+  if (isManagedCloud(entry.cloud)) {
+    return `${entry.runtimeUrl}/v1/assistants/${entry.assistantId}/migrations/${subpath}`;
+  }
+  return `${entry.runtimeUrl}/v1/migrations/${subpath}`;
+}
+
+/**
+ * Resolve the URL for a generic runtime endpoint under `/v1/<subpath>`,
+ * taking the assistant's topology into account.
+ *
+ * - For local/docker assistants, `runtimeUrl` is the loopback gateway and
+ *   the runtime serves `/v1/<subpath>` directly.
+ * - For platform-managed (cloud="cadet") assistants the path is rewritten
+ *   to the wildcard runtime proxy:
+ *   `{platformUrl}/v1/assistants/<assistantId>/<subpath>`.
+ *
+ * The `subpath` is appended verbatim (e.g. `"identity"`).
+ */
+export function resolveRuntimeUrl(
+  entry: Pick<AssistantEntry, "cloud" | "runtimeUrl" | "assistantId">,
+  subpath: string,
+): string {
+  if (isManagedCloud(entry.cloud)) {
+    return `${entry.runtimeUrl}/v1/assistants/${entry.assistantId}/${subpath}`;
+  }
+  return `${entry.runtimeUrl}/v1/${subpath}`;
+}
+
+/**
+ * If the hostname in `url` matches this machine's local DNS name, LAN IP, or
+ * raw hostname, replace it with 127.0.0.1 so the client avoids mDNS round-trips
+ * when talking to an assistant running on the same machine. Trailing slashes are
+ * stripped on a swap. Returns the input unchanged if it doesn't parse as a URL.
+ */
+function maybeSwapToLocalhost(url: string): string {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return url;
+  }
+
+  const urlHost = parsed.hostname.toLowerCase();
+
+  const localNames: string[] = [];
+
+  const host = hostname();
+  if (host) {
+    localNames.push(host.toLowerCase());
+    // Also consider the bare name without .local suffix
+    if (host.toLowerCase().endsWith(".local")) {
+      localNames.push(host.toLowerCase().slice(0, -".local".length));
+    }
+  }
+
+  const lanIp = getLocalLanIPv4();
+  if (lanIp) {
+    localNames.push(lanIp);
+  }
+
+  if (localNames.includes(urlHost)) {
+    parsed.hostname = "127.0.0.1";
+    return parsed.toString().replace(/\/+$/, "");
+  }
+
+  return url;
+}
+
+/**
+ * Canonical form of a runtime/base URL used throughout the CLI: trailing
+ * slashes stripped, then localhost-swapped. This is exactly the transform
+ * `cadet client` applies to the runtime URL it hands the TUI, so comparing two
+ * URLs after passing both through this function is a like-for-like comparison.
+ */
+export function normalizeRuntimeUrl(url: string): string {
+  return maybeSwapToLocalhost(url.replace(/\/+$/, ""));
+}
+
+/**
+ * SECURITY: decide whether a guardian-token refresh may be sent to
+ * `candidateUrl`, and to which URL it should actually go.
+ *
+ * `cadet client` lets `--url`/`-u` override the runtime URL while still reusing
+ * the selected entry's stored guardian token, so a victim pointed at an
+ * attacker-controlled (or poisoned/redirected) URL must NOT cause us to POST the
+ * long-lived refreshToken + deviceId there. Refresh is permitted only when
+ * `candidateUrl` normalizes to one of the entry's persisted URLs (`localUrl`,
+ * which the CLI prefers when present, or `runtimeUrl`).
+ *
+ * Returns the persisted URL that the candidate matched — never the
+ * caller-supplied `candidateUrl` verbatim — so credentials only ever reach a
+ * trusted origin even if a caller forgets to use this return value. The matched
+ * URL is preferred over always returning `runtimeUrl` so the refresh stays on
+ * the same interface the session is using: e.g. a local entry may persist both a
+ * loopback `localUrl` (which `cadet client` defaults to) and an externally
+ * discovered `runtimeUrl`, and refreshing the loopback session against the
+ * external address could be unreachable or needlessly cross the public
+ * interface. Returns `null` when the candidate is untrusted (caller must skip
+ * the refresh).
+ */
+export function trustedRefreshUrl(
+  entry: Pick<AssistantEntry, "runtimeUrl" | "localUrl">,
+  candidateUrl: string,
+): string | null {
+  const candidate = normalizeRuntimeUrl(candidateUrl);
+  // localUrl first: it's what the CLI prefers when present, so the candidate is
+  // most likely to match it, and we want to keep the refresh on that interface.
+  for (const persisted of [entry.localUrl, entry.runtimeUrl]) {
+    if (persisted && normalizeRuntimeUrl(persisted) === candidate) {
+      return persisted;
+    }
+  }
+  return null;
+}