@vellumai/cli 0.8.6 → 0.8.7-dev.202606052135.3e62c5a

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

@@ -0,0 +1,173 @@
+import { describe, expect, test } from "bun:test";
+
+import { parseLockfile, type Lockfile } from "./lockfile-contract";
+
+describe("parseLockfile", () => {
+  test("passes through a fully-populated lockfile", () => {
+    const raw = {
+      activeAssistant: "asst_1",
+      assistants: [
+        {
+          assistantId: "asst_1",
+          name: "Alice",
+          cloud: "local",
+          runtimeUrl: "http://127.0.0.1:7777",
+          species: "vellum",
+          hatchedAt: "2026-01-01T00:00:00.000Z",
+          resources: { gatewayPort: 7777, daemonPort: 7778 },
+        },
+      ],
+    };
+
+    expect(parseLockfile(raw)).toEqual(raw as Lockfile);
+  });
+
+  test("keeps entries missing only optional fields", () => {
+    const raw = {
+      activeAssistant: null,
+      assistants: [
+        { assistantId: "asst_1", cloud: "vellum", runtimeUrl: "https://x" },
+      ],
+    };
+
+    const parsed = parseLockfile(raw);
+    expect(parsed.assistants).toHaveLength(1);
+    expect(parsed.assistants[0]).toEqual({
+      assistantId: "asst_1",
+      cloud: "vellum",
+      runtimeUrl: "https://x",
+    });
+  });
+
+  test("salvages a legacy entry that has only an assistantId", () => {
+    // The oldest persisted entries carry just the identity; the CLI fills the
+    // rest in lazily. assistantId is the only required field, so the entry
+    // must survive intact rather than being discarded.
+    const parsed = parseLockfile({
+      activeAssistant: "asst_1",
+      assistants: [{ assistantId: "asst_1" }],
+    });
+    expect(parsed.assistants).toEqual([{ assistantId: "asst_1" }]);
+  });
+
+  test("salvages an entry whose cloud and runtimeUrl are absent", () => {
+    // Older CLI builds predate the `cloud` field and persisted the runtime URL
+    // under a different key (`localUrl`), so a real on-disk entry can lack both
+    // modeled fields. It must still be returned (the macOS↔CLI skew window).
+    const parsed = parseLockfile({
+      activeAssistant: null,
+      assistants: [{ assistantId: "asst_1", localUrl: "http://127.0.0.1:7777" }],
+    });
+    expect(parsed.assistants).toEqual([{ assistantId: "asst_1" }]);
+  });
+
+  test("drops malformed entries but salvages valid siblings", () => {
+    const raw = {
+      activeAssistant: "asst_ok",
+      assistants: [
+        { assistantId: "asst_ok", cloud: "local", runtimeUrl: "http://a" },
+        { cloud: "local", runtimeUrl: "http://b" }, // missing assistantId
+        { assistantId: 42, cloud: "local", runtimeUrl: "http://c" }, // wrong type
+        "not-an-object",
+      ],
+    };
+
+    const parsed = parseLockfile(raw);
+    expect(parsed.assistants).toEqual([
+      { assistantId: "asst_ok", cloud: "local", runtimeUrl: "http://a" },
+    ]);
+    expect(parsed.activeAssistant).toBe("asst_ok");
+  });
+
+  test("accepts (does not reject) entries with unknown fields from a newer writer", () => {
+    const raw = {
+      activeAssistant: "asst_1",
+      schemaVersion: 99, // unknown top-level field from a newer writer
+      assistants: [
+        {
+          assistantId: "asst_1",
+          cloud: "local",
+          runtimeUrl: "http://a",
+          futureField: { nested: true }, // unknown entry field
+        },
+      ],
+    };
+
+    // A newer writer's extra fields must never make an older reader reject the
+    // entry. The entry survives with its modeled fields; the wire value is the
+    // validated shape (extra fields are stripped from it — the on-disk file
+    // keeps them, see lockfile.test.ts).
+    const parsed = parseLockfile(raw);
+    expect(parsed.assistants).toEqual([
+      { assistantId: "asst_1", cloud: "local", runtimeUrl: "http://a" },
+    ]);
+    expect(parsed.activeAssistant).toBe("asst_1");
+  });
+
+  test("defaults missing or non-array assistants to an empty list", () => {
+    expect(parseLockfile({}).assistants).toEqual([]);
+    expect(parseLockfile({ assistants: "nope" }).assistants).toEqual([]);
+  });
+
+  test("coerces a non-string activeAssistant to null", () => {
+    expect(parseLockfile({ assistants: [], activeAssistant: 7 }).activeAssistant).toBeNull();
+    expect(parseLockfile({ assistants: [] }).activeAssistant).toBeNull();
+  });
+
+  test("returns the empty lockfile for non-object input", () => {
+    const empty: Lockfile = { assistants: [], activeAssistant: null };
+    expect(parseLockfile(null)).toEqual(empty);
+    expect(parseLockfile(undefined)).toEqual(empty);
+    expect(parseLockfile("[]")).toEqual(empty);
+    expect(parseLockfile(123)).toEqual(empty);
+  });
+
+  test("drops a mistyped optional field but keeps the entry", () => {
+    // assistantId is the only required field. A mistyped optional field (here
+    // cloud / runtimeUrl) is dropped from the result, but the entry survives on
+    // the strength of its identity rather than being discarded wholesale.
+    const raw = {
+      assistants: [
+        { assistantId: "asst_1", cloud: 7, runtimeUrl: "http://a" }, // cloud not a string
+        { assistantId: "asst_2", cloud: "local", runtimeUrl: 7 }, // runtimeUrl not a string
+      ],
+      activeAssistant: null,
+    };
+    expect(parseLockfile(raw).assistants).toEqual([
+      { assistantId: "asst_1", runtimeUrl: "http://a" },
+      { assistantId: "asst_2", cloud: "local" },
+    ]);
+  });
+
+  test("drops an entry only when its assistantId is missing or mistyped", () => {
+    const raw = {
+      assistants: [
+        { cloud: "local", runtimeUrl: "http://a" }, // no assistantId
+        { assistantId: 42, cloud: "local" }, // assistantId not a string
+      ],
+      activeAssistant: null,
+    };
+    expect(parseLockfile(raw).assistants).toEqual([]);
+  });
+
+  test("drops a resources object missing its numeric ports", () => {
+    const raw = {
+      assistants: [
+        {
+          assistantId: "asst_1",
+          cloud: "local",
+          runtimeUrl: "http://a",
+          resources: { gatewayPort: "7777", daemonPort: 7778 },
+        },
+      ],
+      activeAssistant: null,
+    };
+    const [assistant] = parseLockfile(raw).assistants;
+    expect(assistant).toEqual({
+      assistantId: "asst_1",
+      cloud: "local",
+      runtimeUrl: "http://a",
+    });
+    expect(assistant?.resources).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,114 @@
+/**
+ * The lockfile wire contract — the types and the parser that validates them —
+ * kept in its own module so consumers can import the contract without pulling
+ * in the host I/O graph (`node:fs`, the CLI resolver, the environments
+ * package). The renderer relies on that separation: it imports these types
+ * type-only and must not transitively reference Node built-ins.
+ *
+ * Validation is hand-written rather than schema-library-based on purpose: this
+ * package is inlined from source by three different bundler hosts (the CLI, the
+ * Electron main process, and the web dev server) and deliberately carries no
+ * third-party runtime dependencies (enforced by `__tests__/package-boundary`).
+ * The contract is small enough that a typed parser is clearer than a dependency.
+ *
+ * The lockfile is written by the Vellum CLI and read across the macOS↔CLI
+ * boundary, which do not release in lockstep. The parser is therefore
+ * permissive about unknown fields: it reads only the modeled fields below and
+ * ignores everything else, so a newer writer's extra fields never fail an
+ * older reader. Unknown fields are preserved on disk by the write path (see
+ * `lockfile.ts`); the validated value returned to callers carries only the
+ * modeled shape.
+ *
+ * `assistantId` is the only required field — it is the entry's identity (the
+ * key every reader and the write path look entries up by) and the one field
+ * the CLI always writes. Everything else is optional on disk: older entries
+ * predate the `cloud` field, the runtime URL has historically been persisted
+ * under a different key (`localUrl`), and resource ports are only present for
+ * multi-instance local setups. The parser therefore salvages any entry that
+ * has a string `assistantId` and copies the remaining modeled fields only when
+ * they are present and well-typed, rather than discarding an otherwise-usable
+ * assistant because an optional field is missing or malformed.
+ */
+
+export interface LocalAssistantResources {
+  gatewayPort: number;
+  daemonPort: number;
+}
+
+export interface LockfileAssistant {
+  assistantId: string;
+  name?: string;
+  cloud?: string;
+  runtimeUrl?: string;
+  species?: string;
+  hatchedAt?: string;
+  resources?: LocalAssistantResources;
+}
+
+export interface Lockfile {
+  assistants: LockfileAssistant[];
+  activeAssistant: string | null;
+}
+
+/**
+ * Renderer-facing result of a lockfile write, returned across the host bridge.
+ * Carries no HTTP-style `status` — the hosts map that away because the
+ * renderer surfaces failures by message alone.
+ */
+export type LockfileWriteResult =
+  | { ok: true; lockfile: Lockfile }
+  | { ok: false; error: string };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function parseResources(value: unknown): LocalAssistantResources | undefined {
+  if (!isRecord(value)) return undefined;
+  if (typeof value.gatewayPort !== "number") return undefined;
+  if (typeof value.daemonPort !== "number") return undefined;
+  return { gatewayPort: value.gatewayPort, daemonPort: value.daemonPort };
+}
+
+/**
+ * Validate a single assistant entry. Returns `null` only when the entry lacks a
+ * string `assistantId` (its identity); any other entry is salvaged. Each
+ * optional field is copied only when present and well-typed — a missing or
+ * mistyped optional field is dropped from the result without discarding the
+ * entry — and unknown fields are ignored.
+ */
+function parseAssistant(value: unknown): LockfileAssistant | null {
+  if (!isRecord(value)) return null;
+  if (typeof value.assistantId !== "string") return null;
+
+  const assistant: LockfileAssistant = { assistantId: value.assistantId };
+  if (typeof value.name === "string") assistant.name = value.name;
+  if (typeof value.cloud === "string") assistant.cloud = value.cloud;
+  if (typeof value.runtimeUrl === "string") assistant.runtimeUrl = value.runtimeUrl;
+  if (typeof value.species === "string") assistant.species = value.species;
+  if (typeof value.hatchedAt === "string") assistant.hatchedAt = value.hatchedAt;
+  const resources = parseResources(value.resources);
+  if (resources) assistant.resources = resources;
+  return assistant;
+}
+
+/**
+ * Coerce parsed JSON into a validated `Lockfile`. Total and non-throwing:
+ * individual assistant entries that fail validation are dropped (so one
+ * malformed entry can't discard the whole file), a missing/non-array
+ * `assistants` becomes `[]`, and a non-string `activeAssistant` becomes
+ * `null`. Callers pass the result through unchanged; the only failure modes a
+ * host surfaces are I/O and JSON-parse errors, handled by `getLockfileData`.
+ */
+export function parseLockfile(raw: unknown): Lockfile {
+  const root = isRecord(raw) ? raw : {};
+  const rawAssistants = Array.isArray(root.assistants) ? root.assistants : [];
+  const assistants: LockfileAssistant[] = [];
+  for (const entry of rawAssistants) {
+    const parsed = parseAssistant(entry);
+    if (parsed) assistants.push(parsed);
+  }
+  const activeAssistant =
+    typeof root.activeAssistant === "string" ? root.activeAssistant : null;
+  return { assistants, activeAssistant };
+}

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

@@ -0,0 +1,235 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import {
+  getLockfileData,
+  replacePlatformAssistants,
+  upsertLockfileAssistant,
+} from "./lockfile";
+
+let dir: string;
+let lockfilePath: string;
+
+beforeEach(() => {
+  dir = fs.mkdtempSync(path.join(os.tmpdir(), "lockfile-test-"));
+  lockfilePath = path.join(dir, "lockfile.json");
+});
+
+afterEach(() => {
+  fs.rmSync(dir, { recursive: true, force: true });
+});
+
+function writeOnDisk(value: unknown): void {
+  fs.writeFileSync(lockfilePath, JSON.stringify(value, null, 2));
+}
+
+function readOnDisk(): Record<string, unknown> {
+  return JSON.parse(fs.readFileSync(lockfilePath, "utf-8")) as Record<
+    string,
+    unknown
+  >;
+}
+
+describe("getLockfileData", () => {
+  test("returns the empty lockfile when no file exists", () => {
+    const result = getLockfileData([lockfilePath]);
+    expect(result).toEqual({
+      ok: true,
+      data: { assistants: [], activeAssistant: null },
+    });
+  });
+
+  test("validates and salvages a partially-malformed file", () => {
+    writeOnDisk({
+      activeAssistant: "asst_ok",
+      assistants: [
+        { assistantId: "asst_ok", cloud: "local", runtimeUrl: "http://a" },
+        { cloud: "local", runtimeUrl: "http://b" }, // missing assistantId
+      ],
+    });
+
+    const result = getLockfileData([lockfilePath]);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.data.assistants).toEqual([
+        { assistantId: "asst_ok", cloud: "local", runtimeUrl: "http://a" },
+      ]);
+    }
+  });
+
+  test("salvages a legacy entry that predates cloud/runtimeUrl", () => {
+    // An entry written by an older CLI: no `cloud`, and the runtime URL stored
+    // under the legacy `localUrl` key rather than `runtimeUrl`. Only the
+    // identity is guaranteed, so the entry must still be returned (the modeled
+    // fields it lacks are simply absent on the wire value).
+    writeOnDisk({
+      activeAssistant: "asst_legacy",
+      assistants: [
+        { assistantId: "asst_legacy", localUrl: "http://127.0.0.1:7777" },
+      ],
+    });
+
+    const result = getLockfileData([lockfilePath]);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.data.assistants).toEqual([{ assistantId: "asst_legacy" }]);
+      expect(result.data.activeAssistant).toBe("asst_legacy");
+    }
+  });
+
+  test("fails with status 500 on malformed JSON", () => {
+    fs.writeFileSync(lockfilePath, "{ not json");
+    const result = getLockfileData([lockfilePath]);
+    expect(result).toEqual({ ok: false, status: 500 });
+  });
+});
+
+describe("upsertLockfileAssistant", () => {
+  test("rejects an assistant with no id", () => {
+    const result = upsertLockfileAssistant(
+      [lockfilePath],
+      { cloud: "local" },
+      undefined,
+    );
+    expect(result).toEqual({
+      ok: false,
+      status: 400,
+      error: "Missing assistant.assistantId",
+    });
+  });
+
+  test("preserves unknown on-disk fields written by a newer client", () => {
+    // A newer writer added a top-level field and per-entry fields this build
+    // does not model. Upserting an unrelated assistant must not drop them.
+    writeOnDisk({
+      schemaVersion: 99,
+      activeAssistant: "asst_old",
+      assistants: [
+        {
+          assistantId: "asst_old",
+          cloud: "vellum",
+          runtimeUrl: "http://old",
+          futureField: "keep-me",
+        },
+      ],
+    });
+
+    const result = upsertLockfileAssistant(
+      [lockfilePath],
+      { assistantId: "asst_new", cloud: "local", runtimeUrl: "http://new" },
+      "asst_new",
+    );
+
+    expect(result.ok).toBe(true);
+
+    const onDisk = readOnDisk();
+    expect(onDisk.schemaVersion).toBe(99);
+    const assistants = onDisk.assistants as Array<Record<string, unknown>>;
+    const old = assistants.find((a) => a.assistantId === "asst_old");
+    expect(old?.futureField).toBe("keep-me");
+
+    // The returned wire value is the validated shape (unknown fields stripped).
+    if (result.ok) {
+      expect(result.lockfile.activeAssistant).toBe("asst_new");
+      const wireOld = result.lockfile.assistants.find(
+        (a) => a.assistantId === "asst_old",
+      );
+      expect(wireOld).toEqual({
+        assistantId: "asst_old",
+        cloud: "vellum",
+        runtimeUrl: "http://old",
+      });
+    }
+  });
+
+  test("merges fields into an existing entry", () => {
+    writeOnDisk({
+      activeAssistant: null,
+      assistants: [
+        { assistantId: "asst_1", cloud: "local", runtimeUrl: "http://a" },
+      ],
+    });
+
+    upsertLockfileAssistant(
+      [lockfilePath],
+      { assistantId: "asst_1", name: "Renamed" },
+      undefined,
+    );
+
+    const assistants = readOnDisk().assistants as Array<
+      Record<string, unknown>
+    >;
+    expect(assistants).toHaveLength(1);
+    expect(assistants[0]).toMatchObject({
+      assistantId: "asst_1",
+      cloud: "local",
+      runtimeUrl: "http://a",
+      name: "Renamed",
+    });
+  });
+});
+
+describe("replacePlatformAssistants", () => {
+  test("replaces platform assistants while keeping local ones and unknown fields", () => {
+    writeOnDisk({
+      schemaVersion: 99,
+      activeAssistant: "asst_local",
+      assistants: [
+        { assistantId: "asst_local", cloud: "local", runtimeUrl: "http://l" },
+        {
+          assistantId: "asst_old_platform",
+          cloud: "vellum",
+          runtimeUrl: "http://op",
+        },
+      ],
+    });
+
+    const result = replacePlatformAssistants(
+      [lockfilePath],
+      [
+        {
+          assistantId: "asst_new_platform",
+          cloud: "vellum",
+          runtimeUrl: "http://np",
+        },
+      ],
+    );
+
+    expect(result.ok).toBe(true);
+
+    const onDisk = readOnDisk();
+    expect(onDisk.schemaVersion).toBe(99);
+    const ids = (onDisk.assistants as Array<Record<string, unknown>>).map(
+      (a) => a.assistantId,
+    );
+    expect(ids).toEqual(["asst_local", "asst_new_platform"]);
+  });
+
+  test("clears activeAssistant when the active id no longer exists", () => {
+    writeOnDisk({
+      activeAssistant: "asst_old_platform",
+      assistants: [
+        {
+          assistantId: "asst_old_platform",
+          cloud: "vellum",
+          runtimeUrl: "http://op",
+        },
+      ],
+    });
+
+    replacePlatformAssistants(
+      [lockfilePath],
+      [
+        {
+          assistantId: "asst_new_platform",
+          cloud: "vellum",
+          runtimeUrl: "http://np",
+        },
+      ],
+    );
+
+    expect(readOnDisk().activeAssistant).toBeNull();
+  });
+});

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

@@ -0,0 +1,133 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { parseLockfile, type Lockfile } from "./lockfile-contract";
+import { stripSensitiveFields } from "./util";
+
+export type LockfileResult =
+  | { ok: true; data: Lockfile }
+  | { 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 } };
+  }
+
+  let data: Record<string, unknown>;
+  try {
+    data = JSON.parse(raw) as Record<string, unknown>;
+  } catch {
+    return { ok: false, status: 500 };
+  }
+  stripSensitiveFields(data);
+  return { ok: true, data: parseLockfile(data) };
+}
+
+export type WriteResult =
+  | { ok: true; lockfile: Lockfile }
+  | { 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: parseLockfile(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: parseLockfile(stripped) };
+}