@vellumai/cli 0.6.3 → 0.6.5

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 = [
+  "VELLUM_ENVIRONMENT",
+  "VELLUM_PLATFORM_URL",
+  "VELLUM_ASSISTANT_PLATFORM_URL",
+  "VELLUM_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://platform.vellum.ai");
+  });
+
+  test("returns dev seed when VELLUM_ENVIRONMENT=dev", () => {
+    process.env.VELLUM_ENVIRONMENT = "dev";
+    const env = getCurrentEnvironment();
+    expect(env.name).toBe("dev");
+    expect(env.platformUrl).toBe("https://dev-platform.vellum.ai");
+  });
+
+  test("returns staging seed when VELLUM_ENVIRONMENT=staging", () => {
+    process.env.VELLUM_ENVIRONMENT = "staging";
+    expect(getCurrentEnvironment().platformUrl).toBe(
+      "https://staging-platform.vellum.ai",
+    );
+  });
+
+  test("returns local seed with localhost URL", () => {
+    process.env.VELLUM_ENVIRONMENT = "local";
+    expect(getCurrentEnvironment().platformUrl).toBe("http://localhost:8000");
+  });
+
+  test("override argument takes priority over VELLUM_ENVIRONMENT env var", () => {
+    process.env.VELLUM_ENVIRONMENT = "staging";
+    const env = getCurrentEnvironment("dev");
+    expect(env.name).toBe("dev");
+    expect(env.platformUrl).toBe("https://dev-platform.vellum.ai");
+  });
+
+  test("empty override argument falls through to env var", () => {
+    process.env.VELLUM_ENVIRONMENT = "dev";
+    const env = getCurrentEnvironment("");
+    expect(env.name).toBe("dev");
+  });
+
+  test("whitespace-only override argument falls through to env var", () => {
+    process.env.VELLUM_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://platform.vellum.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.VELLUM_ENVIRONMENT = "nope";
+    const stderr = spyOn(process.stderr, "write").mockImplementation(
+      () => true,
+    );
+    try {
+      const env = getCurrentEnvironment();
+      expect(env.name).toBe("production");
+      expect(env.platformUrl).toBe("https://platform.vellum.ai");
+      expect(stderr).toHaveBeenCalledWith(
+        expect.stringContaining('unknown environment "nope"'),
+      );
+    } finally {
+      stderr.mockRestore();
+    }
+  });
+
+  test("VELLUM_ENVIRONMENT=production does not emit a warning", () => {
+    process.env.VELLUM_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("VELLUM_PLATFORM_URL overrides platformUrl on the resolved definition", () => {
+    process.env.VELLUM_ENVIRONMENT = "dev";
+    process.env.VELLUM_PLATFORM_URL = "https://custom.example.com";
+    const env = getCurrentEnvironment();
+    expect(env.name).toBe("dev");
+    expect(env.platformUrl).toBe("https://custom.example.com");
+  });
+
+  test("VELLUM_PLATFORM_URL override does not affect the seed table", () => {
+    process.env.VELLUM_PLATFORM_URL = "https://custom.example.com";
+    getCurrentEnvironment();
+    delete process.env.VELLUM_PLATFORM_URL;
+    const env = getCurrentEnvironment();
+    expect(env.platformUrl).toBe("https://platform.vellum.ai");
+  });
+
+  test("VELLUM_ASSISTANT_PLATFORM_URL overrides assistantPlatformUrl", () => {
+    process.env.VELLUM_ASSISTANT_PLATFORM_URL =
+      "http://host.docker.internal:8000";
+    const env = getCurrentEnvironment();
+    expect(env.assistantPlatformUrl).toBe("http://host.docker.internal:8000");
+  });
+
+  test("VELLUM_ASSISTANT_PLATFORM_URL does not shadow platformUrl", () => {
+    process.env.VELLUM_ASSISTANT_PLATFORM_URL = "http://override";
+    const env = getCurrentEnvironment();
+    expect(env.platformUrl).toBe("https://platform.vellum.ai");
+  });
+
+  test("does not auto-materialize a new environment from VELLUM_PLATFORM_URL alone", () => {
+    // Unknown env names fall back to production (parity with daemon + Swift).
+    // The per-field VELLUM_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.VELLUM_ENVIRONMENT = "my-custom";
+    process.env.VELLUM_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://platform.vellum.ai");
+      expect(stderr).toHaveBeenCalledWith(
+        expect.stringContaining('unknown environment "my-custom"'),
+      );
+    } finally {
+      stderr.mockRestore();
+    }
+  });
+
+  test("VELLUM_LOCKFILE_DIR populates lockfileDirOverride on the resolved definition", () => {
+    process.env.VELLUM_LOCKFILE_DIR = "/tmp/test-lockfile-dir";
+    const env = getCurrentEnvironment();
+    expect(env.lockfileDirOverride).toBe("/tmp/test-lockfile-dir");
+  });
+
+  test("lockfileDirOverride is undefined when VELLUM_LOCKFILE_DIR is unset", () => {
+    const env = getCurrentEnvironment();
+    expect(env.lockfileDirOverride).toBeUndefined();
+  });
+
+  test("lockfileDirOverride applies to non-prod envs too", () => {
+    process.env.VELLUM_ENVIRONMENT = "dev";
+    process.env.VELLUM_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-platform.vellum.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-platform.vellum.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,72 @@
+import { describe, expect, test } from "bun:test";
+
+import { getDefaultPorts } from "../paths.js";
+import { SEEDS } from "../seeds.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/paths.ts

@@ -0,0 +1,109 @@
+import { homedir } from "os";
+import { join } from "path";
+
+import type { EnvironmentDefinition, PortMap } from "./types.js";
+
+const PRODUCTION_ENVIRONMENT_NAME = "production";
+
+/**
+ * Production lockfile filenames in priority order. The current name is
+ * `.vellum.lock.json`; `.vellum.lockfile.json` is the legacy name kept for
+ * backward compatibility with installs that predate the rename.
+ */
+const PRODUCTION_LOCKFILE_NAMES = [
+  ".vellum.lock.json",
+  ".vellum.lockfile.json",
+] as const;
+
+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/vellum/` location;
+ * non-production environments use `$XDG_CONFIG_HOME/vellum-<env>/`.
+ */
+export function getConfigDir(env: EnvironmentDefinition): string {
+  if (env.configDirOverride) return env.configDirOverride;
+  if (env.name === PRODUCTION_ENVIRONMENT_NAME) {
+    return join(xdgConfigHome(), "vellum");
+  }
+  return join(xdgConfigHome(), `vellum-${env.name}`);
+}
+
+/**
+ * Lockfile candidate paths for an environment, in priority order.
+ *
+ * For production, returns both the current `.vellum.lock.json` and the
+ * legacy `.vellum.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
+ * `VELLUM_LOCKFILE_DIR`) overrides the directory the lockfile lives in for
+ * both production and non-production environments.
+ */
+export function getLockfilePaths(env: EnvironmentDefinition): string[] {
+  if (env.name === PRODUCTION_ENVIRONMENT_NAME) {
+    const dir = env.lockfileDirOverride ?? homedir();
+    return PRODUCTION_LOCKFILE_NAMES.map((name) => join(dir, name));
+  }
+  const dir = env.lockfileDirOverride ?? getConfigDir(env);
+  return [join(dir, "lockfile.json")];
+}
+
+/**
+ * Canonical lockfile path for writes. For production this is the current
+ * `.vellum.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/vellum/assistants/` — the convention already in
+ * `cli/src/lib/assistant-config.ts`. Non-production environments use
+ * `~/.local/share/vellum-<env>/assistants/`.
+ */
+export function getMultiInstanceDir(env: EnvironmentDefinition): string {
+  if (env.name === PRODUCTION_ENVIRONMENT_NAME) {
+    return join(xdgDataHome(), "vellum", "assistants");
+  }
+  return join(xdgDataHome(), `vellum-${env.name}`, "assistants");
+}
+
+/**
+ * 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 ?? {}),
+  };
+}
+
+function xdgDataHome(): string {
+  return (
+    process.env.XDG_DATA_HOME?.trim() || join(homedir(), ".local", "share")
+  );
+}
+
+function xdgConfigHome(): string {
+  return process.env.XDG_CONFIG_HOME?.trim() || join(homedir(), ".config");
+}

package/src/lib/environments/resolve.ts

@@ -0,0 +1,96 @@
+import { SEEDS } from "./seeds.js";
+import type { EnvironmentDefinition } from "./types.js";
+
+const DEFAULT_ENVIRONMENT_NAME = "production";
+
+/**
+ * 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. `VELLUM_ENVIRONMENT` env var
+ *   3. (future) user context file
+ *   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):
+ *   - `VELLUM_PLATFORM_URL` overrides `platformUrl`
+ *   - `VELLUM_ASSISTANT_PLATFORM_URL` overrides `assistantPlatformUrl`
+ *   - `VELLUM_LOCKFILE_DIR` overrides `lockfileDirOverride` (legacy e2e
+ *     test hook)
+ *
+ * This function should be the single entrypoint for environment resolution.
+ * No other code should drive off `VELLUM_ENVIRONMENT` directly.
+ */
+export function getCurrentEnvironment(
+  override?: string,
+): EnvironmentDefinition {
+  const name = resolveEnvironmentName(override);
+  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:getXdgVellumConfigDirName
+      // and clients/shared/App/VellumEnvironment.swift:current. Those two
+      // silently fall back to production; the CLI should agree so all three
+      // writers don't end up in disjoint states on a typo.
+      process.stderr.write(
+        `warning: unknown environment "${name}"; falling back to "${DEFAULT_ENVIRONMENT_NAME}". ` +
+          `Add it to cli/src/lib/environments/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.VELLUM_PLATFORM_URL?.trim();
+  if (platformUrlOverride) {
+    resolved.platformUrl = platformUrlOverride;
+  }
+
+  const assistantPlatformUrlOverride =
+    process.env.VELLUM_ASSISTANT_PLATFORM_URL?.trim();
+  if (assistantPlatformUrlOverride) {
+    resolved.assistantPlatformUrl = assistantPlatformUrlOverride;
+  }
+
+  const lockfileDirOverride = process.env.VELLUM_LOCKFILE_DIR?.trim();
+  if (lockfileDirOverride) {
+    resolved.lockfileDirOverride = lockfileDirOverride;
+  }
+
+  return resolved;
+}
+
+function resolveEnvironmentName(override: string | undefined): string {
+  const trimmedOverride = override?.trim();
+  if (trimmedOverride && trimmedOverride.length > 0) {
+    return trimmedOverride;
+  }
+  const envVar = process.env.VELLUM_ENVIRONMENT?.trim();
+  if (envVar && envVar.length > 0) {
+    return envVar;
+  }
+
+  return DEFAULT_ENVIRONMENT_NAME;
+}

package/src/lib/environments/seeds.ts

@@ -0,0 +1,74 @@
+import type { EnvironmentDefinition, PortMap } from "./types.js";
+
+/**
+ * Non-prod port blocks. Each environment gets a 1000-port window in the
+ * 17000–21000 band. Within a block, services are spaced 100 apart so up to
+ * 100 assistants can coexist without the scan (`findAvailablePort`) running
+ * one service's range into the next. Band chosen to sit below Linux's
+ * default ephemeral start (32768) and macOS's (49152), and away from the
+ * 3000/5000/8000/9000 dev-tool swamp. Production keeps its legacy,
+ * non-contiguous port set (7821/7830/6333/8090/8080/8765): cross-env
+ * collision is the only problem this change targets, prod is unaffected
+ * because only one env's assistants compete on a given machine, and
+ * churning it would leave existing hatches on 7821 while new ones
+ * allocated elsewhere.
+ */
+function portBlock(base: number): PortMap {
+  return {
+    daemon: base,
+    gateway: base + 100,
+    qdrant: base + 200,
+    ces: base + 300,
+    outboundProxy: base + 400,
+    tcp: base + 500,
+  };
+}
+
+/**
+ * Built-in environment definitions. Mirrors Swift's
+ * `clients/macos/vellum-assistant/App/VellumEnvironment.swift` enum and is
+ * the TS-side source of truth for the set of known environment names.
+ * Two other TS sites duplicate the name list:
+ *   - `assistant/src/util/platform.ts` (`KNOWN_ENVIRONMENTS`)
+ *   - `clients/chrome-extension/native-host/src/lockfile.ts`
+ *     (`NON_PRODUCTION_ENVIRONMENTS`, excludes `production`)
+ * Drift between these three sites is caught at test time by
+ * `cli/src/__tests__/env-drift.test.ts`. Fast follow: hoist the shared
+ * list into a `packages/environments` package so all three sites import
+ * from one place.
+ *
+ * Custom environments via a user config file are a future phase — see the
+ * "Coexisting environments" design doc. Until then, a call site that needs a
+ * new environment must add it here and rebuild.
+ */
+export const SEEDS: Record<string, EnvironmentDefinition> = {
+  production: {
+    name: "production",
+    platformUrl: "https://platform.vellum.ai",
+  },
+  staging: {
+    name: "staging",
+    platformUrl: "https://staging-platform.vellum.ai",
+    portsOverride: portBlock(17000),
+  },
+  test: {
+    name: "test",
+    // Non-functional URL — used only by unit tests for URL resolution, never
+    // hit in production.
+    platformUrl: "https://test-platform.vellum.ai",
+    portsOverride: portBlock(19000),
+  },
+  dev: {
+    name: "dev",
+    platformUrl: "https://dev-platform.vellum.ai",
+    portsOverride: portBlock(18000),
+  },
+  local: {
+    name: "local",
+    platformUrl: "http://localhost:8000",
+    // assistantPlatformUrl: "http://host.docker.internal:8000",
+    // ^ uncomment this once dockerized hatch path is live.
+    // The assistant runs in a different network namespace than the host.
+    portsOverride: portBlock(20000),
+  },
+};

package/src/lib/environments/types.ts

@@ -0,0 +1,60 @@
+/**
+ * Environment type definitions. Environments are deployment targets with
+ * their own platform backend and their own isolated on-host state. See the
+ * "Coexisting environments" design doc for the full model.
+ */
+
+/**
+ * Per-service default port set. Phase 5 (per-environment port offsets) is
+ * deferred from MVP, so today every environment uses the same port set. The
+ * shape exists so the rest of the stack can call `getDefaultPorts(env)` and
+ * gain per-env offsets later without changing any call sites.
+ */
+export interface PortMap {
+  daemon: number;
+  gateway: number;
+  qdrant: number;
+  ces: number;
+  outboundProxy: number;
+  tcp: number;
+}
+
+/**
+ * A resolved environment definition. Required fields are `name` and
+ * `platformUrl`. All other fields are optional and declared upfront — new
+ * fields are additive, never breaking. `name` is intentionally typed as
+ * `string` (not `keyof SEEDS`) so custom environments can be represented by
+ * future layers (user config file, ad-hoc env vars, etc.).
+ */
+export interface EnvironmentDefinition {
+  name: string;
+  platformUrl: string;
+
+  /**
+   * Override for the platform URL the assistant process itself uses. Only
+   * differs from `platformUrl` when the assistant runs in a different network
+   * namespace than the host (e.g. Docker on macOS, where the host's localhost
+   * is reached via `host.docker.internal`). Falls back to `platformUrl` when
+   * unset.
+   */
+  assistantPlatformUrl?: string;
+
+  /** Human-readable label for UI surfaces. */
+  displayName?: string;
+
+  /** Hint for UI surfaces that want to tint or badge their display. */
+  tintColor?: string;
+
+  /** Per-service port overrides merged on top of defaults. */
+  portsOverride?: Partial<PortMap>;
+
+  /** Override for the XDG config directory. */
+  configDirOverride?: string;
+
+  /**
+   * Override for the directory containing the lockfile. Populated by the
+   * resolver from `VELLUM_LOCKFILE_DIR` (an existing e2e test escape hatch)
+   * so path helpers don't read env vars directly.
+   */
+  lockfileDirOverride?: string;
+}