@vellumai/cli 0.11.2 → 0.11.3-staging.1

package/knip.json

@@ -10,6 +10,7 @@
   "project": ["src/**/*.ts", "src/**/*.tsx"],
   "ignoreDependencies": [
     "@vellumai/environments",
+    "@vellumai/ipc-server-utils",
     "@vellumai/local-mode",
     "@vellumai/service-contracts",
     "@vellumai/web"

package/node_modules/@vellumai/environments/package.json

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

package/node_modules/@vellumai/environments/src/__tests__/cloud-assistant-hub-url.test.ts

@@ -0,0 +1,38 @@
+/**
+ * Pins the environment-to-cloud-hub mapping in one place. Both consumers
+ * (the Capacitor shell's `server.url` and the CLI remote-web edge's
+ * `hubUrl`) read this helper, so this matrix is the single behavioral pin
+ * for the served URLs.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import { cloudAssistantHubUrl, SEEDS } from "../index.js";
+
+describe("cloudAssistantHubUrl", () => {
+  test("cloud environments resolve to their own web origin", () => {
+    expect(cloudAssistantHubUrl("production")).toBe(
+      "https://www.vellum.ai/assistant",
+    );
+    expect(cloudAssistantHubUrl("staging")).toBe(
+      "https://staging-assistant.vellum.ai/assistant",
+    );
+  });
+
+  test("every other environment falls back to the dev SPA", () => {
+    for (const name of ["dev", "test", "local", "unknown-env", undefined]) {
+      expect(cloudAssistantHubUrl(name)).toBe(
+        "https://dev-assistant.vellum.ai/assistant",
+      );
+    }
+  });
+
+  test("cloud hub URLs derive from the seed web URLs", () => {
+    for (const name of ["production", "staging"]) {
+      expect(cloudAssistantHubUrl(name)).toBe(
+        `${SEEDS[name].webUrl}/assistant`,
+      );
+    }
+    expect(cloudAssistantHubUrl("local")).toBe(`${SEEDS.dev.webUrl}/assistant`);
+  });
+});

package/node_modules/@vellumai/environments/src/__tests__/install-layout.test.ts

@@ -0,0 +1,98 @@
+/**
+ * Tests for reading an install layout: telling a repo checkout from an
+ * installed package, and locating the `assistant` command that ships with an
+ * install.
+ */
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import { findAssistantCommand, isRepoCheckoutPath } from "../index.js";
+
+let root: string;
+
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), "install-layout-"));
+});
+
+afterEach(() => {
+  rmSync(root, { recursive: true, force: true });
+});
+
+/** Create `<nodeModulesDir>/.bin/assistant` and return its path. */
+function seedCommand(nodeModulesDir: string): string {
+  const binDir = join(nodeModulesDir, ".bin");
+  mkdirSync(binDir, { recursive: true });
+  const command = join(binDir, "assistant");
+  writeFileSync(command, "#!/usr/bin/env bun\n");
+  return command;
+}
+
+describe("isRepoCheckoutPath", () => {
+  test("an installed package is not a checkout", () => {
+    expect(
+      isRepoCheckoutPath(
+        "/Users/x/Library/Application Support/@vellumai/macos/cli/latest/node_modules/@vellumai/assistant/src/index.ts",
+      ),
+    ).toBe(false);
+  });
+
+  test("a repo checkout is", () => {
+    expect(
+      isRepoCheckoutPath("/Users/x/dev/vellum/assistant/src/index.ts"),
+    ).toBe(true);
+  });
+
+  test("a directory merely named node_modules-ish is not enough", () => {
+    expect(
+      isRepoCheckoutPath("/Users/x/node_modules_backup/a/src/index.ts"),
+    ).toBe(true);
+  });
+});
+
+describe("findAssistantCommand", () => {
+  test("finds the command shipped beside an installed package", () => {
+    const nodeModules = join(root, "cli", "latest", "node_modules");
+    const command = seedCommand(nodeModules);
+    const path = join(nodeModules, "@vellumai", "assistant", "src", "index.ts");
+
+    expect(findAssistantCommand(path)).toBe(command);
+  });
+
+  test("prefers a nested install over a hoisted one", () => {
+    const outer = join(root, "node_modules");
+    const outerCommand = seedCommand(outer);
+    const inner = join(outer, "vellum", "node_modules");
+    const innerCommand = seedCommand(inner);
+    const path = join(inner, "@vellumai", "assistant", "src", "index.ts");
+
+    expect(findAssistantCommand(path)).toBe(innerCommand);
+    expect(innerCommand).not.toBe(outerCommand);
+  });
+
+  test("falls back to a hoisted install when the nested one has no command", () => {
+    const outer = join(root, "node_modules");
+    const outerCommand = seedCommand(outer);
+    const inner = join(outer, "vellum", "node_modules");
+    mkdirSync(inner, { recursive: true });
+    const path = join(inner, "@vellumai", "assistant", "src", "index.ts");
+
+    expect(findAssistantCommand(path)).toBe(outerCommand);
+  });
+
+  test("returns null for a repo checkout", () => {
+    expect(
+      findAssistantCommand(join(root, "assistant", "src", "index.ts")),
+    ).toBeNull();
+  });
+
+  test("returns null when the install ships no assistant command", () => {
+    const nodeModules = join(root, "node_modules");
+    mkdirSync(join(nodeModules, ".bin"), { recursive: true });
+    const path = join(nodeModules, "@vellumai", "assistant", "src", "index.ts");
+
+    expect(findAssistantCommand(path)).toBeNull();
+  });
+});

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

