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

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

@@ -0,0 +1,265 @@
+import {
+  afterAll,
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  mock,
+  test,
+} from "bun:test";
+import { join } from "path";
+
+const TEST_HOME = "/test/home";
+
+// Mock homedir() so the helpers return predictable paths regardless of who
+// is running the test. `os.homedir()` is read once per process on Bun/Node
+// and does not reflect later $HOME changes, so setting process.env.HOME at
+// test time does not work — module mocking is the recommended pattern (see
+// cli/src/__tests__/multi-local.test.ts).
+const realOs = await import("node:os");
+mock.module("node:os", () => ({
+  ...realOs,
+  homedir: () => TEST_HOME,
+}));
+mock.module("os", () => ({
+  ...realOs,
+  homedir: () => TEST_HOME,
+}));
+
+// Restore the real `os` module once this file finishes so the `homedir()`
+// override does not leak into other test files in the same `bun test` run.
+afterAll(() => {
+  mock.module("node:os", () => realOs);
+  mock.module("os", () => realOs);
+});
+
+// Imports that depend on the mocked `os` module must come after the
+// mock.module() calls above.
+const {
+  getConfigDir,
+  getConfigDirs,
+  getDefaultPorts,
+  getLockfilePath,
+  getLockfilePaths,
+  getMultiInstanceDir,
+} = await import("../paths.js");
+type EnvironmentDefinition =
+  import("@mycadet/environments").EnvironmentDefinition;
+
+const prod: EnvironmentDefinition = {
+  name: "production",
+  platformUrl: "https://cloud.mycadet.ai",
+  webUrl: "https://mycadet.ai",
+};
+
+const dev: EnvironmentDefinition = {
+  name: "dev",
+  platformUrl: "https://dev-cloud.mycadet.ai",
+  webUrl: "https://dev.mycadet.ai",
+};
+
+const XDG_ENV_VARS = ["XDG_DATA_HOME", "XDG_CONFIG_HOME", "APPDATA"] as const;
+
+describe("path helpers", () => {
+  let savedEnv: Record<string, string | undefined>;
+
+  beforeEach(() => {
+    savedEnv = {};
+    for (const key of XDG_ENV_VARS) {
+      savedEnv[key] = process.env[key];
+      delete process.env[key];
+    }
+  });
+
+  afterEach(() => {
+    for (const [key, value] of Object.entries(savedEnv)) {
+      if (value === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = value;
+      }
+    }
+  });
+
+  describe("getConfigDir", () => {
+    test("Windows keeps XDG config as a legacy read location", () => {
+      const descriptor = Object.getOwnPropertyDescriptor(process, "platform")!;
+      try {
+        Object.defineProperty(process, "platform", {
+          ...descriptor,
+          value: "win32",
+        });
+        process.env.APPDATA = "C:\\AppData";
+        process.env.XDG_CONFIG_HOME = "D:\\Legacy";
+        expect(getConfigDirs(dev)).toEqual([
+          "C:\\AppData\\cadet-dev",
+          "D:\\Legacy\\cadet-dev",
+        ]);
+      } finally {
+        Object.defineProperty(process, "platform", descriptor);
+      }
+    });
+
+    test("production returns ~/.config/cadet/", () => {
+      expect(getConfigDir(prod)).toBe(join(TEST_HOME, ".config", "cadet"));
+    });
+
+    test("dev returns ~/.config/cadet-dev/", () => {
+      expect(getConfigDir(dev)).toBe(join(TEST_HOME, ".config", "cadet-dev"));
+    });
+
+    test("respects XDG_CONFIG_HOME for non-prod envs", () => {
+      process.env.XDG_CONFIG_HOME = "/custom/config";
+      expect(getConfigDir(dev)).toBe("/custom/config/cadet-dev");
+    });
+
+    test("respects XDG_CONFIG_HOME for production too", () => {
+      // Production's XDG config dir already follows XDG conventions, so the
+      // standard XDG override applies.
+      process.env.XDG_CONFIG_HOME = "/custom/config";
+      expect(getConfigDir(prod)).toBe("/custom/config/cadet");
+    });
+
+    test("respects env.configDirOverride", () => {
+      const env: EnvironmentDefinition = {
+        ...dev,
+        configDirOverride: "/tmp/cfg",
+      };
+      expect(getConfigDir(env)).toBe("/tmp/cfg");
+    });
+  });
+
+  describe("getLockfilePath", () => {
+    test("production returns ~/.cadet.lock.json", () => {
+      expect(getLockfilePath(prod)).toBe(join(TEST_HOME, ".cadet.lock.json"));
+    });
+
+    test("dev returns ~/.config/cadet-dev/lockfile.json", () => {
+      expect(getLockfilePath(dev)).toBe(
+        join(TEST_HOME, ".config", "cadet-dev", "lockfile.json"),
+      );
+    });
+
+    test("non-prod respects configDirOverride", () => {
+      const env: EnvironmentDefinition = {
+        ...dev,
+        configDirOverride: "/tmp/cfg",
+      };
+      expect(getLockfilePath(env)).toBe("/tmp/cfg/lockfile.json");
+    });
+
+    test("production respects lockfileDirOverride", () => {
+      const env: EnvironmentDefinition = {
+        ...prod,
+        lockfileDirOverride: "/tmp/lock",
+      };
+      expect(getLockfilePath(env)).toBe("/tmp/lock/.cadet.lock.json");
+    });
+
+    test("non-prod respects lockfileDirOverride (overrides configDir)", () => {
+      const env: EnvironmentDefinition = {
+        ...dev,
+        configDirOverride: "/tmp/cfg",
+        lockfileDirOverride: "/tmp/lock",
+      };
+      expect(getLockfilePath(env)).toBe("/tmp/lock/lockfile.json");
+    });
+  });
+
+  describe("getLockfilePaths", () => {
+    test("production returns both current and legacy filenames in priority order", () => {
+      expect(getLockfilePaths(prod)).toEqual([
+        join(TEST_HOME, ".cadet.lock.json"),
+        join(TEST_HOME, ".cadet.lockfile.json"),
+      ]);
+    });
+
+    test("non-prod returns a single canonical path", () => {
+      expect(getLockfilePaths(dev)).toEqual([
+        join(TEST_HOME, ".config", "cadet-dev", "lockfile.json"),
+      ]);
+    });
+
+    test("production with lockfileDirOverride applies to both candidates", () => {
+      const env: EnvironmentDefinition = {
+        ...prod,
+        lockfileDirOverride: "/tmp/lock",
+      };
+      expect(getLockfilePaths(env)).toEqual([
+        "/tmp/lock/.cadet.lock.json",
+        "/tmp/lock/.cadet.lockfile.json",
+      ]);
+    });
+
+    test("non-prod with lockfileDirOverride overrides the config dir", () => {
+      const env: EnvironmentDefinition = {
+        ...dev,
+        lockfileDirOverride: "/tmp/lock",
+      };
+      expect(getLockfilePaths(env)).toEqual(["/tmp/lock/lockfile.json"]);
+    });
+
+    test("getLockfilePath returns the first entry from getLockfilePaths", () => {
+      expect(getLockfilePath(prod)).toBe(getLockfilePaths(prod)[0]);
+      expect(getLockfilePath(dev)).toBe(getLockfilePaths(dev)[0]);
+    });
+  });
+
+  describe("getMultiInstanceDir", () => {
+    test("production returns ~/.local/share/cadet/assistants", () => {
+      expect(getMultiInstanceDir(prod)).toBe(
+        join(TEST_HOME, ".local", "share", "cadet", "assistants"),
+      );
+    });
+
+    test("dev returns ~/.local/share/cadet-dev/assistants", () => {
+      expect(getMultiInstanceDir(dev)).toBe(
+        join(TEST_HOME, ".local", "share", "cadet-dev", "assistants"),
+      );
+    });
+
+    test("respects XDG_DATA_HOME", () => {
+      process.env.XDG_DATA_HOME = "/custom/data";
+      expect(getMultiInstanceDir(dev)).toBe(
+        "/custom/data/cadet-dev/assistants",
+      );
+    });
+  });
+
+  describe("getDefaultPorts", () => {
+    test("returns production defaults for production", () => {
+      const ports = getDefaultPorts(prod);
+      expect(ports.daemon).toBe(7821);
+      expect(ports.gateway).toBe(7830);
+      expect(ports.qdrant).toBe(6333);
+      expect(ports.ces).toBe(8090);
+      expect(ports.outboundProxy).toBe(8080);
+      expect(ports.tcp).toBe(8765);
+    });
+
+    test("returns base defaults for a bare env with no portsOverride", () => {
+      // Bare env literal (no portsOverride) falls through to DEFAULT_PORTS.
+      // Real non-prod seeds populate portsOverride — see seeds.test cases.
+      expect(getDefaultPorts(dev)).toEqual(getDefaultPorts(prod));
+    });
+
+    test("merges env.portsOverride on top of defaults", () => {
+      const env: EnvironmentDefinition = {
+        ...dev,
+        portsOverride: { daemon: 9999, gateway: 9998 },
+      };
+      const ports = getDefaultPorts(env);
+      expect(ports.daemon).toBe(9999);
+      expect(ports.gateway).toBe(9998);
+      expect(ports.qdrant).toBe(6333);
+      expect(ports.ces).toBe(8090);
+    });
+
+    test("returns a fresh object — mutations do not affect future calls", () => {
+      const first = getDefaultPorts(prod);
+      first.daemon = 1;
+      const second = getDefaultPorts(prod);
+      expect(second.daemon).toBe(7821);
+    });
+  });
+});

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

