@vellumai/cli 0.8.6 → 0.8.7-dev.202606052118.34cd356

package/node_modules/@vellumai/local-mode/src/__tests__/package-boundary.test.ts

@@ -0,0 +1,104 @@
+/**
+ * Package boundary tests for @vellumai/local-mode.
+ *
+ * This package is the shared local-assistant host surface. It sits one layer
+ * above @vellumai/environments (its only allowed @vellumai dependency) and
+ * uses node builtins for filesystem, child-process, and network work.
+ *
+ * Enforces that the package:
+ * 1. Imports only node builtins, its own relative modules, and
+ *    `@vellumai/environments` — no other `@vellumai/*` packages and no
+ *    third-party runtime imports (so any bundler host can inline it).
+ * 2. Declares exactly one runtime dependency: `@vellumai/environments`.
+ * 3. Is marked `private`.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+const PACKAGE_ROOT = resolve(import.meta.dirname, "../..");
+const SRC_DIR = join(PACKAGE_ROOT, "src");
+
+const ALLOWED_PACKAGES = new Set(["@vellumai/environments"]);
+
+function collectSourceFiles(dir: string): string[] {
+  const files: string[] = [];
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    const stat = statSync(full);
+    if (stat.isDirectory()) {
+      if (entry === "node_modules" || entry === "__tests__") continue;
+      files.push(...collectSourceFiles(full));
+    } else if (
+      entry.endsWith(".ts") &&
+      !entry.endsWith(".test.ts") &&
+      !entry.endsWith(".d.ts")
+    ) {
+      files.push(full);
+    }
+  }
+  return files;
+}
+
+/**
+ * Matches the module specifier of any `import ... from "<spec>"` /
+ * `export ... from "<spec>"` / `require("<spec>")` statement.
+ */
+const IMPORT_SPEC = /(?:from|require\s*\(\s*)["']([^"']+)["']/g;
+
+/**
+ * A specifier is forbidden when it is neither relative, a node builtin, nor
+ * one of the explicitly allowed `@vellumai/*` packages.
+ */
+function isForbiddenSpecifier(spec: string): boolean {
+  if (spec.startsWith(".") || spec.startsWith("/")) return false;
+  if (spec.startsWith("node:")) return false;
+  if (ALLOWED_PACKAGES.has(spec)) return false;
+  return true;
+}
+
+describe("package boundary", () => {
+  const sourceFiles = collectSourceFiles(SRC_DIR);
+
+  test("has source files to validate", () => {
+    expect(sourceFiles.length).toBeGreaterThan(0);
+  });
+
+  test("imports only node builtins, relative modules, and @vellumai/environments", () => {
+    const violations: string[] = [];
+
+    for (const file of sourceFiles) {
+      const lines = readFileSync(file, "utf-8").split("\n");
+      for (let i = 0; i < lines.length; i++) {
+        for (const match of lines[i]!.matchAll(IMPORT_SPEC)) {
+          const spec = match[1]!;
+          if (isForbiddenSpecifier(spec)) {
+            const relative = file.replace(PACKAGE_ROOT + "/", "");
+            violations.push(`${relative}:${i + 1}: ${spec}`);
+          }
+        }
+      }
+    }
+
+    if (violations.length > 0) {
+      throw new Error(
+        `Found ${violations.length} forbidden import(s) in @vellumai/local-mode:\n` +
+          violations.map((v) => `  - ${v}`).join("\n") +
+          "\n\n@vellumai/local-mode may import only node builtins, its own\n" +
+          "relative modules, and @vellumai/environments. Any other dependency\n" +
+          "would break bundler hosts that inline this source-only package.",
+      );
+    }
+  });
+
+  test("package.json declares it as private with only the @vellumai/environments dependency", () => {
+    const pkg = JSON.parse(
+      readFileSync(join(PACKAGE_ROOT, "package.json"), "utf-8"),
+    );
+    expect(pkg.private).toBe(true);
+    expect(pkg.dependencies ?? {}).toEqual({
+      "@vellumai/environments": "file:../environments",
+    });
+  });
+});

package/node_modules/@vellumai/local-mode/src/__tests__/wake.test.ts

@@ -0,0 +1,66 @@
+import { afterEach, beforeAll, describe, expect, mock, test } from "bun:test";
+import { EventEmitter } from "node:events";
+
+import type { CliInvocation } from "../util";
+
+class FakeChild extends EventEmitter {
+  stdout = new EventEmitter();
+  stderr = new EventEmitter();
+  kill = mock(() => true);
+}
+
+let lastChild: FakeChild;
+const spawnArgs: Array<[string, string[]]> = [];
+const spawnMock = mock((command: string, args: string[]) => {
+  spawnArgs.push([command, args]);
+  lastChild = new FakeChild();
+  return lastChild;
+});
+
+mock.module("node:child_process", () => ({ spawn: spawnMock }));
+
+let runWake: typeof import("../wake").runWake;
+
+beforeAll(async () => {
+  ({ runWake } = await import("../wake"));
+});
+
+afterEach(() => {
+  spawnArgs.length = 0;
+  spawnMock.mockClear();
+});
+
+const invocation: CliInvocation = { command: "bun", baseArgs: ["run", "cli"] };
+
+describe("runWake", () => {
+  test("spawns the CLI wake command for the assistant and resolves ok on exit 0", async () => {
+    const pending = runWake(invocation, "asst-42");
+    lastChild.emit("close", 0);
+
+    expect(await pending).toEqual({ ok: true });
+    expect(spawnArgs[0]).toEqual(["bun", ["run", "cli", "wake", "asst-42"]]);
+  });
+
+  test("a non-zero exit resolves to a failure carrying the CLI's output", async () => {
+    const pending = runWake(invocation, "asst-42");
+    lastChild.stderr.emit("data", Buffer.from("no sibling environment to seed from"));
+    lastChild.emit("close", 1);
+
+    expect(await pending).toEqual({
+      ok: false,
+      status: 500,
+      error: "no sibling environment to seed from",
+    });
+  });
+
+  test("a spawn failure resolves to a failure rather than rejecting", async () => {
+    const pending = runWake(invocation, "asst-42");
+    lastChild.emit("error", new Error("ENOENT"));
+
+    const result = await pending;
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toContain("ENOENT");
+    }
+  });
+});