@@ -1,10 +1,10 @@
 /**
  * Package boundary tests for @vellumai/environments.
  *
- * This package is the lowest layer of the shared-packages hierarchy: pure
- * environment types and constants with no runtime dependencies. It must
- * stay a leaf so any consumer (CLI, assistant, local-mode host) can depend
- * on it without dragging in a dependency tree.
+ * This package is the lowest layer of the shared-packages hierarchy:
+ * environment types, constants, and small helpers over node builtins, with no
+ * runtime dependencies. It must stay a leaf so any consumer (CLI, assistant,
+ * local-mode host) can depend on it without dragging in a dependency tree.
  *
  * Enforces that the package:
  * 1. Imports only node builtins and its own relative modules — no `@vellumai/*`
@@ -79,7 +79,7 @@ describe("package boundary", () => {
       throw new Error(
         `Found ${violations.length} forbidden import(s) in @vellumai/environments:\n` +
           violations.map((v) => `  - ${v}`).join("\n") +
-          "\n\n@vellumai/environments is a pure types/constants leaf and must\n" +
+          "\n\n@vellumai/environments is a dependency-free leaf and must\n" +
           "import only node builtins and its own relative modules.",
       );
     }

package/node_modules/@vellumai/environments/src/index.ts

@@ -1,11 +1,22 @@
 /**
- * @vellumai/environments — the single source of truth for Vellum's known
- * deployment environments (names, platform/web URLs, per-service port
- * blocks). Consumed by the CLI, the assistant daemon, and the local-mode
- * host library so the environment list is defined exactly once on the TS
- * side. The Swift client mirrors the same set in `VellumEnvironment.swift`.
+ * @vellumai/environments: the single source of truth for how a Vellum install
+ * is laid out and which deployment environment it belongs to.
  *
- * Intentionally free of runtime dependencies: pure types and constants only.
+ * Two things live here:
+ *
+ *   - The known deployment environments (names, platform/web URLs, per-service
+ *     port blocks). The Swift client mirrors the same set in
+ *     `VellumEnvironment.swift`.
+ *   - Install layout: whether a runtime is a repo checkout or an installed
+ *     package, and where the `assistant` command it ships lives.
+ *
+ * Consumed by the CLI, the assistant daemon, and the local-mode host library
+ * so each answer is defined exactly once on the TS side.
+ *
+ * This is the lowest layer of the shared-packages hierarchy and stays a leaf:
+ * types, constants, and small helpers over node builtins, with no runtime
+ * dependencies of its own. See `__tests__/package-boundary.test.ts`.
  */
 export * from "./types.js";
 export * from "./seeds.js";