@@ -0,0 +1,226 @@
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+
+import { getCurrentEnvironment, getSeed } from "../resolve.js";
+
+const ENV_VARS_TO_SAVE = [
+  "CADET_ENVIRONMENT",
+  "CADET_PLATFORM_URL",
+  "CADET_ASSISTANT_PLATFORM_URL",
+  "CADET_LOCKFILE_DIR",
+] as const;
+
+describe("getCurrentEnvironment", () => {
+  let savedEnv: Record<string, string | undefined>;
+
+  beforeEach(() => {
+    savedEnv = {};
+    for (const key of ENV_VARS_TO_SAVE) {
+      savedEnv[key] = process.env[key];
+      delete process.env[key];
+    }
+  });
+
+  afterEach(() => {
+    for (const [key, value] of Object.entries(savedEnv)) {
+      if (value === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = value;
+      }
+    }
+  });
+
+  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");
+  });
+
+  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");
+  });
+
+  test("returns staging seed when CADET_ENVIRONMENT=staging", () => {
+    process.env.CADET_ENVIRONMENT = "staging";
+    expect(getCurrentEnvironment().platformUrl).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");
+  });
+
+  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");
+  });
+
+  test("empty override argument falls through to env var", () => {
+    process.env.CADET_ENVIRONMENT = "dev";
+    const env = getCurrentEnvironment("");
+    expect(env.name).toBe("dev");
+  });
+
+  test("whitespace-only override argument falls through to env var", () => {
+    process.env.CADET_ENVIRONMENT = "dev";
+    const env = getCurrentEnvironment("   ");
+    expect(env.name).toBe("dev");
+  });
+
+  test("falls back to production seed for unknown env name via override, warns on stderr", () => {
+    const stderr = spyOn(process.stderr, "write").mockImplementation(
+      () => true,
+    );
+    try {
+      const env = getCurrentEnvironment("no-such-env");
+      expect(env.name).toBe("production");
+      expect(env.platformUrl).toBe("https://cloud.mycadet.ai");
+      expect(stderr).toHaveBeenCalledWith(
+        expect.stringContaining('unknown environment "no-such-env"'),
+      );
+      expect(stderr).toHaveBeenCalledWith(
+        expect.stringContaining('falling back to "production"'),
+      );
+    } finally {
+      stderr.mockRestore();
+    }
+  });
+
+  test("falls back to production seed for unknown env name via env var, warns on stderr", () => {
+    process.env.CADET_ENVIRONMENT = "nope";
+    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(stderr).toHaveBeenCalledWith(
+        expect.stringContaining('unknown environment "nope"'),
+      );
+    } finally {
+      stderr.mockRestore();
+    }
+  });
+
+  test("CADET_ENVIRONMENT=production does not emit a warning", () => {
+    process.env.CADET_ENVIRONMENT = "production";
+    const stderr = spyOn(process.stderr, "write").mockImplementation(
+      () => true,
+    );
+    try {
+      const env = getCurrentEnvironment();
+      expect(env.name).toBe("production");
+      expect(stderr).not.toHaveBeenCalled();
+    } finally {
+      stderr.mockRestore();
+    }
+  });
+
+  test("CADET_PLATFORM_URL overrides platformUrl on the resolved definition", () => {
+    process.env.CADET_ENVIRONMENT = "dev";
+    process.env.CADET_PLATFORM_URL = "https://custom.example.com";
+    const env = getCurrentEnvironment();
+    expect(env.name).toBe("dev");
+    expect(env.platformUrl).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";
+    getCurrentEnvironment();
+    delete process.env.CADET_PLATFORM_URL;
+    const env = getCurrentEnvironment();
+    expect(env.platformUrl).toBe("https://cloud.mycadet.ai");
+  });
+
+  test("CADET_ASSISTANT_PLATFORM_URL overrides assistantPlatformUrl", () => {
+    process.env.CADET_ASSISTANT_PLATFORM_URL =
+      "http://host.docker.internal:8000";
+    const env = getCurrentEnvironment();
+    expect(env.assistantPlatformUrl).toBe("http://host.docker.internal:8000");
+  });
+
+  test("CADET_ASSISTANT_PLATFORM_URL does not shadow platformUrl", () => {
+    process.env.CADET_ASSISTANT_PLATFORM_URL = "http://override";
+    const env = getCurrentEnvironment();
+    expect(env.platformUrl).toBe("https://cloud.mycadet.ai");
+  });
+
+  test("does not auto-materialize a new environment from CADET_PLATFORM_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 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";
+    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(stderr).toHaveBeenCalledWith(
+        expect.stringContaining('unknown environment "my-custom"'),
+      );
+    } finally {
+      stderr.mockRestore();
+    }
+  });
+
+  test("CADET_LOCKFILE_DIR populates lockfileDirOverride on the resolved definition", () => {
+    process.env.CADET_LOCKFILE_DIR = "/tmp/test-lockfile-dir";
+    const env = getCurrentEnvironment();
+    expect(env.lockfileDirOverride).toBe("/tmp/test-lockfile-dir");
+  });
+
+  test("lockfileDirOverride is undefined when CADET_LOCKFILE_DIR is unset", () => {
+    const env = getCurrentEnvironment();
+    expect(env.lockfileDirOverride).toBeUndefined();
+  });
+
+  test("lockfileDirOverride applies to non-prod envs too", () => {
+    process.env.CADET_ENVIRONMENT = "dev";
+    process.env.CADET_LOCKFILE_DIR = "/tmp/test-lockfile-dir";
+    const env = getCurrentEnvironment();
+    expect(env.name).toBe("dev");
+    expect(env.lockfileDirOverride).toBe("/tmp/test-lockfile-dir");
+  });
+});
+
+describe("getSeed", () => {
+  test("returns a definition for a known seed", () => {
+    const seed = getSeed("dev");
+    expect(seed).toBeDefined();
+    expect(seed?.name).toBe("dev");
+    expect(seed?.platformUrl).toBe("https://dev-cloud.mycadet.ai");
+  });
+
+  test("returns undefined for an unknown name", () => {
+    expect(getSeed("no-such-env")).toBeUndefined();
+  });
+
+  test("returned seed is a copy — mutations do not affect the table", () => {
+    const seed = getSeed("dev");
+    if (seed) {
+      seed.platformUrl = "mutated";
+    }
+    const second = getSeed("dev");
+    expect(second?.platformUrl).toBe("https://dev-cloud.mycadet.ai");
+  });
+
+  test("all five canonical seeds exist", () => {
+    expect(getSeed("production")).toBeDefined();
+    expect(getSeed("staging")).toBeDefined();
+    expect(getSeed("test")).toBeDefined();
+    expect(getSeed("dev")).toBeDefined();
+    expect(getSeed("local")).toBeDefined();
+  });
+});

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

