@vellumai/cli 0.11.2 → 0.11.3-staging.2

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

@@ -0,0 +1,232 @@
+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 { guardianTokenPath } from "../config";
+import { unpairAssistant } from "../unpair";
+
+let tmpDir: string;
+let lockfilePath: string;
+let configDir: string;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "vellum-unpair-"));
+  lockfilePath = path.join(tmpDir, "lockfile.json");
+  configDir = path.join(tmpDir, "config");
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
+const writeLockfile = (data: Record<string, unknown>): void => {
+  fs.writeFileSync(lockfilePath, JSON.stringify(data));
+};
+
+const readLockfileFromDisk = (): Record<string, unknown> =>
+  JSON.parse(fs.readFileSync(lockfilePath, "utf-8")) as Record<string, unknown>;
+
+const seedGuardianToken = (assistantId: string): string => {
+  const tokenPath = guardianTokenPath(configDir, assistantId);
+  fs.mkdirSync(path.dirname(tokenPath), { recursive: true });
+  fs.writeFileSync(tokenPath, JSON.stringify({ accessToken: "tok" }));
+  return tokenPath;
+};
+
+describe("unpairAssistant", () => {
+  test("removes the paired entry, deletes its guardian token, and reassigns the active pointer", () => {
+    writeLockfile({
+      assistants: [
+        { assistantId: "paired-1", cloud: "paired", runtimeUrl: "https://h" },
+        { assistantId: "local-1", cloud: "local", futureField: "keep-me" },
+      ],
+      activeAssistant: "paired-1",
+    });
+    const tokenPath = seedGuardianToken("paired-1");
+
+    const result = unpairAssistant([lockfilePath], configDir, "paired-1");
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    // Active falls back to the first remaining entry, matching the CLI's
+    // removeAssistantEntry semantics.
+    expect(result.lockfile.activeAssistant).toBe("local-1");
+    expect(result.lockfile.assistants.map((a) => a.assistantId)).toEqual([
+      "local-1",
+    ]);
+    expect(fs.existsSync(tokenPath)).toBe(false);
+
+    // Unknown fields on the remaining entries survive the rewrite.
+    const onDisk = readLockfileFromDisk();
+    expect(onDisk.assistants).toEqual([
+      { assistantId: "local-1", cloud: "local", futureField: "keep-me" },
+    ]);
+    expect(onDisk.activeAssistant).toBe("local-1");
+  });
+
+  test("removing the sole (active) entry leaves no active pointer", () => {
+    writeLockfile({
+      assistants: [{ assistantId: "paired-1", cloud: "paired" }],
+      activeAssistant: "paired-1",
+    });
+
+    const result = unpairAssistant([lockfilePath], configDir, "paired-1");
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.lockfile.activeAssistant).toBeNull();
+    expect(result.lockfile.assistants).toEqual([]);
+  });
+
+  test("reassigns the active pointer past tolerated malformed entries", () => {
+    writeLockfile({
+      assistants: [
+        { assistantId: "paired-1", cloud: "paired" },
+        { notAnAssistant: true },
+        { assistantId: "local-1", cloud: "local" },
+      ],
+      activeAssistant: "paired-1",
+    });
+
+    const result = unpairAssistant([lockfilePath], configDir, "paired-1");
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.lockfile.activeAssistant).toBe("local-1");
+  });
+
+  test("a failed token delete aborts before touching the lockfile", () => {
+    writeLockfile({
+      assistants: [{ assistantId: "paired-1", cloud: "paired" }],
+      activeAssistant: "paired-1",
+    });
+    // A non-empty directory at the token path makes rmSync (non-recursive)
+    // throw, standing in for EPERM-style failures.
+    const tokenPath = guardianTokenPath(configDir, "paired-1");
+    fs.mkdirSync(path.join(tokenPath, "oops"), { recursive: true });
+
+    const result = unpairAssistant([lockfilePath], configDir, "paired-1");
+
+    expect(result.ok).toBe(false);
+    if (result.ok) {
+      return;
+    }
+    expect(result.status).toBe(500);
+    expect(result.error).toContain("guardian token");
+    // The entry is untouched, so the unpair can be retried.
+    expect(readLockfileFromDisk().assistants).toEqual([
+      { assistantId: "paired-1", cloud: "paired" },
+    ]);
+    expect(readLockfileFromDisk().activeAssistant).toBe("paired-1");
+  });
+
+  test("restores the guardian token when the lockfile write fails", () => {
+    writeLockfile({
+      assistants: [{ assistantId: "paired-1", cloud: "paired" }],
+      activeAssistant: null,
+    });
+    const tokenPath = seedGuardianToken("paired-1");
+    // A read-only lockfile directory makes the tmp-file write fail after the
+    // token has already been deleted.
+    fs.chmodSync(tmpDir, 0o500);
+    try {
+      const result = unpairAssistant([lockfilePath], configDir, "paired-1");
+
+      expect(result.ok).toBe(false);
+      expect(fs.existsSync(tokenPath)).toBe(true);
+      expect(fs.readFileSync(tokenPath, "utf-8")).toBe(
+        JSON.stringify({ accessToken: "tok" }),
+      );
+    } finally {
+      fs.chmodSync(tmpDir, 0o700);
+    }
+  });
+
+  test("leaves the active pointer alone when it names another assistant", () => {
+    writeLockfile({
+      assistants: [
+        { assistantId: "paired-1", cloud: "paired" },
+        { assistantId: "local-1", cloud: "local" },
+      ],
+      activeAssistant: "local-1",
+    });
+
+    const result = unpairAssistant([lockfilePath], configDir, "paired-1");
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.lockfile.activeAssistant).toBe("local-1");
+  });
+
+  test("succeeds when the guardian token file is already gone", () => {
+    writeLockfile({
+      assistants: [{ assistantId: "paired-1", cloud: "paired" }],
+      activeAssistant: null,
+    });
+
+    const result = unpairAssistant([lockfilePath], configDir, "paired-1");
+
+    expect(result.ok).toBe(true);
+  });
+
+  test("refuses an unknown assistant without touching disk", () => {
+    writeLockfile({
+      assistants: [{ assistantId: "paired-1", cloud: "paired" }],
+      activeAssistant: "paired-1",
+    });
+
+    const result = unpairAssistant([lockfilePath], configDir, "nope");
+
+    expect(result).toEqual({
+      ok: false,
+      status: 404,
+      error: "No such assistant",
+    });
+    expect(readLockfileFromDisk().activeAssistant).toBe("paired-1");
+  });
+
+  test("refuses a non-paired assistant and leaves its entry and token alone", () => {
+    writeLockfile({
+      assistants: [{ assistantId: "local-1", cloud: "local" }],
+      activeAssistant: "local-1",
+    });
+    const tokenPath = seedGuardianToken("local-1");
+
+    const result = unpairAssistant([lockfilePath], configDir, "local-1");
+
+    expect(result.ok).toBe(false);
+    if (result.ok) {
+      return;
+    }
+    expect(result.status).toBe(400);
+    expect(result.error).toContain("paired");
+    expect(fs.existsSync(tokenPath)).toBe(true);
+    expect(readLockfileFromDisk().assistants).toEqual([
+      { assistantId: "local-1", cloud: "local" },
+    ]);
+  });
+
+  test("refuses a cloudless entry (defaults to local) rather than treating it as paired", () => {
+    writeLockfile({
+      assistants: [{ assistantId: "bare-1" }],
+      activeAssistant: null,
+    });
+
+    const result = unpairAssistant([lockfilePath], configDir, "bare-1");
+
+    expect(result.ok).toBe(false);
+    if (result.ok) {
+      return;
+    }
+    expect(result.status).toBe(400);
+  });
+});

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

