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

package/src/lib/environments/paths.ts

@@ -0,0 +1,138 @@
+import { homedir } from "os";
+import { join } from "path";
+
+import type { EnvironmentDefinition, PortMap } from "@mycadet/environments";
+import {
+  resolveAssistantsDir,
+  resolveConfigDirPaths,
+  resolveLockfilePaths,
+  resolveLogDir,
+  resolveRuntimeDir,
+  type LocalPathOptions,
+} from "@mycadet/local-mode";
+
+const DEFAULT_PORTS: Readonly<PortMap> = {
+  daemon: 7821,
+  gateway: 7830,
+  qdrant: 6333,
+  ces: 8090,
+  outboundProxy: 8080,
+  tcp: 8765,
+};
+
+/**
+ * Config directory for an environment.
+ * Production preserves the existing `~/.config/cadet/` location;
+ * non-production environments use `$XDG_CONFIG_HOME/cadet-<env>/`.
+ */
+export function getConfigDir(env: EnvironmentDefinition): string {
+  return getConfigDirs(env)[0]!;
+}
+
+export function getConfigDirs(env: EnvironmentDefinition): string[] {
+  return resolveConfigDirPaths(process.env, localPathOptions(env));
+}
+
+/**
+ * Lockfile candidate paths for an environment, in priority order.
+ *
+ * For production, returns both the current `.cadet.lock.json` and the
+ * legacy `.cadet.lockfile.json` so read-side callers can fall back to the
+ * legacy filename on installs that predate the rename. Non-production
+ * environments are new and have a single canonical path under the env-scoped
+ * XDG config directory.
+ *
+ * Read-side callers should iterate this array and use the first existing
+ * file (matching `cli/src/lib/assistant-config.ts:readLockfile`). Write-side
+ * callers should use {@link getLockfilePath}, which returns the first
+ * (canonical) entry.
+ *
+ * `env.lockfileDirOverride` (populated by the resolver from
+ * `CADET_LOCKFILE_DIR`) overrides the directory the lockfile lives in for
+ * both production and non-production environments.
+ */
+export function getLockfilePaths(env: EnvironmentDefinition): string[] {
+  return resolveLockfilePaths(process.env, localPathOptions(env));
+}
+
+/**
+ * Canonical lockfile path for writes. For production this is the current
+ * `.cadet.lock.json` (legacy reads handled by {@link getLockfilePaths}).
+ */
+export function getLockfilePath(env: EnvironmentDefinition): string {
+  return getLockfilePaths(env)[0]!;
+}
+
+/**
+ * Multi-instance root directory for an environment. Production uses
+ * `~/.local/share/cadet/assistants/` — the convention already in
+ * `cli/src/lib/assistant-config.ts`. Non-production environments use
+ * `~/.local/share/cadet-<env>/assistants/`.
+ */
+export function getMultiInstanceDir(env: EnvironmentDefinition): string {
+  return resolveAssistantsDir(process.env, localPathOptions(env));
+}
+
+/**
+ * Default port set for an environment.
+ * Seed entries for non-prod environments come with separate port ranges
+ * to avoid collisions in multi-env / multi-instance setups.
+ * Longer term, consider allocating ports dynamically at hatch/wake time.
+ */
+export function getDefaultPorts(env: EnvironmentDefinition): PortMap {
+  return {
+    ...DEFAULT_PORTS,
+    ...(env.portsOverride ?? {}),
+  };
+}
+
+/**
+ * Runtime state directory for an environment (upgrade logs, etc.).
+ * Production uses `~/.local/share/cadet/`; non-production environments
+ * use `~/.local/share/cadet-<env>/`.
+ */
+export function getStateDir(env: EnvironmentDefinition): string {
+  return resolveRuntimeDir(process.env, localPathOptions(env));
+}
+
+export function getLogDir(env: EnvironmentDefinition): string {
+  return resolveLogDir(process.env, localPathOptions(env));
+}
+
+/**
+ * Path to the interactive CLI's input history file.
+ *
+ * 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`.
+ *
+ * Not environment-scoped: terminal input history is per-user, not per-assistant,
+ * so dev and prod CLIs share the same history file.
+ */
+export function getInputHistoryPath(): string {
+  return join(xdgStateHome(), "cadet", "input-history");
+}
+
+/**
+ * Named port constants derived from `DEFAULT_PORTS`.
+ * These are the ports the assistant and gateway services bind to *inside*
+ * their container (or process). They are stable across environments.
+ */
+export const ASSISTANT_INTERNAL_PORT = DEFAULT_PORTS.daemon;
+export const GATEWAY_INTERNAL_PORT = DEFAULT_PORTS.gateway;
+
+function xdgStateHome(): string {
+  return (
+    process.env.XDG_STATE_HOME?.trim() || join(homedir(), ".local", "state")
+  );
+}
+
+function localPathOptions(env: EnvironmentDefinition): LocalPathOptions {
+  return {
+    homeDir: homedir(),
+    environmentName: env.name,
+    configDirOverride: env.configDirOverride,
+    lockfileDirOverride: env.lockfileDirOverride,
+  };
+}

