@vellumai/cli 0.8.7 → 0.8.8-dev.202606052332.17fc8ea

package/node_modules/@vellumai/local-mode/package.json

@@ -5,7 +5,8 @@
   "license": "MIT",
   "type": "module",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./contract": "./src/lockfile-contract.ts"
   },
   "scripts": {
     "typecheck": "bunx tsc --noEmit",

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

@@ -0,0 +1,116 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import {
+  defaultEnvironmentFilePath,
+  readDefaultEnvironment,
+  resolveEnvironmentName,
+} from "../environment";
+import { resolveLockfilePaths, resolveConfigDir } from "../config";
+
+let configHome: string;
+
+/** Write the persisted default-environment file under the temp config home. */
+function persistDefault(name: string): void {
+  const file = path.join(configHome, "vellum", "environment");
+  mkdirSync(path.dirname(file), { recursive: true });
+  writeFileSync(file, name + "\n", "utf-8");
+}
+
+beforeEach(() => {
+  configHome = mkdtempSync(path.join(os.tmpdir(), "vellum-env-"));
+});
+
+afterEach(() => {
+  rmSync(configHome, { recursive: true, force: true });
+});
+
+describe("defaultEnvironmentFilePath", () => {
+  test("honors XDG_CONFIG_HOME", () => {
+    expect(defaultEnvironmentFilePath({ XDG_CONFIG_HOME: configHome })).toBe(
+      path.join(configHome, "vellum", "environment"),
+    );
+  });
+
+  test("falls back to ~/.config", () => {
+    expect(defaultEnvironmentFilePath({})).toBe(
+      path.join(os.homedir(), ".config", "vellum", "environment"),
+    );
+  });
+});
+
+describe("readDefaultEnvironment", () => {
+  test("returns undefined when no file exists", () => {
+    expect(
+      readDefaultEnvironment({ XDG_CONFIG_HOME: configHome }),
+    ).toBeUndefined();
+  });
+
+  test("returns the trimmed persisted name", () => {
+    persistDefault("dev");
+    expect(readDefaultEnvironment({ XDG_CONFIG_HOME: configHome })).toBe("dev");
+  });
+
+  test("treats an empty file as no default", () => {
+    const file = path.join(configHome, "vellum", "environment");
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(file, "  \n", "utf-8");
+    expect(
+      readDefaultEnvironment({ XDG_CONFIG_HOME: configHome }),
+    ).toBeUndefined();
+  });
+});
+
+describe("resolveEnvironmentName", () => {
+  test("prefers VELLUM_ENVIRONMENT over the persisted default", () => {
+    persistDefault("dev");
+    expect(
+      resolveEnvironmentName({
+        XDG_CONFIG_HOME: configHome,
+        VELLUM_ENVIRONMENT: "staging",
+      }),
+    ).toBe("staging");
+  });
+
+  test("falls back to the persisted default when the env var is unset", () => {
+    persistDefault("dev");
+    expect(resolveEnvironmentName({ XDG_CONFIG_HOME: configHome })).toBe("dev");
+  });
+
+  test("falls back to production when neither is set", () => {
+    expect(resolveEnvironmentName({ XDG_CONFIG_HOME: configHome })).toBe(
+      "production",
+    );
+  });
+});
+
+describe("path resolvers honor the persisted default", () => {
+  test("resolveLockfilePaths points at the persisted environment", () => {
+    persistDefault("dev");
+    const env = { XDG_CONFIG_HOME: configHome };
+    expect(resolveLockfilePaths(env)).toEqual([
+      path.join(configHome, "vellum-dev", "lockfile.json"),
+    ]);
+  });
+
+  test("resolveConfigDir points at the persisted environment", () => {
+    persistDefault("dev");
+    expect(resolveConfigDir({ XDG_CONFIG_HOME: configHome })).toBe(
+      path.join(configHome, "vellum-dev"),
+    );
+  });
+
+  test("VELLUM_ENVIRONMENT still wins for path resolution", () => {
+    persistDefault("dev");
+    const env = {
+      XDG_CONFIG_HOME: configHome,
+      VELLUM_ENVIRONMENT: "production",
+    };
+    expect(resolveLockfilePaths(env)).toEqual([
+      path.join(os.homedir(), ".vellum.lock.json"),
+      path.join(os.homedir(), ".vellum.lockfile.json"),
+    ]);
+  });
+});

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

@@ -0,0 +1,79 @@
+import { describe, expect, test } from "bun:test";
+
+import { resolveGatewayProxyTarget } from "../gateway-proxy";
+
+const allow =
+  (...ports: number[]) =>
+  () =>
+    new Set<number>(ports);
+
+describe("resolveGatewayProxyTarget", () => {
+  test("passes non-gateway pathnames through untouched", () => {
+    expect(resolveGatewayProxyTarget("/index.html", allow(8080))).toEqual({
+      kind: "pass",
+    });
+    expect(resolveGatewayProxyTarget("/assistant/assets/app.js", allow())).toEqual({
+      kind: "pass",
+    });
+  });
+
+  test("forwards an allowlisted port to its loopback target", () => {
+    expect(
+      resolveGatewayProxyTarget("/__gateway/8080/v1/assistants", allow(8080)),
+    ).toEqual({
+      kind: "forward",
+      target: { port: 8080, path: "/v1/assistants" },
+    });
+  });
+
+  test("accepts the renderer's `/assistant` mount prefix", () => {
+    expect(
+      resolveGatewayProxyTarget("/assistant/__gateway/8080/auth/token", allow(8080)),
+    ).toEqual({
+      kind: "forward",
+      target: { port: 8080, path: "/auth/token" },
+    });
+  });
+
+  test("defaults a portless tail to the gateway root", () => {
+    expect(resolveGatewayProxyTarget("/__gateway/8080", allow(8080))).toEqual({
+      kind: "forward",
+      target: { port: 8080, path: "/" },
+    });
+  });
+
+  test("rejects ports outside the 1024–65535 range as invalid", () => {
+    expect(resolveGatewayProxyTarget("/__gateway/80/v1", allow(80))).toEqual({
+      kind: "invalid-port",
+    });
+    expect(resolveGatewayProxyTarget("/__gateway/70000/v1", allow(70000))).toEqual({
+      kind: "invalid-port",
+    });
+  });
+
+  test("forbids a well-formed port that isn't registered in the lockfile", () => {
+    expect(
+      resolveGatewayProxyTarget("/__gateway/9999/v1", allow(8080)),
+    ).toEqual({ kind: "forbidden-port", port: 9999 });
+  });
+
+  test("forbids every gateway port when the allowlist is empty", () => {
+    expect(resolveGatewayProxyTarget("/__gateway/8080/v1", allow())).toEqual({
+      kind: "forbidden-port",
+      port: 8080,
+    });
+  });
+
+  test("never reads the allowlist for non-gateway or invalid-port paths", () => {
+    let reads = 0;
+    const counting = () => {
+      reads += 1;
+      return new Set<number>([8080]);
+    };
+    resolveGatewayProxyTarget("/index.html", counting);
+    resolveGatewayProxyTarget("/__gateway/80/v1", counting);
+    expect(reads).toBe(0);
+    resolveGatewayProxyTarget("/__gateway/8080/v1", counting);
+    expect(reads).toBe(1);
+  });
+});

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

@@ -45,6 +45,21 @@ describe("runHatch", () => {
     expect(spawnArgs[0]).toEqual(["bun", ["run", "cli", "hatch", "vellum"]]);
   });
 
+  test("parses the assistant id from a Docker hatch banner", async () => {
+    const pending = runHatch(invocation, "vellum", { remote: "docker" });
+    lastChild.stdout.emit(
+      "data",
+      Buffer.from("🥚 Hatching Docker assistant: asst-docker\n"),
+    );
+    lastChild.emit("close", 0);
+
+    expect(await pending).toEqual({ ok: true, assistantId: "asst-docker" });
+    expect(spawnArgs[0]).toEqual([
+      "bun",
+      ["run", "cli", "hatch", "vellum", "--remote", "docker"],
+    ]);
+  });
+
   test("a non-zero exit resolves to a failure carrying the CLI's output", async () => {
     const pending = runHatch(invocation, "vellum");
     lastChild.stderr.emit("data", Buffer.from("daemon already running"));

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

@@ -3,6 +3,8 @@ import path from "node:path";
 
 import { SEEDS } from "@vellumai/environments";
 
+import { resolveEnvironmentName } from "./environment";
+
 const PRODUCTION_ENVIRONMENT_NAME = "production";
 
 export interface LocalEndpointConfig {
@@ -13,13 +15,14 @@ export interface LocalEndpointConfig {
 }
 
 /**
- * Resolve config from environment variables (Vite plugin context, where
- * `env` comes from `loadEnv` and process.env).
+ * 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>,
+  env: Record<string, string | undefined>,
 ): LocalEndpointConfig {
-  const vellumEnv = env.VELLUM_ENVIRONMENT || PRODUCTION_ENVIRONMENT_NAME;
+  const vellumEnv = resolveEnvironmentName(env);
   const seed = SEEDS[vellumEnv] ?? SEEDS[PRODUCTION_ENVIRONMENT_NAME]!;
 
   return {
@@ -30,8 +33,10 @@ export function resolveLocalConfigFromEnv(
   };
 }
 
-export function resolveLockfilePaths(env: Record<string, string>): string[] {
-  const vellumEnv = env.VELLUM_ENVIRONMENT || PRODUCTION_ENVIRONMENT_NAME;
+export function resolveLockfilePaths(
+  env: Record<string, string | undefined>,
+): string[] {
+  const vellumEnv = resolveEnvironmentName(env);
   const lockfileDir = env.VELLUM_LOCKFILE_DIR;
 
   if (vellumEnv === PRODUCTION_ENVIRONMENT_NAME) {
@@ -48,8 +53,10 @@ export function resolveLockfilePaths(env: Record<string, string>): string[] {
   return [path.join(dir, "lockfile.json")];
 }
 
-export function resolveConfigDir(env: Record<string, string>): string {
-  const vellumEnv = env.VELLUM_ENVIRONMENT || PRODUCTION_ENVIRONMENT_NAME;
+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) {

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

@@ -22,6 +22,48 @@ export function parseGatewayUrl(pathname: string): GatewayParseResult {
   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 {

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

@@ -3,19 +3,31 @@ 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,
-      [...invocation.baseArgs, "hatch", species],
+      args,
       { stdio: ["ignore", "pipe", "pipe"] },
     );
 
@@ -30,10 +42,16 @@ export function runHatch(
       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 120 seconds" });
-    }, HATCH_TIMEOUT_MS);
+      finish({
+        ok: false,
+        status: 500,
+        error: `Hatch timed out after ${timeoutMs / 1000} seconds`,
+      });
+    }, timeoutMs);
 
     child.stdout.on("data", (data: Buffer) => {
       stdout += data.toString();
@@ -53,7 +71,7 @@ export function runHatch(
         return;
       }
       const assistantId = stdout
-        .match(/Hatching local assistant:\s+(.+)/)?.[1]
+        .match(/Hatching (?:local|Docker) assistant:\s+(.+)/)?.[1]
         ?.trim();
       if (!assistantId) {
         finish({

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

@@ -1,7 +1,7 @@
 /**
  * @vellumai/local-mode — shared host library for serving the local-assistant
  * surface (lockfile reads, guardian-token issuance, gateway proxying, and the
- * hatch/retire lifecycle ops) over a loopback HTTP boundary. Consumed by 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`.
@@ -14,13 +14,35 @@ export {
 export type { CliInvocation } from "./util";
 export { resolveLocalConfigFromEnv, resolveLockfilePaths, resolveConfigDir } from "./config";
 export type { LocalEndpointConfig } from "./config";
-export { getLockfileData, upsertLockfileAssistant, replacePlatformAssistants } from "./lockfile";
+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 } from "./gateway-proxy";
-export type { GatewayTarget, GatewayParseResult } from "./gateway-proxy";
+export {
+  parseGatewayUrl,
+  readAllowedGatewayPorts,
+  resolveGatewayProxyTarget,
+} from "./gateway-proxy";
+export type {
+  GatewayTarget,
+  GatewayParseResult,
+  GatewayProxyDecision,
+} from "./gateway-proxy";