@@ -1,9 +1,15 @@
 import os from "node:os";
-import path from "node:path";
 
 import { SEEDS } from "@vellumai/environments";
 
 import { resolveEnvironmentName } from "./environment";
+import {
+  assertSafePathSegment,
+  joinLocalPath,
+  resolveConfigHomes,
+  resolveDataHome,
+  type LocalPathOptions,
+} from "./paths";
 
 const PRODUCTION_ENVIRONMENT_NAME = "production";
 
@@ -21,13 +27,14 @@ export interface LocalEndpointConfig {
  */
 export function resolveLocalConfigFromEnv(
   env: Record<string, string | undefined>,
+  options: LocalPathOptions = {},
 ): LocalEndpointConfig {
-  const vellumEnv = resolveEnvironmentName(env);
+  const vellumEnv = resolveEnvironmentName(env, options);
   const seed = SEEDS[vellumEnv] ?? SEEDS[PRODUCTION_ENVIRONMENT_NAME]!;
 
   return {
-    lockfilePaths: resolveLockfilePaths(env),
-    configDir: resolveConfigDir(env),
+    lockfilePaths: resolveLockfilePaths(env, options),
+    configDir: resolveConfigDir(env, options),
     webUrl: env.VELLUM_WEB_URL || seed.webUrl,
     platformUrl: env.VELLUM_PLATFORM_URL || seed.platformUrl,
   };
@@ -35,34 +42,125 @@ export function resolveLocalConfigFromEnv(
 
 export function resolveLockfilePaths(
   env: Record<string, string | undefined>,
+  options: LocalPathOptions = {},
 ): string[] {
-  const vellumEnv = resolveEnvironmentName(env);
-  const lockfileDir = env.VELLUM_LOCKFILE_DIR;
+  const vellumEnv = resolveEnvironmentName(env, options);
+  const lockfileDir = Object.hasOwn(options, "lockfileDirOverride")
+    ? options.lockfileDirOverride
+    : env.VELLUM_LOCKFILE_DIR?.trim();
+
+  if ((options.platform ?? process.platform) === "win32") {
+    const canonicalDir = lockfileDir ?? resolveConfigDir(env, options);
+    const canonical = joinLocalPath(options, canonicalDir, "lockfile.json");
+    const legacyDir = lockfileDir ?? options.homeDir ?? os.homedir();
+    const legacy =
+      vellumEnv === PRODUCTION_ENVIRONMENT_NAME
+        ? [".vellum.lock.json", ".vellum.lockfile.json"].map((name) =>
+            joinLocalPath(options, legacyDir, name),
+          )
+        : [
+            joinLocalPath(
+              options,
+              lockfileDir ?? resolveConfigDirPaths(env, options).at(-1)!,
+              "lockfile.json",
+            ),
+          ];
+    return [
+      canonical,
+      ...legacy.filter((candidate) => candidate !== canonical),
+    ];
+  }
 
   if (vellumEnv === PRODUCTION_ENVIRONMENT_NAME) {
-    const dir = lockfileDir ?? os.homedir();
+    const dir = lockfileDir ?? options.homeDir ?? os.homedir();
     return [
-      path.join(dir, ".vellum.lock.json"),
-      path.join(dir, ".vellum.lockfile.json"),
+      joinLocalPath(options, dir, ".vellum.lock.json"),
+      joinLocalPath(options, 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")];
+  const dir = lockfileDir ?? resolveConfigDir(env, options);
+  return [joinLocalPath(options, dir, "lockfile.json")];
 }
 
 export function resolveConfigDir(
   env: Record<string, string | undefined>,
+  options: LocalPathOptions = {},
 ): 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 resolveConfigDirPaths(env, options)[0]!;
+}
+
+export function resolveConfigDirPaths(
+  env: Record<string, string | undefined>,
+  options: LocalPathOptions = {},
+): string[] {
+  if (options.configDirOverride) {
+    return [options.configDirOverride];
   }
-  return path.join(xdgConfigHome, `vellum-${vellumEnv}`);
+  const vellumEnv = resolveEnvironmentName(env, options);
+  return resolveConfigHomes(env, options).map((home) =>
+    joinLocalPath(options, home, environmentDirectoryName(vellumEnv, options)),
+  );
+}
+
+function environmentDirectoryName(
+  vellumEnv: string,
+  options: LocalPathOptions,
+): string {
+  assertSafePathSegment(vellumEnv, "environment name", options);
+  return vellumEnv === PRODUCTION_ENVIRONMENT_NAME
+    ? "vellum"
+    : `vellum-${vellumEnv}`;
+}
+
+function resolveDataDir(
+  env: Record<string, string | undefined>,
+  options: LocalPathOptions,
+): string {
+  const vellumEnv = resolveEnvironmentName(env, options);
+  return joinLocalPath(
+    options,
+    resolveDataHome(env, options),
+    environmentDirectoryName(vellumEnv, options),
+  );
+}
+
+export function resolveRuntimeDir(
+  env: Record<string, string | undefined>,
+  options: LocalPathOptions = {},
+): string {
+  return resolveDataDir(env, options);
+}
+
+export function resolveLogDir(
+  env: Record<string, string | undefined>,
+  options: LocalPathOptions = {},
+): string {
+  const root =
+    (options.platform ?? process.platform) === "win32"
+      ? resolveDataDir(env, options)
+      : resolveConfigDir(env, options);
+  return joinLocalPath(options, root, "logs");
+}
+
+export function resolveAssistantsDir(
+  env: Record<string, string | undefined>,
+  options: LocalPathOptions = {},
+): string {
+  return joinLocalPath(options, resolveDataDir(env, options), "assistants");
+}
+
+export function resolveInstanceDir(
+  env: Record<string, string | undefined>,
+  assistantId: string,
+  options: LocalPathOptions = {},
+): string {
+  assertSafePathSegment(assistantId, "assistant ID", options);
+  return joinLocalPath(
+    options,
+    resolveAssistantsDir(env, options),
+    assistantId,
+  );
 }
 
 /**
@@ -74,6 +172,14 @@ export function resolveConfigDir(
 export function guardianTokenPath(
   configDir: string,
   assistantId: string,
+  options: LocalPathOptions = {},
 ): string {
-  return path.join(configDir, "assistants", assistantId, "guardian-token.json");
+  assertSafePathSegment(assistantId, "assistant ID", options);
+  return joinLocalPath(
+    options,
+    configDir,
+    "assistants",
+    assistantId,
+    "guardian-token.json",
+  );
 }

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

@@ -1,21 +1,33 @@
 import { existsSync, readFileSync } from "node:fs";
-import os from "node:os";
-import path from "node:path";
+
+import {
+  joinLocalPath,
+  resolveConfigHomes,
+  type LocalPathOptions,
+} from "./paths";
 
 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`.
+ * be read before the environment is known. Uses AppData on Windows and the
+ * XDG config home on macOS and Linux.
  */
+export function defaultEnvironmentFilePaths(
+  env: Record<string, string | undefined>,
+  options: LocalPathOptions = {},
+): string[] {
+  return resolveConfigHomes(env, options).map((home) =>
+    joinLocalPath(options, home, "vellum", "environment"),
+  );
+}
+
 export function defaultEnvironmentFilePath(
   env: Record<string, string | undefined>,
+  options: LocalPathOptions = {},
 ): string {
-  const xdgConfigHome =
-    env.XDG_CONFIG_HOME?.trim() || path.join(os.homedir(), ".config");
-  return path.join(xdgConfigHome, "vellum", "environment");
+  return defaultEnvironmentFilePaths(env, options)[0]!;
 }
 
 /**
@@ -24,15 +36,22 @@ export function defaultEnvironmentFilePath(
  */
 export function readDefaultEnvironment(
   env: Record<string, string | undefined>,
+  options: LocalPathOptions = {},
 ): 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;
+  for (const filePath of defaultEnvironmentFilePaths(env, options)) {
+    try {
+      if (!existsSync(filePath)) {
+        continue;
+      }
+      const content = readFileSync(filePath, "utf-8").trim();
+      if (content.length > 0) {
+        return content;
+      }
+    } catch {
+      // Try the next compatible location.
+    }
   }
+  return undefined;
 }
 
 /**
@@ -53,10 +72,12 @@ export function readDefaultEnvironment(
  */
 export function resolveEnvironmentName(
   env: Record<string, string | undefined>,
+  options: LocalPathOptions = {},
 ): string {
   return (
+    options.environmentName ||
     env.VELLUM_ENVIRONMENT?.trim() ||
-    readDefaultEnvironment(env) ||
+    readDefaultEnvironment(env, options) ||
     PRODUCTION_ENVIRONMENT_NAME
   );
 }