package/src/lib/environments/resolve.ts

@@ -0,0 +1,155 @@
+import { mkdirSync, unlinkSync, writeFileSync } from "fs";
+import { dirname } from "path";
+
+import { SEEDS, type EnvironmentDefinition } from "@mycadet/environments";
+import {
+  defaultEnvironmentFilePath,
+  defaultEnvironmentFilePaths,
+  readDefaultEnvironment as readPersistedDefaultEnvironment,
+} from "@mycadet/local-mode";
+
+const DEFAULT_ENVIRONMENT_NAME = "production";
+
+/**
+ * Read the persisted default environment name, if any.
+ * Returns `undefined` if no file exists or the file is empty.
+ */
+export function readDefaultEnvironment(): string | undefined {
+  return readPersistedDefaultEnvironment(process.env);
+}
+
+/**
+ * Persist a default environment name to the user config file.
+ */
+export function writeDefaultEnvironment(name: string): void {
+  const filePath = defaultEnvironmentFilePath(process.env);
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, name + "\n", "utf-8");
+}
+
+/**
+ * Remove the persisted default environment file, falling back to production.
+ */
+export function clearDefaultEnvironment(): void {
+  for (const filePath of defaultEnvironmentFilePaths(process.env)) {
+    try {
+      unlinkSync(filePath);
+    } catch {
+      // Already absent.
+    }
+  }
+}
+
+/**
+ * Look up a seed entry by name. Returns `undefined` if no seed matches.
+ * Callers that need the full resolution stack (env-var overrides, default
+ * fallback, error on unknown) should use {@link getCurrentEnvironment}
+ * instead. The returned definition is a shallow copy so mutations by the
+ * caller don't leak back into the seed table.
+ */
+export function getSeed(name: string): EnvironmentDefinition | undefined {
+  const seed = SEEDS[name];
+  if (!seed) return undefined;
+  return { ...seed };
+}
+
+/**
+ * Resolve the current environment definition.
+ *
+ * Priority:
+ *   1. `override` argument (from a `--environment` CLI flag, when wired)
+ *   2. `CADET_ENVIRONMENT` env var
+ *   3. User config file (`~/.config/cadet/environment`, set via `cadet env set`)
+ *   4. Default: `production`
+ *
+ * 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_WEB_URL` overrides `webUrl`
+ *   - `CADET_ASSISTANT_PLATFORM_URL` overrides `assistantPlatformUrl`
+ *   - `CADET_LOCKFILE_DIR` overrides `lockfileDirOverride` (legacy e2e
+ *     test hook)
+ *
+ * This function should be the single entrypoint for environment resolution.
+ * No other code should drive off `CADET_ENVIRONMENT` directly.
+ */
+export function getCurrentEnvironment(
+  override?: string,
+): EnvironmentDefinition {
+  const { name, source } = resolveEnvironmentSource(override);
+
+  // When the environment was resolved from the config file, propagate it
+  // into process.env so child processes (daemon, gateway) inherit the same
+  // environment without needing to read the config file themselves.
+  if (source === "config" && !process.env.CADET_ENVIRONMENT) {
+    process.env.CADET_ENVIRONMENT = name;
+  }
+
+  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.
+      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`,
+      );
+    }
+    const fallback = SEEDS[DEFAULT_ENVIRONMENT_NAME];
+    if (!fallback) {
+      throw new Error(
+        `fatal: default environment "${DEFAULT_ENVIRONMENT_NAME}" missing from seed table — this is a build error`,
+      );
+    }
+    return { ...fallback };
+  }
+
+  const resolved: EnvironmentDefinition = { ...seed };
+
+  const platformUrlOverride = process.env.CADET_PLATFORM_URL?.trim();
+  if (platformUrlOverride) {
+    resolved.platformUrl = platformUrlOverride;
+  }
+
+  const webUrlOverride = process.env.CADET_WEB_URL?.trim();
+  if (webUrlOverride) {
+    resolved.webUrl = webUrlOverride;
+  }
+
+  const assistantPlatformUrlOverride =
+    process.env.CADET_ASSISTANT_PLATFORM_URL?.trim();
+  if (assistantPlatformUrlOverride) {
+    resolved.assistantPlatformUrl = assistantPlatformUrlOverride;
+  }
+
+  const lockfileDirOverride = process.env.CADET_LOCKFILE_DIR?.trim();
+  if (lockfileDirOverride) {
+    resolved.lockfileDirOverride = lockfileDirOverride;
+  }
+
+  return resolved;
+}
+
+/**
+ * Resolve the environment name and its source for diagnostics.
+ */
+export function resolveEnvironmentSource(override?: string): {
+  name: string;
+  source: "flag" | "env" | "config" | "default";
+} {
+  const trimmedOverride = override?.trim();
+  if (trimmedOverride && trimmedOverride.length > 0) {
+    return { name: trimmedOverride, source: "flag" };
+  }
+  const envVar = process.env.CADET_ENVIRONMENT?.trim();
+  if (envVar && envVar.length > 0) {
+    return { name: envVar, source: "env" };
+  }
+  const configDefault = readDefaultEnvironment();
+  if (configDefault) {
+    return { name: configDefault, source: "config" };
+  }
+  return { name: DEFAULT_ENVIRONMENT_NAME, source: "default" };
+}

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

@@ -0,0 +1,122 @@
+import { createConnection } from "net";
+import { existsSync } from "fs";
+
+import type { AssistantEntry } from "./assistant-config";
+
+/**
+ * Execute a command inside an Apple Container assistant via the management
+ * socket. Non-interactive: sends the command, streams stdout/stderr to the
+ * terminal, and exits with the appropriate code.
+ */
+export async function execAppleContainer(
+  entry: AssistantEntry,
+  command: string[],
+  service: string,
+): Promise<void> {
+  const mgmtSocket = entry.mgmtSocket as string | undefined;
+  if (!mgmtSocket) {
+    console.error(
+      `No management socket found for '${entry.assistantId}'.\n` +
+        "The assistant may not be running.",
+    );
+    process.exit(1);
+  }
+
+  if (!existsSync(mgmtSocket)) {
+    console.error(
+      `Management socket not found at ${mgmtSocket}.\n` +
+        "The assistant may have been stopped.",
+    );
+    process.exit(1);
+  }
+
+  const handshake =
+    JSON.stringify({
+      command,
+      service,
+      cols: process.stdout.columns || 120,
+      rows: process.stdout.rows || 40,
+    }) + "\n";
+
+  return new Promise<void>((resolve, reject) => {
+    const socket = createConnection({ path: mgmtSocket }, () => {
+      socket.write(handshake);
+    });
+
+    const HANDSHAKE_TIMEOUT_MS = 10_000;
+    let handshakeComplete = false;
+    const handshakeChunks: Buffer[] = [];
+    let handshakeLen = 0;
+
+    socket.setTimeout(HANDSHAKE_TIMEOUT_MS);
+    socket.on("timeout", () => {
+      if (!handshakeComplete) {
+        console.error("Timed out waiting for response from management socket.");
+        socket.destroy();
+        process.exit(1);
+      }
+    });
+
+    socket.on("data", (data: Buffer) => {
+      if (!handshakeComplete) {
+        handshakeChunks.push(data);
+        handshakeLen += data.length;
+        const accumulated = Buffer.concat(handshakeChunks, handshakeLen);
+        const nlIndex = accumulated.indexOf(0x0a);
+        if (nlIndex === -1) return;
+
+        const responseLine = accumulated.slice(0, nlIndex).toString("utf-8");
+        const remainder = accumulated.slice(nlIndex + 1);
+        handshakeComplete = true;
+        socket.setTimeout(0);
+
+        let response: { status: string; message?: string };
+        try {
+          response = JSON.parse(responseLine) as {
+            status: string;
+            message?: string;
+          };
+        } catch {
+          console.error("Invalid response from management socket.");
+          socket.destroy();
+          process.exit(1);
+          return;
+        }
+
+        if (response.status !== "ok") {
+          console.error(`Exec failed: ${response.message || "unknown error"}`);
+          socket.destroy();
+          process.exit(1);
+          return;
+        }
+
+        // Write any bytes that arrived after the handshake newline.
+        if (remainder.length > 0) {
+          process.stdout.write(remainder);
+        }
+        return;
+      }
+
+      // Stream command output to stdout.
+      process.stdout.write(data);
+    });
+
+    socket.on("end", () => {
+      if (handshakeComplete) {
+        resolve();
+      } else {
+        reject(new Error("Connection closed before handshake completed."));
+      }
+    });
+
+    socket.on("error", (err) => {
+      reject(new Error(`Management socket error: ${err.message}`));
+    });
+
+    socket.on("close", () => {
+      if (handshakeComplete) {
+        resolve();
+      }
+    });
+  });
+}

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

@@ -0,0 +1,84 @@
+import { describe, expect, test, spyOn } from "bun:test";
+
+import { parseFeatureFlagArgs } from "./flag-args";
+
+describe("parseFeatureFlagArgs", () => {
+  test("single flag produces env var and empty remaining", () => {
+    const result = parseFeatureFlagArgs(["--flag", "browser=true"]);
+    expect(result).toEqual({
+      envVars: { CADET_FLAG_BROWSER: "true" },
+      remaining: [],
+    });
+  });
+
+  test("multiple flags produce multiple env vars", () => {
+    const result = parseFeatureFlagArgs(["--flag", "a=1", "--flag", "b=0"]);
+    expect(result).toEqual({
+      envVars: { CADET_FLAG_A: "1", CADET_FLAG_B: "0" },
+      remaining: [],
+    });
+  });
+
+  test("flags mixed with other args preserves remaining", () => {
+    const result = parseFeatureFlagArgs([
+      "--watch",
+      "--flag",
+      "x=y",
+      "--name",
+      "foo",
+    ]);
+    expect(result).toEqual({
+      envVars: { CADET_FLAG_X: "y" },
+      remaining: ["--watch", "--name", "foo"],
+    });
+  });
+
+  test("exits with error when --flag has no following argument", () => {
+    const exitSpy = spyOn(process, "exit").mockImplementation(() => {
+      throw new Error("process.exit");
+    });
+    const errorSpy = spyOn(console, "error").mockImplementation(() => {});
+
+    expect(() => parseFeatureFlagArgs(["--flag"])).toThrow("process.exit");
+    expect(errorSpy).toHaveBeenCalledWith(
+      "Error: --flag requires a key=value argument",
+    );
+
+    exitSpy.mockRestore();
+    errorSpy.mockRestore();
+  });
+
+  test("exits with error when value has no equals sign", () => {
+    const exitSpy = spyOn(process, "exit").mockImplementation(() => {
+      throw new Error("process.exit");
+    });
+    const errorSpy = spyOn(console, "error").mockImplementation(() => {});
+
+    expect(() => parseFeatureFlagArgs(["--flag", "noequals"])).toThrow(
+      "process.exit",
+    );
+    expect(errorSpy).toHaveBeenCalledWith(
+      'Error: --flag value must be in key=value format, got "noequals"',
+    );
+
+    exitSpy.mockRestore();
+    errorSpy.mockRestore();
+  });
+
+  test("exits with error when key is not kebab-case", () => {
+    const exitSpy = spyOn(process, "exit").mockImplementation(() => {
+      throw new Error("process.exit");
+    });
+    const errorSpy = spyOn(console, "error").mockImplementation(() => {});
+
+    expect(() => parseFeatureFlagArgs(["--flag", "UPPER=true"])).toThrow(
+      "process.exit",
+    );
+    expect(errorSpy).toHaveBeenCalledWith(
+      'Error: invalid flag key "UPPER". Keys must be kebab-case (e.g. "browser")',
+    );
+
+    exitSpy.mockRestore();
+    errorSpy.mockRestore();
+  });
+});

package/src/lib/flag-args.ts

@@ -0,0 +1,74 @@
+/** Only allow simple kebab-case keys (e.g. "browser", "contacts"). */
+const ALLOWED_KEY_RE = /^[a-z0-9][a-z0-9-]*$/;
+
+/**
+ * Extract repeatable `--flag key=value` pairs from a CLI arg list.
+ *
+ * Each `--flag` consumes the next argument as `key=value`. Keys are validated
+ * against a kebab-case pattern, then converted to env var names of the form
+ * `CADET_FLAG_<UPPER_SNAKE>`. All `--flag` pairs are stripped from the
+ * returned `remaining` array so downstream parsers never see them.
+ */
+export function parseFeatureFlagArgs(args: string[]): {
+  envVars: Record<string, string>;
+  remaining: string[];
+} {
+  const envVars: Record<string, string> = {};
+  const remaining: string[] = [];
+
+  let i = 0;
+  while (i < args.length) {
+    if (args[i] === "--flag") {
+      if (i + 1 >= args.length) {
+        console.error("Error: --flag requires a key=value argument");
+        process.exit(1);
+      }
+
+      const pair = args[i + 1]!;
+      const eqIdx = pair.indexOf("=");
+      if (eqIdx === -1) {
+        console.error(
+          `Error: --flag value must be in key=value format, got "${pair}"`,
+        );
+        process.exit(1);
+      }
+
+      const key = pair.slice(0, eqIdx);
+      const value = pair.slice(eqIdx + 1);
+
+      if (!ALLOWED_KEY_RE.test(key)) {
+        console.error(
+          `Error: invalid flag key "${key}". Keys must be kebab-case (e.g. "browser")`,
+        );
+        process.exit(1);
+      }
+
+      const envName = `CADET_FLAG_${key.toUpperCase().replace(/-/g, "_")}`;
+      envVars[envName] = value;
+      i += 2;
+    } else {
+      remaining.push(args[i]!);
+      i += 1;
+    }
+  }
+
+  return { envVars, remaining };
+}
+
+const ENV_FLAG_PREFIX = "CADET_FLAG_";
+
+/**
+ * Scan `process.env` for ambient `CADET_FLAG_*` entries.
+ * Returns them as-is (same `Record<string, string>` shape as
+ * `parseFeatureFlagArgs().envVars`) so callers can merge both
+ * sources with `--flag` args winning over ambient env vars.
+ */
+export function readAmbientFlagEnvVars(): Record<string, string> {
+  const vars: Record<string, string> = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (key.startsWith(ENV_FLAG_PREFIX) && value !== undefined) {
+      vars[key] = value;
+    }
+  }
+  return vars;
+}

package/src/lib/gcp.ts

@@ -0,0 +1,102 @@
+import { exec, execOutput } from "./step-runner";
+
+async function instanceExists(
+  instanceName: string,
+  project: string,
+  zone: string,
+): Promise<boolean> {
+  try {
+    await execOutput("gcloud", [
+      "compute",
+      "instances",
+      "describe",
+      instanceName,
+      `--project=${project}`,
+      `--zone=${zone}`,
+      "--format=get(name)",
+    ]);
+    return true;
+  } catch (error) {
+    const msg = error instanceof Error ? error.message.toLowerCase() : "";
+    if (
+      msg.includes("was not found") ||
+      msg.includes("could not fetch resource")
+    ) {
+      return false;
+    }
+    throw error;
+  }
+}
+
+async function checkGcloudAvailable(): Promise<boolean> {
+  try {
+    await execOutput("gcloud", ["--version"]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function retireInstance(
+  name: string,
+  project: string,
+  zone: string,
+  source?: string,
+): Promise<void> {
+  const gcloudOk = await checkGcloudAvailable();
+  if (!gcloudOk) {
+    throw new Error(
+      `Cannot retire GCP instance '${name}': gcloud CLI is not installed or not in PATH. ` +
+        `Please install the Google Cloud SDK and try again, or delete the instance manually ` +
+        `via the GCP Console (project=${project}, zone=${zone}).`,
+    );
+  }
+
+  let exists: boolean;
+  try {
+    exists = await instanceExists(name, project, zone);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `Cannot verify GCP instance '${name}': gcloud authentication failed.\n` +
+        `Ensure you are authenticated with 'gcloud auth login' or provide valid credentials.\n\n` +
+        `Details: ${detail}`,
+    );
+  }
+  if (!exists) {
+    console.warn(
+      `\u26a0\ufe0f  Instance ${name} not found in GCP (project=${project}, zone=${zone}).`,
+    );
+    return;
+  }
+
+  if (source) {
+    try {
+      await exec("gcloud", [
+        "compute",
+        "instances",
+        "add-labels",
+        name,
+        `--project=${project}`,
+        `--zone=${zone}`,
+        `--labels=retired-by=${source}`,
+      ]);
+    } catch {
+      console.warn(`\u26a0\ufe0f  Could not label instance before deletion`);
+    }
+  }
+
+  console.log(`\u{1F5D1}\ufe0f  Deleting GCP instance ${name}\n`);
+
+  await exec("gcloud", [
+    "compute",
+    "instances",
+    "delete",
+    name,
+    `--project=${project}`,
+    `--zone=${zone}`,
+    "--quiet",
+  ]);
+
+  console.log(`\u2705 Instance ${name} deleted.`);
+}