+export * from "./install-layout.js";

package/node_modules/@vellumai/environments/src/install-layout.ts

@@ -0,0 +1,49 @@
+/**
+ * Reading the layout a Vellum runtime is installed in.
+ *
+ * The daemon is started either from a developer's repo checkout or from an
+ * installed npm package (`<install>/node_modules/@vellumai/assistant/src/
+ * index.ts`, which is what the desktop app runs). The CLI needs the layout to
+ * decide whether a launch is a dev run and what to put on the daemon's PATH;
+ * the daemon needs it to decide what to install as the `assistant` command.
+ * Both ask the same two questions, so they ask them here.
+ */
+
+import { existsSync } from "node:fs";
+import { join, sep } from "node:path";
+
+const NODE_MODULES_SEGMENT = `${sep}node_modules${sep}`;
+
+/**
+ * Whether `path` sits in a developer's repo checkout rather than inside an
+ * installed package.
+ */
+export function isRepoCheckoutPath(path: string): boolean {
+  return !path.includes(NODE_MODULES_SEGMENT);
+}
+
+/**
+ * The `assistant` command shipped with the install that contains `path`, or
+ * null when there is none (a repo checkout, or an install whose dependency
+ * graph omits the package declaring the bin).
+ *
+ * Searches innermost `node_modules` outward, since a nested install shadows a
+ * hoisted one.
+ */
+export function findAssistantCommand(path: string): string | null {
+  let index = path.lastIndexOf(NODE_MODULES_SEGMENT);
+
+  while (index !== -1) {
+    const nodeModulesDir = path.slice(
+      0,
+      index + NODE_MODULES_SEGMENT.length - 1,
+    );
+    const command = join(nodeModulesDir, ".bin", "assistant");
+    if (existsSync(command)) {
+      return command;
+    }
+    index = path.lastIndexOf(NODE_MODULES_SEGMENT, index - 1);
+  }
+
+  return null;
+}

package/node_modules/@vellumai/environments/src/seeds.ts

@@ -24,6 +24,35 @@ function portBlock(base: number): PortMap {
   };
 }
 