package/node_modules/@vellumai/local-mode/src/config.ts

@@ -0,0 +1,66 @@
+import os from "node:os";
+import path from "node:path";
+
+import { SEEDS } from "@vellumai/environments";
+
+import { resolveEnvironmentName } from "./environment";
+
+const PRODUCTION_ENVIRONMENT_NAME = "production";
+
+export interface LocalEndpointConfig {
+  lockfilePaths: string[];
+  configDir: string;
+  webUrl: string;
+  platformUrl: string;
+}
+
+/**
+ * Resolve config from environment variables. Accepts any environment-shaped
+ * map, including `process.env` (whose values are `string | undefined`) and the
+ * Vite plugin's `loadEnv` result.
+ */
+export function resolveLocalConfigFromEnv(
+  env: Record<string, string | undefined>,
+): LocalEndpointConfig {
+  const vellumEnv = resolveEnvironmentName(env);
+  const seed = SEEDS[vellumEnv] ?? SEEDS[PRODUCTION_ENVIRONMENT_NAME]!;
+
+  return {
+    lockfilePaths: resolveLockfilePaths(env),
+    configDir: resolveConfigDir(env),
+    webUrl: env.VELLUM_WEB_URL || seed.webUrl,
+    platformUrl: env.VELLUM_PLATFORM_URL || seed.platformUrl,
+  };
+}
+
+export function resolveLockfilePaths(
+  env: Record<string, string | undefined>,
+): string[] {
+  const vellumEnv = resolveEnvironmentName(env);
+  const lockfileDir = env.VELLUM_LOCKFILE_DIR;
+
+  if (vellumEnv === PRODUCTION_ENVIRONMENT_NAME) {
+    const dir = lockfileDir ?? os.homedir();
+    return [
+      path.join(dir, ".vellum.lock.json"),
+      path.join(dir, ".vellum.lockfile.json"),
+    ];
+  }
+
+  const xdgConfigHome =
+    env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
+  const dir = lockfileDir ?? path.join(xdgConfigHome, `vellum-${vellumEnv}`);
+  return [path.join(dir, "lockfile.json")];
+}
+
+export function resolveConfigDir(
+  env: Record<string, string | undefined>,
+): string {
+  const vellumEnv = resolveEnvironmentName(env);
+  const xdgConfigHome =
+    env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
+  if (vellumEnv === PRODUCTION_ENVIRONMENT_NAME) {
+    return path.join(xdgConfigHome, "vellum");
+  }
+  return path.join(xdgConfigHome, `vellum-${vellumEnv}`);
+}

