@vellumai/cli 0.8.5 → 0.8.7

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,74 @@
+import { spawn } from "node:child_process";
+
+import type { CliInvocation } from "./util";
+
+const HATCH_TIMEOUT_MS = 120_000;
+
+export type HatchResult =
+  | { ok: true; assistantId: string }
+  | { ok: false; status: number; error: string };
+
+export function runHatch(
+  invocation: CliInvocation,
+  species: string,
+): Promise<HatchResult> {
+  return new Promise((resolve) => {
+    const child = spawn(
+      invocation.command,
+      [...invocation.baseArgs, "hatch", species],
+      { 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 timeout = setTimeout(() => {
+      child.kill("SIGTERM");
+      finish({ ok: false, status: 500, error: "Hatch timed out after 120 seconds" });
+    }, HATCH_TIMEOUT_MS);
+
+    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 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,26 @@
+/**
+ * @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
+ * 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 { getLockfileData, upsertLockfileAssistant, replacePlatformAssistants } from "./lockfile";
+export type { LockfileResult, WriteResult } from "./lockfile";
+export { runHatch } from "./hatch";
+export type { HatchResult } from "./hatch";
+export { runRetire } from "./retire";
+export type { RetireResult } from "./retire";
+export { getGuardianAccessToken } from "./guardian-token";
+export type { TokenResult } from "./guardian-token";
+export { parseGatewayUrl, readAllowedGatewayPorts } from "./gateway-proxy";
+export type { GatewayTarget, GatewayParseResult } from "./gateway-proxy";

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

@@ -0,0 +1,131 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { stripSensitiveFields } from "./util";
+
+export type LockfileResult =
+  | { ok: true; data: Record<string, unknown> }
+  | { ok: false; status: number; error?: string };
+
+export function getLockfileData(lockfilePaths: string[]): LockfileResult {
+  let raw: string | undefined;
+  for (const candidate of lockfilePaths) {
+    try {
+      raw = fs.readFileSync(candidate, "utf-8");
+      break;
+    } catch (err: unknown) {
+      if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
+        return { ok: false, status: 500 };
+      }
+    }
+  }
+
+  if (!raw) {
+    return { ok: true, data: { assistants: [], activeAssistant: null } };
+  }
+
+  try {
+    const data = JSON.parse(raw) as Record<string, unknown>;
+    stripSensitiveFields(data);
+    return { ok: true, data };
+  } catch {
+    return { ok: false, status: 500 };
+  }
+}
+
+export type WriteResult =
+  | { ok: true; lockfile: Record<string, unknown> }
+  | { ok: false; status: number; error: string };
+
+export function upsertLockfileAssistant(
+  lockfilePaths: string[],
+  assistant: Record<string, unknown>,
+  activeAssistant: string | undefined,
+): WriteResult {
+  if (!assistant || typeof assistant.assistantId !== "string") {
+    return { ok: false, status: 400, error: "Missing assistant.assistantId" };
+  }
+
+  let lockfile: Record<string, unknown> = { assistants: [], activeAssistant: null };
+  for (const candidate of lockfilePaths) {
+    try {
+      lockfile = JSON.parse(fs.readFileSync(candidate, "utf-8")) as Record<string, unknown>;
+      break;
+    } catch {
+      // continue
+    }
+  }
+
+  const assistants = Array.isArray(lockfile.assistants) ? lockfile.assistants : [];
+  const existingIdx = assistants.findIndex(
+    (a: Record<string, unknown>) => a?.assistantId === assistant.assistantId,
+  );
+  if (existingIdx >= 0) {
+    assistants[existingIdx] = { ...assistants[existingIdx], ...assistant };
+  } else {
+    assistants.push(assistant);
+  }
+  lockfile.assistants = assistants;
+  if (activeAssistant !== undefined) {
+    lockfile.activeAssistant = activeAssistant;
+  }
+
+  const writePath = lockfilePaths[0]!;
+  try {
+    const dir = path.dirname(writePath);
+    fs.mkdirSync(dir, { recursive: true });
+    const tmp = `${writePath}.tmp.${process.pid}`;
+    fs.writeFileSync(tmp, JSON.stringify(lockfile, null, 2));
+    fs.renameSync(tmp, writePath);
+  } catch (err) {
+    return { ok: false, status: 500, error: `Failed to write lockfile: ${err}` };
+  }
+
+  const stripped = JSON.parse(JSON.stringify(lockfile)) as Record<string, unknown>;
+  stripSensitiveFields(stripped);
+  return { ok: true, lockfile: stripped };
+}
+
+export function replacePlatformAssistants(
+  lockfilePaths: string[],
+  platformAssistants: Array<Record<string, unknown>>,
+): WriteResult {
+  let lockfile: Record<string, unknown> = { assistants: [], activeAssistant: null };
+  for (const candidate of lockfilePaths) {
+    try {
+      lockfile = JSON.parse(fs.readFileSync(candidate, "utf-8")) as Record<string, unknown>;
+      break;
+    } catch {
+      // continue
+    }
+  }
+
+  const existing = Array.isArray(lockfile.assistants) ? lockfile.assistants : [];
+  const local = existing.filter(
+    (a: Record<string, unknown>) => a?.cloud !== "vellum",
+  );
+  lockfile.assistants = [...local, ...platformAssistants];
+
+  const active = lockfile.activeAssistant as string | null;
+  if (active) {
+    const stillExists = (lockfile.assistants as Array<Record<string, unknown>>).some(
+      (a) => a.assistantId === active,
+    );
+    if (!stillExists) lockfile.activeAssistant = null;
+  }
+
+  const writePath = lockfilePaths[0]!;
+  try {
+    const dir = path.dirname(writePath);
+    fs.mkdirSync(dir, { recursive: true });
+    const tmp = `${writePath}.tmp.${process.pid}`;
+    fs.writeFileSync(tmp, JSON.stringify(lockfile, null, 2));
+    fs.renameSync(tmp, writePath);
+  } catch (err) {
+    return { ok: false, status: 500, error: `Failed to write lockfile: ${err}` };
+  }
+
+  const stripped = JSON.parse(JSON.stringify(lockfile)) as Record<string, unknown>;
+  stripSensitiveFields(stripped);
+  return { ok: true, lockfile: stripped };
+}

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

@@ -0,0 +1,58 @@
+import { spawn } from "node:child_process";
+
+import type { CliInvocation } from "./util";
+
+const RETIRE_TIMEOUT_MS = 60_000;
+
+export type RetireResult =
+  | { ok: true }
+  | { ok: false; status: number; error: string };
+
+export function runRetire(
+  invocation: CliInvocation,
+  assistantId: string,
+): Promise<RetireResult> {
+  return new Promise((resolve) => {
+    const child = spawn(
+      invocation.command,
+      [...invocation.baseArgs, "retire", assistantId, "--yes"],
+      { stdio: ["ignore", "pipe", "pipe"] },
+    );
+
+    let stdout = "";
+    let stderr = "";
+    let done = false;
+
+    const finish = (result: RetireResult) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timeout);
+      resolve(result);
+    };
+
+    const timeout = setTimeout(() => {
+      child.kill("SIGTERM");
+      finish({ ok: false, status: 500, error: "Retire timed out after 60 seconds" });
+    }, RETIRE_TIMEOUT_MS);
+
+    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) {
+        finish({ ok: true });
+      } else {
+        finish({ ok: false, status: 500, error: stderr || stdout });
+      }
+    });
+
+    child.on("error", (err) => {
+      finish({ ok: false, status: 500, error: `Failed to spawn CLI: ${err.message}` });
+    });
+  });
+}

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

@@ -0,0 +1,102 @@
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+
+const CLI_PACKAGE_NAME = "@vellumai/cli";
+
+/**
+ * How to invoke the Vellum CLI as a child process: a base command plus the
+ * leading arguments that precede the subcommand. Each host resolves its own
+ * invocation — the dev hosts run the CLI from source via `bun run <entry>`,
+ * a packaged host would point at its bundled runtime — and the shared
+ * lifecycle ops (`runHatch`, `runRetire`, guardian-token refresh) append
+ * their subcommand args to `baseArgs`.
+ */
+export interface CliInvocation {
+  command: string;
+  baseArgs: string[];
+}
+
+const SENSITIVE_FIELDS = [
+  "signingKey",
+  "bearerToken",
+  "guardianBootstrapSecret",
+] as const;
+
+export function stripSensitiveFields(data: Record<string, unknown>): void {
+  const assistants = data.assistants;
+  if (!Array.isArray(assistants)) return;
+  for (const assistant of assistants) {
+    if (assistant && typeof assistant === "object") {
+      const entry = assistant as Record<string, unknown>;
+      for (const field of SENSITIVE_FIELDS) {
+        delete entry[field];
+      }
+      const resources = entry.resources;
+      if (resources && typeof resources === "object") {
+        for (const field of SENSITIVE_FIELDS) {
+          delete (resources as Record<string, unknown>)[field];
+        }
+      }
+    }
+  }
+}
+
+export function isLoopbackAddr(addr: string): boolean {
+  const v4Mapped = addr.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/i);
+  const normalized = v4Mapped ? v4Mapped[1]! : addr;
+  if (normalized.includes(".")) {
+    return normalized.startsWith("127.");
+  }
+  return normalized === "::1";
+}
+
+let _resolvedCliPath: string | undefined;
+
+/**
+ * Resolve the CLI entry point.
+ *
+ * 1. Source tree — `<baseDir>/cli/src/index.ts` (dev mode in monorepo).
+ * 2. Installed package — `require.resolve("@vellumai/cli/package.json")`.
+ */
+function resolveCliPath(baseDir: string, importMetaUrl?: string): string {
+  if (_resolvedCliPath) return _resolvedCliPath;
+
+  const sourceTreePath = path.join(baseDir, "cli", "src", "index.ts");
+  if (fs.existsSync(sourceTreePath)) {
+    _resolvedCliPath = sourceTreePath;
+    return _resolvedCliPath;
+  }
+
+  const _require = createRequire(importMetaUrl ?? `file://${baseDir}/`);
+  try {
+    const pkgPath = _require.resolve(`${CLI_PACKAGE_NAME}/package.json`);
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8")) as { bin?: Record<string, string> };
+    const binEntry = pkg.bin?.["vellum"];
+    if (binEntry) {
+      const entryPoint = path.resolve(path.dirname(pkgPath), binEntry);
+      if (fs.existsSync(entryPoint)) {
+        _resolvedCliPath = entryPoint;
+        return _resolvedCliPath;
+      }
+    }
+  } catch {
+    // Not found in node_modules
+  }
+
+  throw new Error(
+    `Vellum CLI not found. Looked for source tree at ${sourceTreePath} and npm package ${CLI_PACKAGE_NAME}.`,
+  );
+}
+
+/**
+ * Build the CLI invocation used by the dev hosts (CLI client server and the
+ * web dev-server middleware), which run the CLI from source via Bun:
+ * `bun run <cli-entry> <subcommand> …`.
+ */
+export function resolveDevCliInvocation(
+  baseDir: string,
+  importMetaUrl?: string,
+): CliInvocation {
+  return { command: "bun", baseArgs: ["run", resolveCliPath(baseDir, importMetaUrl)] };
+}

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

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "noEmit": true,
+    "types": ["bun-types"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.8.5",
+  "version": "0.8.7",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {
@@ -8,6 +8,10 @@
     "./package.json": "./package.json",
     "./src/components/DefaultMainScreen": "./src/components/DefaultMainScreen.tsx",
     "./src/lib/constants": "./src/lib/constants.ts",
+    "./src/lib/hatch-local": "./src/lib/hatch-local.ts",
+    "./src/lib/retire-local": "./src/lib/retire-local.ts",
+    "./src/lib/guardian-token": "./src/lib/guardian-token.ts",
+    "./src/lib/lifecycle-reporter": "./src/lib/lifecycle-reporter.ts",
     "./src/commands/*": "./src/commands/*.ts"
   },
   "bin": {
@@ -18,18 +22,25 @@
     "format:check": "prettier --check .",
     "lint": "eslint",
     "lint:unused": "knip --include files,dependencies,unlisted",
+    "prepack": "node ../scripts/prepack-bundled-deps.mjs",
     "test": "bun test",
     "typecheck": "bunx tsc --noEmit"
   },
   "author": "Vellum AI",
   "license": "MIT",
   "dependencies": {
+    "@vellumai/environments": "file:../packages/environments",
+    "@vellumai/local-mode": "file:../packages/local-mode",
     "chalk": "5.6.2",
     "ink": "6.8.0",
     "nanoid": "5.1.7",
     "react": "19.2.4",
     "react-devtools-core": "6.1.5"
   },
+  "bundledDependencies": [
+    "@vellumai/environments",
+    "@vellumai/local-mode"
+  ],
   "devDependencies": {
     "@types/bun": "1.3.11",
     "@types/react": "19.2.14",

package/src/__tests__/backup.test.ts

@@ -162,6 +162,16 @@ beforeEach(() => {
   });
   getBackupsDirMock.mockReset();
   getBackupsDirMock.mockReturnValue("/tmp/backups-default");
+  loadGuardianTokenSpy.mockReset();
+  loadGuardianTokenSpy.mockReturnValue({
+    accessToken: "local-token",
+    accessTokenExpiresAt: new Date(Date.now() + 60_000).toISOString(),
+  } as unknown as ReturnType<typeof guardianToken.loadGuardianToken>);
+  leaseGuardianTokenSpy.mockReset();
+  leaseGuardianTokenSpy.mockResolvedValue({
+    accessToken: "leased-token",
+    accessTokenExpiresAt: new Date(Date.now() + 60_000).toISOString(),
+  } as unknown as Awaited<ReturnType<typeof guardianToken.leaseGuardianToken>>);
   mkdirSyncMock.mockReset();
   mkdirSyncMock.mockImplementation((() => undefined) as never);
   writeFileSyncMock.mockReset();
@@ -207,6 +217,34 @@ function mockGcsDownload(body: Uint8Array, ok = true, status = 200) {
   }) as unknown as typeof globalThis.fetch;
 }
 
+describe("vellum backup <local>: guardian bootstrap secret", () => {
+  test("passes the lockfile bootstrap secret when leasing a fresh guardian token", async () => {
+    const localEntry = {
+      assistantId: "local-assistant",
+      runtimeUrl: "http://127.0.0.1:7830",
+      cloud: "local",
+      guardianBootstrapSecret: "bootstrap-secret-value",
+    } satisfies assistantConfig.AssistantEntry;
+    findAssistantByNameMock.mockReturnValue(localEntry);
+    loadGuardianTokenSpy.mockReturnValue(null);
+    setArgv("my-local", "--output", "/tmp/local-backup.vbundle");
+
+    globalThis.fetch = mock(async () => {
+      return new Response(new Uint8Array([1, 2, 3]), {
+        status: 200,
+      });
+    }) as unknown as typeof globalThis.fetch;
+
+    await backup();
+
+    expect(leaseGuardianTokenSpy).toHaveBeenCalledWith(
+      "http://127.0.0.1:7830",
+      "local-assistant",
+      "bootstrap-secret-value",
+    );
+  });
+});
+
 describe("vellum backup <platform-managed>: GCS happy path", () => {
   test("requests upload URL → kicks off runtime export → polls → downloads from GCS → writes file", async () => {
     findAssistantByNameMock.mockReturnValue(VELLUM_ENTRY);