+/**
+ * Base URL of the cloud-hosted assistant SPA (the "hub") for a deployment
+ * environment. The Capacitor mobile shell bakes this into native builds as
+ * `server.url`, and the CLI's remote-web edge stamps it into the served
+ * config as `hubUrl`, so the environment-to-hub mapping lives here exactly
+ * once.
+ *
+ * Only the cloud deployments (production, staging) serve the hosted SPA at
+ * their own web origin; every other environment (dev, test, local, unknown)
+ * falls back to the dev SPA, whose host serves remote clients that cannot
+ * reach a local or per-developer web URL.
+ *
+ * The `/assistant` suffix is deliberate: booting on the bare host lands on
+ * the marketing page, whose CTA redirects to `www.vellum.ai/assistant` and
+ * bounces non-prod shells off their own host.
+ *
+ * NOTE: this module is loaded by Capacitor's single-file TS config loader
+ * (via the `@vellumai/environments/seeds` subpath), which cannot follow the
+ * package index's `.js`-suffixed runtime re-exports. Keep this file's
+ * imports type-only so it stays loadable on its own.
+ */
+export function cloudAssistantHubUrl(envName: string | undefined): string {
+  const seed =
+    envName === "production" || envName === "staging"
+      ? SEEDS[envName]
+      : SEEDS.dev;
+  return `${seed.webUrl}/assistant`;
+}
+
 /**
  * Built-in environment definitions and the source of truth for the
  * set of known environment names.

package/node_modules/@vellumai/ipc-server-utils/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@vellumai/ipc-server-utils",
+  "version": "0.0.1",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "bunx tsc --noEmit",
+    "test": "bun test src/"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.10",
+    "typescript": "5.9.3"
+  }
+}

package/node_modules/@vellumai/ipc-server-utils/src/endpoint.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { removeIpcEndpointFile, resolveIpcEndpoint } from "./endpoint.js";
+const windowsEndpoint = (name: string, workspaceDir: string) => resolveIpcEndpoint(name, { workspaceDir, platform: "win32" });
+describe("resolveIpcEndpoint", () => {
+  test("keeps long POSIX fallbacks deterministic and bounded", () => {
+    const options = {
+      workspaceDir: `/tmp/${"a".repeat(120)}`,
+      platform: "darwin" as const,
+    };
+    const endpoint = resolveIpcEndpoint("assistant", options);
+    expect(resolveIpcEndpoint("assistant", options)).toEqual(endpoint);
+    expect(Buffer.byteLength(endpoint.path)).toBeLessThanOrEqual(103);
+  });
+  test("returns normalized, isolated, bounded Windows pipes", () => {
+    const first = windowsEndpoint("assistant", "C:\\one");
+    expect(resolveIpcEndpoint("assistant", { workspaceDir: "c:\\ONE\\", platform: "win32", env: { ASSISTANT_IPC_SOCKET_DIR: "C:\\ignored" } })).toEqual(first);
+    expect(first.path.length).toBeLessThanOrEqual(256);
+    expect(windowsEndpoint("assistant", "C:\\two").path).not.toBe(first.path);
+    expect(windowsEndpoint("gateway", "C:\\one").path).not.toBe(first.path);
+  });
+  test("cleans socket files but skips named pipes", () => {
+    const dir = mkdtempSync(join(tmpdir(), "vellum-ipc-cleanup-"));
+    const socketPath = join(dir, "assistant.sock");
+    try {
+      writeFileSync(socketPath, "stale");
+      removeIpcEndpointFile(socketPath);
+      expect(existsSync(socketPath)).toBe(false);
+      removeIpcEndpointFile("\\\\.\\pipe\\vellum-assistant-test");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/node_modules/@vellumai/ipc-server-utils/src/endpoint.ts

@@ -0,0 +1,142 @@
+import { createHash } from "node:crypto";
+import { unlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { posix, win32 } from "node:path";
+
+const DARWIN_UNIX_SOCKET_MAX_PATH_BYTES = 103;
+const DEFAULT_UNIX_SOCKET_MAX_PATH_BYTES = 107;
+const IPC_TMP_DIR_NAME = "vellum-ipc";
+const join = posix.join;
+
+export type IpcSocketPathSource =
+  | "env-override"
+  | "workspace"
+  | "tmp-hash"
+  | "tmp-short-hash"
+  | "windows-named-pipe";
+
+export interface IpcSocketPathResolution {
+  path: string;
+  source: IpcSocketPathSource;
+}
+
+export interface IpcEndpointOptions {
+  workspaceDir: string;
+  env?: Record<string, string | undefined>;
+  platform?: NodeJS.Platform;
+}
+
+function getUnixSocketMaxPathBytes(platform: NodeJS.Platform): number {
+  return platform === "darwin"
+    ? DARWIN_UNIX_SOCKET_MAX_PATH_BYTES
+    : DEFAULT_UNIX_SOCKET_MAX_PATH_BYTES;
+}
+
+function isPathWithinSocketLimit(path: string, maxPathBytes: number): boolean {
+  return Buffer.byteLength(path, "utf8") <= maxPathBytes;
+}
+
+/**
+ * Derive the env var name and socket filename from a socket name.
+ *
+ * Examples (hyphens in the name become underscores in the env var):
+ */
+function deriveSocketNames(socketName: string): {
+  envVar: string;
+  fileName: string;
+} {
+  if (!/^[a-z][a-z0-9-]{0,63}$/.test(socketName)) {
+    throw new Error(`Invalid IPC endpoint name: ${socketName}`);
+  }
+  const envVar = `${socketName.toUpperCase().replace(/-/g, "_")}_IPC_SOCKET_DIR`;
+  const fileName = `${socketName}.sock`;
+  return { envVar, fileName };
+}
+
+function resolveWindowsNamedPipe(
+  socketName: string,
+  workspaceDir: string,
+): IpcSocketPathResolution {
+  const workspaceIdentity = win32
+    .normalize(workspaceDir)
+    .replace(/\\+$/, "")
+    .toLowerCase();
+  const hash = createHash("sha256")
+    .update(`${workspaceIdentity}\0${socketName}`)
+    .digest("hex")
+    .slice(0, 24);
+  return {
+    path: `\\\\.\\pipe\\vellum-${socketName}-${hash}`,
+    source: "windows-named-pipe",
+  };
+}
+
+export function isNamedPipePath(endpointPath: string): boolean {
+  return /^\\\\[.?]\\pipe\\/.test(endpointPath);
+}
+
+export function removeIpcEndpointFile(endpointPath: string): void {
+  if (isNamedPipePath(endpointPath)) {
+    return;
+  }
+  try {
+    unlinkSync(endpointPath);
+  } catch {
+    // Already absent.
+  }
+}
+
+/**
+ * Resolve the path to an IPC socket file.
+ *
+ * Resolution order:
+ * POSIX uses overrides, workspace paths, then bounded temporary paths.
+ * Windows uses deterministic named pipes.
+ */
+export function resolveIpcEndpoint(
+  socketName: string,
+  options: IpcEndpointOptions,
+): IpcSocketPathResolution {
+  const { envVar, fileName } = deriveSocketNames(socketName);
+  const platform = options.platform ?? process.platform;
+  if (platform === "win32") {
+    return resolveWindowsNamedPipe(socketName, options.workspaceDir);
+  }
+
+  // Explicit override via env var.
+  const envSocketDir = (options.env ?? process.env)[envVar]?.trim();
+  if (envSocketDir) {
+    return {
+      path: join(envSocketDir, fileName),
+      source: "env-override",
+    };
+  }
+
+  const maxPathBytes = getUnixSocketMaxPathBytes(platform);
+  const workspacePath = join(options.workspaceDir, fileName);
+
+  if (isPathWithinSocketLimit(workspacePath, maxPathBytes)) {
+    return {
+      path: workspacePath,
+      source: "workspace",
+    };
+  }
+
+  // Workspace path exceeds AF_UNIX limit - fall back to tmpdir.
+  const hash = createHash("sha256")
+    .update(workspacePath)
+    .digest("hex")
+    .slice(0, 12);
+  const hashedPath = join(tmpdir(), IPC_TMP_DIR_NAME, `${hash}-${fileName}`);
+  if (isPathWithinSocketLimit(hashedPath, maxPathBytes)) {
+    return {
+      path: hashedPath,
+      source: "tmp-hash",
+    };
+  }
+
+  return {
+    path: join(tmpdir(), `v-${hash}.sock`),
+    source: "tmp-short-hash",
+  };
+}

package/node_modules/@vellumai/ipc-server-utils/src/index.ts

@@ -0,0 +1,18 @@
+export {
+  SocketWatchdog,
+  ensureSocketDir,
+  type SocketWatchdogOptions,
+  type SocketWatchdogLogger,
+} from "./socket-watchdog.js";
+export { isNamedPipePath, removeIpcEndpointFile, resolveIpcEndpoint } from "./endpoint.js";
+export { ipcListenOptions } from "./listen-options.js";
+export {
+  IpcFrameReader,
+  writeLegacyMessage,
+  writeMessage,
+  writeStreamChunk,
+  writeStreamEnd,
+  type IpcEnvelope,
+  type OnMessageCallback,
+  type StreamCallbacks,
+} from "./ipc-framing.js";