package/node_modules/@vellumai/local-mode/src/environment.ts

@@ -0,0 +1,62 @@
+import { existsSync, readFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const PRODUCTION_ENVIRONMENT_NAME = "production";
+
+/**
+ * Location of the persisted default-environment file, written by
+ * `vellum env set`. It lives at a fixed, environment-agnostic path so it can
+ * be read before the environment is known. Honors `XDG_CONFIG_HOME`, falling
+ * back to `~/.config`.
+ */
+export function defaultEnvironmentFilePath(
+  env: Record<string, string | undefined>,
+): string {
+  const xdgConfigHome =
+    env.XDG_CONFIG_HOME?.trim() || path.join(os.homedir(), ".config");
+  return path.join(xdgConfigHome, "vellum", "environment");
+}
+
+/**
+ * Read the persisted default environment name, or `undefined` when no default
+ * has been set (no file, empty file, or unreadable).
+ */
+export function readDefaultEnvironment(
+  env: Record<string, string | undefined>,
+): string | undefined {
+  const filePath = defaultEnvironmentFilePath(env);
+  try {
+    if (!existsSync(filePath)) return undefined;
+    const content = readFileSync(filePath, "utf-8").trim();
+    return content.length > 0 ? content : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Resolve the active environment name from a single source of truth so every
+ * local-mode host — the CLI `client` server, the web app's Vite dev
+ * middleware, and the Electron main process — reads and writes the same
+ * lockfile and config directory.
+ *
+ * Resolution order matches the CLI's `resolveEnvironmentSource`:
+ *   1. `VELLUM_ENVIRONMENT` (explicit override, also inherited by the
+ *      hatch/retire child processes the CLI spawns)
+ *   2. the persisted default written by `vellum env set`
+ *   3. `production`
+ *
+ * Resolving the persisted default here — rather than only inspecting
+ * `VELLUM_ENVIRONMENT` — is what keeps a host that did not go through the CLI's
+ * resolver (the Electron main) pointed at the same environment the CLI uses.
+ */
+export function resolveEnvironmentName(
+  env: Record<string, string | undefined>,
+): string {
+  return (
+    env.VELLUM_ENVIRONMENT?.trim() ||
+    readDefaultEnvironment(env) ||
+    PRODUCTION_ENVIRONMENT_NAME
+  );
+}

package/node_modules/@vellumai/local-mode/src/gateway-proxy.ts

@@ -0,0 +1,109 @@
+import fs from "node:fs";
+
+const GATEWAY_PATTERN = /^(?:\/assistant)?\/__gateway\/(\d+)(\/.*)?$/;
+
+export interface GatewayTarget {
+  port: number;
+  path: string;
+}
+
+export type GatewayParseResult =
+  | { match: true; valid: true; target: GatewayTarget }
+  | { match: true; valid: false }
+  | { match: false };
+
+export function parseGatewayUrl(pathname: string): GatewayParseResult {
+  const match = pathname.match(GATEWAY_PATTERN);
+  if (!match) return { match: false };
+
+  const port = parseInt(match[1]!, 10);
+  if (port < 1024 || port > 65535) return { match: true, valid: false };
+
+  return { match: true, valid: true, target: { port, path: match[2] || "/" } };
+}
+
+/**
+ * Verdict for a gateway-proxy URL, combining the URL parse with the
+ * lockfile port-allowlist check into one decision a host can act on
+ * without re-deriving the rules.
+ *
+ *   - `pass`          — not a gateway URL; the host serves it normally.
+ *   - `invalid-port`  — a gateway URL whose port is outside 1024–65535.
+ *   - `forbidden-port`— a well-formed gateway URL for a port that isn't
+ *                       registered in the lockfile (the security
+ *                       boundary: the proxy only reaches gateway ports
+ *                       the user actually hatched, never arbitrary
+ *                       loopback services).
+ *   - `forward`       — forward to `127.0.0.1:{port}{path}`.
+ */
+export type GatewayProxyDecision =
+  | { kind: "pass" }
+  | { kind: "invalid-port" }
+  | { kind: "forbidden-port"; port: number }
+  | { kind: "forward"; target: GatewayTarget };
+
+/**
+ * Resolve a request pathname to a gateway-proxy verdict. Identical across every
+ * host that proxies the data plane (the Vite dev middleware and the Electron
+ * `app://` protocol handler).
+ *
+ * `getAllowedPorts` is a thunk (typically `() => readAllowedGatewayPorts(...)`)
+ * so the lockfile is read only once a gateway URL is matched — the hot path of
+ * static-asset and non-gateway requests never touches disk.
+ */
+export function resolveGatewayProxyTarget(
+  pathname: string,
+  getAllowedPorts: () => Set<number>,
+): GatewayProxyDecision {
+  const parsed = parseGatewayUrl(pathname);
+  if (!parsed.match) return { kind: "pass" };
+  if (!parsed.valid) return { kind: "invalid-port" };
+  if (!getAllowedPorts().has(parsed.target.port)) {
+    return { kind: "forbidden-port", port: parsed.target.port };
+  }
+  return { kind: "forward", target: parsed.target };
+}
+
+function addPortFromUrl(url: unknown, ports: Set<number>): void {
+  if (typeof url !== "string") return;
+  try {
+    const parsed = new URL(url);
+    if (parsed.hostname !== "127.0.0.1" && parsed.hostname !== "localhost") return;
+    const port = Number(parsed.port);
+    if (Number.isInteger(port) && port >= 1024 && port <= 65535) {
+      ports.add(port);
+    }
+  } catch {
+    // malformed URL — skip
+  }
+}
+
+export function readAllowedGatewayPorts(lockfilePaths: string[]): Set<number> {
+  const ports = new Set<number>();
+  for (const candidate of lockfilePaths) {
+    try {
+      const raw = fs.readFileSync(candidate, "utf-8");
+      const data = JSON.parse(raw) as {
+        assistants?: Array<{
+          gatewayUrl?: unknown;
+          localUrl?: unknown;
+          resources?: { gatewayPort?: unknown };
+        }>;
+      };
+      const assistants = Array.isArray(data.assistants) ? data.assistants : [];
+      for (const assistant of assistants) {
+        if (!assistant) continue;
+        addPortFromUrl(assistant.gatewayUrl, ports);
+        addPortFromUrl(assistant.localUrl, ports);
+        const gp = assistant.resources?.gatewayPort;
+        if (typeof gp === "number" && Number.isInteger(gp) && gp >= 1024 && gp <= 65535) {
+          ports.add(gp);
+        }
+      }
+      if (ports.size > 0) return ports;
+    } catch (err: unknown) {
+      if ((err as NodeJS.ErrnoException).code !== "ENOENT") return new Set<number>();
+    }
+  }
+  return ports;
+}

package/node_modules/@vellumai/local-mode/src/guardian-token.ts

@@ -0,0 +1,122 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+import type { CliInvocation } from "./util";
+
+const GUARDIAN_TOKEN_REFRESH_TIMEOUT_MS = 15_000;
+
+interface GuardianTokenData {
+  accessToken: string;
+  accessTokenExpiresAt: string | number;
+  refreshToken: string;
+  refreshTokenExpiresAt: string | number;
+}
+
+function isAccessTokenExpired(data: GuardianTokenData): boolean {
+  const expiresAt = new Date(data.accessTokenExpiresAt).getTime();
+  if (!Number.isFinite(expiresAt)) return true;
+  return Date.now() >= expiresAt - 60_000;
+}
+
+function isRefreshTokenExpired(data: GuardianTokenData): boolean {
+  const expiresAt = new Date(data.refreshTokenExpiresAt).getTime();
+  if (!Number.isFinite(expiresAt)) return true;
+  return Date.now() >= expiresAt;
+}
+
+export type TokenResult =
+  | { ok: true; accessToken: string }
+  | { ok: false; status: number; error: string };
+
+export function getGuardianAccessToken(
+  assistantId: string,
+  configDir: string,
+  invocation: CliInvocation,
+  isLoopback: boolean,
+  env?: Record<string, string>,
+): Promise<TokenResult> {
+  if (!isLoopback) {
+    return Promise.resolve({ ok: false, status: 403, error: "Forbidden" });
+  }
+
+  const tokenPath = path.join(configDir, "assistants", assistantId, "guardian-token.json");
+
+  let raw: string;
+  try {
+    raw = fs.readFileSync(tokenPath, "utf-8");
+  } catch {
+    return Promise.resolve({ ok: false, status: 404, error: "Guardian token not found" });
+  }
+
+  let data: GuardianTokenData;
+  try {
+    data = JSON.parse(raw) as GuardianTokenData;
+  } catch {
+    return Promise.resolve({ ok: false, status: 500, error: "Malformed guardian token file" });
+  }
+
+  if (!isAccessTokenExpired(data)) {
+    return Promise.resolve({ ok: true, accessToken: data.accessToken });
+  }
+
+  if (isRefreshTokenExpired(data)) {
+    return Promise.resolve({
+      ok: false,
+      status: 401,
+      error: "Guardian token expired — re-run `vellum hatch` or `vellum wake`",
+    });
+  }
+
+  return refreshToken(assistantId, invocation, env);
+}
+
+function refreshToken(
+  assistantId: string,
+  invocation: CliInvocation,
+  env?: Record<string, string>,
+): Promise<TokenResult> {
+  return new Promise((resolve) => {
+    const child = spawn(
+      invocation.command,
+      [...invocation.baseArgs, "gateway", "token", "refresh", assistantId],
+      { stdio: ["ignore", "pipe", "pipe"], env: { ...process.env, ...env } },
+    );
+
+    let stdout = "";
+    let done = false;
+
+    const finish = (result: TokenResult) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timeout);
+      resolve(result);
+    };
+
+    const timeout = setTimeout(() => {
+      child.kill("SIGTERM");
+      finish({ ok: false, status: 500, error: "Guardian token refresh timed out" });
+    }, GUARDIAN_TOKEN_REFRESH_TIMEOUT_MS);
+
+    child.stdout.on("data", (chunk: Buffer) => {
+      stdout += chunk.toString();
+    });
+
+    child.on("close", (code) => {
+      if (code === 0) {
+        const accessToken = stdout.trim();
+        if (accessToken) {
+          finish({ ok: true, accessToken });
+        } else {
+          finish({ ok: false, status: 500, error: "CLI returned empty token" });
+        }
+      } else {
+        finish({ ok: false, status: 401, error: "Failed to refresh guardian token" });
+      }
+    });
+
+    child.on("error", (err) => {
+      finish({ ok: false, status: 500, error: `Failed to spawn CLI: ${err.message}` });
+    });
+  });
+}

package/node_modules/@vellumai/local-mode/src/hatch.ts

@@ -0,0 +1,92 @@
+import { spawn } from "node:child_process";
+
+import type { CliInvocation } from "./util";
+
+const HATCH_TIMEOUT_MS = 120_000;
+// Docker hatches pull images and wait up to 5 min for container readiness.
+const DOCKER_HATCH_TIMEOUT_MS = 10 * 60 * 1000;
+
+export type HatchResult =
+  | { ok: true; assistantId: string }
+  | { ok: false; status: number; error: string };
+
+export interface RunHatchOptions {
+  remote?: string;
+}
+
+export function runHatch(
+  invocation: CliInvocation,
+  species: string,
+  options?: RunHatchOptions,
+): Promise<HatchResult> {
+  return new Promise((resolve) => {
+    const args = [...invocation.baseArgs, "hatch", species];
+    if (options?.remote) {
+      args.push("--remote", options.remote);
+    }
+
+    const child = spawn(
+      invocation.command,
+      args,
+      { stdio: ["ignore", "pipe", "pipe"] },
+    );
+
+    let stdout = "";
+    let stderr = "";
+    let done = false;
+
+    const finish = (result: HatchResult) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timeout);
+      resolve(result);
+    };
+
+    const timeoutMs =
+      options?.remote === "docker" ? DOCKER_HATCH_TIMEOUT_MS : HATCH_TIMEOUT_MS;
+    const timeout = setTimeout(() => {
+      child.kill("SIGTERM");
+      finish({
+        ok: false,
+        status: 500,
+        error: `Hatch timed out after ${timeoutMs / 1000} seconds`,
+      });
+    }, timeoutMs);
+
+    child.stdout.on("data", (data: Buffer) => {
+      stdout += data.toString();
+    });
+
+    child.stderr.on("data", (data: Buffer) => {
+      stderr += data.toString();
+    });
+
+    child.on("close", (code) => {
+      if (code !== 0) {
+        const error =
+          stderr.trim() ||
+          stdout.trim() ||
+          `Hatch failed: the CLI exited with code ${code ?? "unknown"} and produced no output.`;
+        finish({ ok: false, status: 500, error });
+        return;
+      }
+      const assistantId = stdout
+        .match(/Hatching (?:local|Docker) assistant:\s+(.+)/)?.[1]
+        ?.trim();
+      if (!assistantId) {
+        finish({
+          ok: false,
+          status: 500,
+          error:
+            "Hatch reported success but no assistant id was found in the CLI output.",
+        });
+        return;
+      }
+      finish({ ok: true, assistantId });
+    });
+
+    child.on("error", (err) => {
+      finish({ ok: false, status: 500, error: `Failed to spawn CLI: ${err.message}` });
+    });
+  });
+}