@@ -0,0 +1,73 @@
+import { describe, expect, test } from "bun:test";
+
+import { SEEDS } from "@mycadet/environments";
+
+import { getDefaultPorts } from "../paths.js";
+
+describe("SEEDS port blocks", () => {
+  test("production uses the legacy (pre-MVP) port layout", () => {
+    const ports = getDefaultPorts(SEEDS.production!);
+    expect(ports).toEqual({
+      daemon: 7821,
+      gateway: 7830,
+      qdrant: 6333,
+      ces: 8090,
+      outboundProxy: 8080,
+      tcp: 8765,
+    });
+  });
+
+  test.each([
+    ["staging", 17000],
+    ["dev", 18000],
+    ["test", 19000],
+    ["local", 20000],
+  ] as const)("%s block starts at %i with 100-apart services", (name, base) => {
+    const ports = getDefaultPorts(SEEDS[name]!);
+    expect(ports).toEqual({
+      daemon: base,
+      gateway: base + 100,
+      qdrant: base + 200,
+      ces: base + 300,
+      outboundProxy: base + 400,
+      tcp: base + 500,
+    });
+  });
+
+  test("non-prod blocks are disjoint across environments", () => {
+    // 100 instances per service is the scan headroom in findAvailablePort,
+    // so a block "occupies" base…base+599 from daemon through tcp. Verify no
+    // two blocks overlap for any service.
+    const blocks = (["staging", "dev", "test", "local"] as const).map(
+      (name) => ({
+        name,
+        ports: getDefaultPorts(SEEDS[name]!),
+      }),
+    );
+    const allPorts = new Set<number>();
+    for (const { name, ports } of blocks) {
+      for (const port of Object.values(ports)) {
+        // Within each block, each service has 100 slots (base…base+99).
+        for (let offset = 0; offset < 100; offset++) {
+          const p = port + offset;
+          if (allPorts.has(p)) {
+            throw new Error(
+              `port ${p} (in ${name}'s block) overlaps another env's block`,
+            );
+          }
+          allPorts.add(p);
+        }
+      }
+    }
+  });
+
+  test("non-prod blocks sit below Linux's default ephemeral range (32768)", () => {
+    for (const name of ["staging", "dev", "test", "local"] as const) {
+      const ports = getDefaultPorts(SEEDS[name]!);
+      for (const port of Object.values(ports)) {
+        // Max port we'll ever scan to is base+99 for daemon/gateway/etc.
+        expect(port + 99).toBeLessThan(32768);
+      }
+    }
+  });
+});