package/node_modules/@vellumai/local-mode/src/index.ts

@@ -0,0 +1,48 @@
+/**
+ * @vellumai/local-mode — shared host library for serving the local-assistant
+ * surface (lockfile reads, guardian-token issuance, gateway proxying, and the
+ * hatch/retire/wake lifecycle ops) over a loopback HTTP boundary. Consumed by the
+ * CLI `client` server and the web app's dev-server middleware so the local
+ * endpoint behaviour is defined exactly once instead of one host reaching into
+ * another's source tree. Depends only on `@vellumai/environments`.
+ */
+export {
+  stripSensitiveFields,
+  isLoopbackAddr,
+  resolveDevCliInvocation,
+} from "./util";
+export type { CliInvocation } from "./util";
+export { resolveLocalConfigFromEnv, resolveLockfilePaths, resolveConfigDir } from "./config";
+export type { LocalEndpointConfig } from "./config";
+export { defaultEnvironmentFilePath, readDefaultEnvironment, resolveEnvironmentName } from "./environment";
+export {
+  getLockfileData,
+  upsertLockfileAssistant,
+  replacePlatformAssistants,
+} from "./lockfile";
+export type { LockfileResult, WriteResult } from "./lockfile";
+export { parseLockfile } from "./lockfile-contract";
+export type {
+  Lockfile,
+  LockfileAssistant,
+  LocalAssistantResources,
+  LockfileWriteResult,
+} from "./lockfile-contract";
+export { runHatch } from "./hatch";
+export type { HatchResult } from "./hatch";
+export { runRetire } from "./retire";
+export type { RetireResult } from "./retire";
+export { runWake } from "./wake";
+export type { WakeResult } from "./wake";
+export { getGuardianAccessToken } from "./guardian-token";
+export type { TokenResult } from "./guardian-token";
+export {
+  parseGatewayUrl,
+  readAllowedGatewayPorts,
+  resolveGatewayProxyTarget,
+} from "./gateway-proxy";
+export type {
+  GatewayTarget,
+  GatewayParseResult,
+  GatewayProxyDecision,
+} from "./gateway-proxy";