package/src/lib/environments/detect.ts

@@ -0,0 +1,79 @@
+import { readdirSync } from "fs";
+
+import { SEEDS, type EnvironmentDefinition } from "@mycadet/environments";
+
+import { getMultiInstanceDir } from "./paths.js";
+import { getCurrentEnvironment } from "./resolve.js";
+
+/**
+ * Names of OTHER environments (every seed except `currentEnv`) whose
+ * multi-instance data dir exists and holds at least one assistant
+ * subdirectory.
+ *
+ * Each environment has its own on-host data layout — see
+ * {@link getMultiInstanceDir}. A user who hatched via a dev/staging desktop
+ * app but runs the production npm CLI (or vice versa) targets a different
+ * layout than the app did, so the assistant the app created is invisible to
+ * this CLI. This cheap filesystem scan surfaces that split so callers can
+ * point the user at the environment that actually holds their assistants.
+ *
+ * Never throws: a missing or unreadable dir just means that environment has no
+ * discoverable assistants, so it is skipped. Returns an empty array on any
+ * error.
+ */
+export function detectOtherEnvironmentAssistants(
+  currentEnv: EnvironmentDefinition,
+): string[] {
+  const found: string[] = [];
+  for (const env of Object.values(SEEDS)) {
+    if (env.name === currentEnv.name) {
+      continue;
+    }
+    try {
+      const hasAssistant = readdirSync(getMultiInstanceDir(env), {
+        withFileTypes: true,
+      }).some((dirent) => dirent.isDirectory());
+      if (hasAssistant) {
+        found.push(env.name);
+      }
+    } catch {
+      // Missing or unreadable dir — this environment has no discoverable
+      // assistants. Skip it.
+    }
+  }
+  return found;
+}
+
+/**
+ * One-line hint appended to "no assistant found" and "gateway unreachable"
+ * errors when another environment's data dir holds assistants. A first-time
+ * user who hatched via a dev/staging desktop app while running the production
+ * npm CLI otherwise gets a bare failure with no clue the two tools target
+ * different environments.
+ *
+ * Returns null when nothing is found so callers can append unconditionally:
+ * `message + (crossEnvironmentAssistantHint() ?? "")`. Detection failure never
+ * propagates — the caller's original error must survive intact.
+ */
+export function crossEnvironmentAssistantHint(): string | null {
+  let currentEnv: EnvironmentDefinition;
+  let others: string[];
+  try {
+    currentEnv = getCurrentEnvironment();
+    others = detectOtherEnvironmentAssistants(currentEnv);
+  } catch {
+    return null;
+  }
+  if (others.length === 0) {
+    return null;
+  }
+
+  const quoted = others.map((name) => `'${name}'`).join(", ");
+  const noun = others.length > 1 ? "environments" : "environment";
+  return (
+    `\n\nFound assistants in the ${quoted} ${noun} (managed by a dev/staging ` +
+    `desktop app). This CLI targets '${currentEnv.name}'. Use the desktop ` +
+    `app's 'Install cadet Command…' menu item to get a matching CLI, or ` +
+    `set CADET_ENVIRONMENT=${others[0]}.`
+  );
+}