@vellumai/assistant 0.8.1 → 0.8.3

package/src/cli/lib/__tests__/list-installed-plugins.test.ts

@@ -0,0 +1,154 @@
+/**
+ * Tests for {@link listInstalledPlugins}.
+ *
+ * Each test materializes a temp workspace plugins directory and points
+ * `listInstalledPlugins` at it via the `workspacePluginsDir` option — no
+ * env mutation, no filesystem reach beyond `tmpdir()`.
+ */
+
+import {
+  mkdirSync,
+  mkdtempSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import { listInstalledPlugins } from "../list-installed-plugins.js";
+
+let pluginsDir: string;
+
+beforeEach(() => {
+  pluginsDir = mkdtempSync(join(tmpdir(), "plugins-list-"));
+});
+
+afterEach(() => {
+  rmSync(pluginsDir, { recursive: true, force: true });
+});
+
+describe("listInstalledPlugins", () => {
+  test("returns [] for a non-existent plugins directory", () => {
+    const missing = join(pluginsDir, "does-not-exist");
+    expect(listInstalledPlugins({ workspacePluginsDir: missing })).toEqual([]);
+  });
+
+  test("returns [] for an empty plugins directory", () => {
+    expect(listInstalledPlugins({ workspacePluginsDir: pluginsDir })).toEqual(
+      [],
+    );
+  });
+
+  test("lists plugins alphabetically with parsed package.json metadata", () => {
+    mkdirSync(join(pluginsDir, "zeta"));
+    writeFileSync(
+      join(pluginsDir, "zeta", "package.json"),
+      JSON.stringify({
+        name: "zeta",
+        version: "1.2.3",
+        description: "z plugin",
+        peerDependencies: { "@vellumai/plugin-api": "0.8.0" },
+      }),
+    );
+    mkdirSync(join(pluginsDir, "alpha"));
+    writeFileSync(
+      join(pluginsDir, "alpha", "package.json"),
+      JSON.stringify({ name: "alpha", version: "0.1.0" }),
+    );
+
+    const result = listInstalledPlugins({ workspacePluginsDir: pluginsDir });
+    expect(result.map((p) => p.name)).toEqual(["alpha", "zeta"]);
+    expect(result[0]!.packageJson).toEqual({
+      name: "alpha",
+      version: "0.1.0",
+      description: undefined,
+      peerDependencies: undefined,
+    });
+    expect(result[1]!.packageJson).toEqual({
+      name: "zeta",
+      version: "1.2.3",
+      description: "z plugin",
+      peerDependencies: { "@vellumai/plugin-api": "0.8.0" },
+    });
+    expect(result.every((p) => p.issues.length === 0)).toBe(true);
+  });
+
+  test("reports missing package.json as an issue rather than failing", () => {
+    mkdirSync(join(pluginsDir, "barebones"));
+
+    const result = listInstalledPlugins({ workspacePluginsDir: pluginsDir });
+    expect(result).toHaveLength(1);
+    expect(result[0]!.packageJson).toBeNull();
+    expect(result[0]!.issues).toEqual(["missing package.json"]);
+  });
+
+  test("reports malformed JSON as an issue rather than failing", () => {
+    mkdirSync(join(pluginsDir, "broken"));
+    writeFileSync(join(pluginsDir, "broken", "package.json"), "{not json");
+
+    const result = listInstalledPlugins({ workspacePluginsDir: pluginsDir });
+    expect(result).toHaveLength(1);
+    expect(result[0]!.packageJson).toBeNull();
+    expect(result[0]!.issues[0]).toMatch(/invalid JSON/);
+  });
+
+  test("reports non-object package.json as an issue", () => {
+    mkdirSync(join(pluginsDir, "array-shaped"));
+    writeFileSync(
+      join(pluginsDir, "array-shaped", "package.json"),
+      JSON.stringify([1, 2, 3]),
+    );
+
+    const result = listInstalledPlugins({ workspacePluginsDir: pluginsDir });
+    expect(result).toHaveLength(1);
+    expect(result[0]!.packageJson).toBeNull();
+    expect(result[0]!.issues).toContain("package.json is not an object");
+  });
+
+  test("skips hidden entries and non-directories", () => {
+    mkdirSync(join(pluginsDir, ".hidden-dir"));
+    writeFileSync(join(pluginsDir, "stray-file.txt"), "noise");
+    mkdirSync(join(pluginsDir, "visible"));
+    writeFileSync(
+      join(pluginsDir, "visible", "package.json"),
+      JSON.stringify({ name: "visible", version: "0.0.1" }),
+    );
+
+    const result = listInstalledPlugins({ workspacePluginsDir: pluginsDir });
+    expect(result.map((p) => p.name)).toEqual(["visible"]);
+  });
+
+  test("follows symlinks that resolve to directories", () => {
+    const real = mkdtempSync(join(tmpdir(), "real-plugin-"));
+    try {
+      writeFileSync(
+        join(real, "package.json"),
+        JSON.stringify({ name: "linked", version: "0.0.1" }),
+      );
+      symlinkSync(real, join(pluginsDir, "linked"));
+
+      const result = listInstalledPlugins({ workspacePluginsDir: pluginsDir });
+      expect(result.map((p) => p.name)).toEqual(["linked"]);
+      expect(result[0]!.packageJson?.name).toBe("linked");
+    } finally {
+      rmSync(real, { recursive: true, force: true });
+    }
+  });
+
+  test("ignores broken symlinks rather than throwing", () => {
+    symlinkSync(
+      join(pluginsDir, "does-not-exist"),
+      join(pluginsDir, "dangling"),
+    );
+    mkdirSync(join(pluginsDir, "valid"));
+    writeFileSync(
+      join(pluginsDir, "valid", "package.json"),
+      JSON.stringify({ name: "valid", version: "0.0.1" }),
+    );
+
+    const result = listInstalledPlugins({ workspacePluginsDir: pluginsDir });
+    expect(result.map((p) => p.name)).toEqual(["valid"]);
+  });
+});

package/src/cli/lib/__tests__/search-plugins.test.ts

@@ -0,0 +1,261 @@
+/**
+ * Tests for {@link searchPlugins}.
+ *
+ * Network is replaced with an in-memory fixture passed via the `fetch`
+ * dependency — no globals are monkey-patched and no `--test-hook` exports
+ * leak into production code.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import {
+  type FetchLike,
+  InvalidSearchPatternError,
+  searchPlugins,
+} from "../search-plugins.js";
+
+/**
+ * Build a GitHub Contents API fixture from an in-memory directory listing.
+ *
+ * `entries` maps each name under `experimental/plugins/` to its `type`. The
+ * fixture answers GET requests against
+ *  - `https://api.github.com/repos/vellum-ai/vellum-assistant/contents/experimental/plugins...`
+ * and returns 500 for anything else (forces test bugs to surface loudly).
+ */
+function fixtureFetch(
+  entries: Record<string, "dir" | "file" | "symlink" | "submodule">,
+): FetchLike {
+  const PREFIX_API =
+    "https://api.github.com/repos/vellum-ai/vellum-assistant/contents/experimental/plugins";
+
+  return (async (input: RequestInfo | URL) => {
+    const url = typeof input === "string" ? input : input.toString();
+    if (!url.startsWith(PREFIX_API)) {
+      return new Response("unexpected url: " + url, { status: 500 });
+    }
+    const body = Object.entries(entries).map(([name, type]) => ({
+      name,
+      path: `experimental/plugins/${name}`,
+      type,
+      size: type === "file" ? 1 : 0,
+      download_url:
+        type === "file"
+          ? `https://raw.githubusercontent.com/vellum-ai/vellum-assistant/main/experimental/plugins/${name}`
+          : null,
+    }));
+    return new Response(JSON.stringify(body), {
+      status: 200,
+      headers: { "content-type": "application/json" },
+    });
+  }) as FetchLike;
+}
+
+describe("searchPlugins", () => {
+  test("matches the query as a case-insensitive regex against directory names", async () => {
+    const result = await searchPlugins(
+      { query: "memory" },
+      {
+        fetch: fixtureFetch({
+          "simple-memory": "dir",
+          "memory-graph": "dir",
+          "git-tools": "dir",
+        }),
+      },
+    );
+
+    expect(result.matches.map((m) => m.name)).toEqual([
+      "memory-graph",
+      "simple-memory",
+    ]);
+    expect(result.matches[0]!.path).toBe("experimental/plugins/memory-graph");
+    expect(result.query).toBe("memory");
+    expect(result.ref).toBe("main");
+  });
+
+  test("matches regardless of query casing (case-insensitive)", async () => {
+    const result = await searchPlugins(
+      { query: "MEMORY" },
+      { fetch: fixtureFetch({ "simple-memory": "dir" }) },
+    );
+    expect(result.matches.map((m) => m.name)).toEqual(["simple-memory"]);
+  });
+
+  test("anchored patterns work without escaping", async () => {
+    const result = await searchPlugins(
+      { query: "^memory-" },
+      {
+        fetch: fixtureFetch({
+          "memory-graph": "dir",
+          "simple-memory": "dir",
+        }),
+      },
+    );
+    expect(result.matches.map((m) => m.name)).toEqual(["memory-graph"]);
+  });
+
+  test("empty query matches all directories", async () => {
+    const result = await searchPlugins(
+      { query: "" },
+      {
+        fetch: fixtureFetch({
+          "simple-memory": "dir",
+          "memory-graph": "dir",
+          "git-tools": "dir",
+        }),
+      },
+    );
+    expect(result.matches.map((m) => m.name)).toEqual([
+      "git-tools",
+      "memory-graph",
+      "simple-memory",
+    ]);
+  });
+
+  test("skips entries that are not directories", async () => {
+    const result = await searchPlugins(
+      { query: "" },
+      {
+        fetch: fixtureFetch({
+          "simple-memory": "dir",
+          "README.md": "file",
+          "broken-symlink": "symlink",
+          "old-plugin": "submodule",
+        }),
+      },
+    );
+    expect(result.matches.map((m) => m.name)).toEqual(["simple-memory"]);
+  });
+
+  test("rejects invalid regex patterns up front (no network call)", async () => {
+    let fetchCalled = false;
+    const fetch: FetchLike = (async () => {
+      fetchCalled = true;
+      return new Response("", { status: 200 });
+    }) as FetchLike;
+
+    await expect(
+      searchPlugins({ query: "(unterminated" }, { fetch }),
+    ).rejects.toBeInstanceOf(InvalidSearchPatternError);
+    expect(fetchCalled).toBe(false);
+  });
+
+  test("empty result set on no matches", async () => {
+    const result = await searchPlugins(
+      { query: "nothing-matches" },
+      { fetch: fixtureFetch({ "simple-memory": "dir" }) },
+    );
+    expect(result.matches).toEqual([]);
+  });
+
+  test("respects `ref` option by forwarding to GitHub", async () => {
+    // The CLI does not surface a `--ref` flag (the source-path convention
+    // may change), but the underlying function keeps `ref` for test
+    // injection and future internal callers.
+    let seenRef: string | undefined;
+    const result = await searchPlugins(
+      { query: "memory", ref: "feat-branch" },
+      {
+        fetch: (async (input: RequestInfo | URL) => {
+          const url = typeof input === "string" ? input : input.toString();
+          const m = /[?&]ref=([^&]+)/.exec(url);
+          seenRef = m ? decodeURIComponent(m[1]!) : undefined;
+          return new Response(
+            JSON.stringify([
+              {
+                name: "simple-memory",
+                path: "experimental/plugins/simple-memory",
+                type: "dir",
+                size: 0,
+                download_url: null,
+              },
+            ]),
+            { status: 200, headers: { "content-type": "application/json" } },
+          );
+        }) as FetchLike,
+      },
+    );
+
+    expect(seenRef).toBe("feat-branch");
+    expect(result.ref).toBe("feat-branch");
+    expect(result.matches.map((m) => m.name)).toEqual(["simple-memory"]);
+  });
+
+  test("HTTP 5xx from GitHub propagates with the status code", async () => {
+    await expect(
+      searchPlugins(
+        { query: "memory" },
+        {
+          fetch: (async () =>
+            new Response("upstream broken", { status: 503 })) as FetchLike,
+        },
+      ),
+    ).rejects.toThrow(/HTTP 503/);
+  });
+
+  test("HTTP 403 (rate-limited / forbidden) surfaces as an error", async () => {
+    await expect(
+      searchPlugins(
+        { query: "memory" },
+        {
+          fetch: (async () =>
+            new Response("rate limit exceeded", { status: 403 })) as FetchLike,
+        },
+      ),
+    ).rejects.toThrow(/HTTP 403/);
+  });
+
+  test("404 on the plugins prefix surfaces as an error (not silently empty)", async () => {
+    // Distinct from `installPlugin`, where 404 on a specific plugin name is
+    // normal "not found". For the search, 404 on the prefix means the
+    // canonical source path itself is gone — that's an upstream problem
+    // worth surfacing, not a clean empty result.
+    await expect(
+      searchPlugins(
+        { query: "memory" },
+        {
+          fetch: (async () =>
+            new Response("not found", { status: 404 })) as FetchLike,
+        },
+      ),
+    ).rejects.toThrow(/HTTP 404/);
+  });
+
+  test("returns matches sorted by name", async () => {
+    const result = await searchPlugins(
+      { query: "" },
+      {
+        fetch: fixtureFetch({
+          "zeta-plugin": "dir",
+          "alpha-plugin": "dir",
+          "mu-plugin": "dir",
+        }),
+      },
+    );
+    expect(result.matches.map((m) => m.name)).toEqual([
+      "alpha-plugin",
+      "mu-plugin",
+      "zeta-plugin",
+    ]);
+  });
+
+  test("sends no Authorization header (canonical source is a public repo)", async () => {
+    let seenAuth: string | undefined;
+    let seenUserAgent: string | undefined;
+    await searchPlugins(
+      { query: "memory" },
+      {
+        fetch: (async (_input: RequestInfo | URL, init?: RequestInit) => {
+          const headers = init?.headers as Record<string, string> | undefined;
+          seenAuth = headers?.Authorization;
+          seenUserAgent = headers?.["User-Agent"];
+          return new Response("[]", {
+            status: 200,
+            headers: { "content-type": "application/json" },
+          });
+        }) as FetchLike,
+      },
+    );
+    expect(seenAuth).toBeUndefined();
+    expect(seenUserAgent).toBe("vellum-assistant-cli");
+  });
+});

package/src/cli/lib/__tests__/uninstall-plugin.test.ts

@@ -0,0 +1,124 @@
+/**
+ * Tests for {@link uninstallPlugin}.
+ *
+ * Each test materializes a temp workspace plugins directory and points
+ * `uninstallPlugin` at it via the `workspacePluginsDir` option.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import { InvalidPluginNameError } from "../install-from-github.js";
+import {
+  PluginNotInstalledError,
+  uninstallPlugin,
+} from "../uninstall-plugin.js";
+
+let pluginsDir: string;
+
+beforeEach(() => {
+  pluginsDir = mkdtempSync(join(tmpdir(), "plugins-uninstall-"));
+});
+
+afterEach(() => {
+  rmSync(pluginsDir, { recursive: true, force: true });
+});
+
+function writePlugin(name: string): string {
+  const target = join(pluginsDir, name);
+  mkdirSync(join(target, "hooks"), { recursive: true });
+  writeFileSync(
+    join(target, "package.json"),
+    JSON.stringify({ name, version: "0.0.1" }),
+  );
+  writeFileSync(
+    join(target, "hooks", "init.ts"),
+    "export async function init() {}\n",
+  );
+  return target;
+}
+
+describe("uninstallPlugin", () => {
+  test("removes the install target recursively", () => {
+    const target = writePlugin("simple-memory");
+    expect(existsSync(target)).toBe(true);
+
+    const result = uninstallPlugin({
+      name: "simple-memory",
+      workspacePluginsDir: pluginsDir,
+    });
+
+    expect(result).toEqual({ name: "simple-memory", target });
+    expect(existsSync(target)).toBe(false);
+    expect(readdirSync(pluginsDir)).toEqual([]);
+  });
+
+  test("throws PluginNotInstalledError when no directory exists", () => {
+    expect(() =>
+      uninstallPlugin({
+        name: "ghost",
+        workspacePluginsDir: pluginsDir,
+      }),
+    ).toThrow(PluginNotInstalledError);
+  });
+
+  test("throws PluginNotInstalledError when the target is a regular file", () => {
+    writeFileSync(join(pluginsDir, "trap"), "not a plugin");
+
+    expect(() =>
+      uninstallPlugin({
+        name: "trap",
+        workspacePluginsDir: pluginsDir,
+      }),
+    ).toThrow(PluginNotInstalledError);
+  });
+
+  test("removes a symlinked plugin without touching the link target", () => {
+    const real = mkdtempSync(join(tmpdir(), "real-plugin-"));
+    try {
+      writeFileSync(
+        join(real, "package.json"),
+        JSON.stringify({ name: "linked", version: "0.0.1" }),
+      );
+      symlinkSync(real, join(pluginsDir, "linked"));
+
+      uninstallPlugin({
+        name: "linked",
+        workspacePluginsDir: pluginsDir,
+      });
+
+      expect(existsSync(join(pluginsDir, "linked"))).toBe(false);
+      // Real directory and its files remain — rm only removed the symlink.
+      expect(existsSync(real)).toBe(true);
+      expect(existsSync(join(real, "package.json"))).toBe(true);
+    } finally {
+      rmSync(real, { recursive: true, force: true });
+    }
+  });
+
+  test.each([
+    ["../escape"],
+    ["/abs/path"],
+    [".hidden"],
+    ["Name-WithCaps"],
+    ["space name"],
+    [""],
+  ])("rejects invalid plugin name %p before touching the filesystem", (bad) => {
+    // Salt the plugins dir with siblings to prove we don't blow them away.
+    writePlugin("real-plugin");
+    expect(() =>
+      uninstallPlugin({ name: bad, workspacePluginsDir: pluginsDir }),
+    ).toThrow(InvalidPluginNameError);
+    expect(existsSync(join(pluginsDir, "real-plugin"))).toBe(true);
+  });
+});

package/src/cli/lib/__tests__/unknown-command.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it } from "bun:test";
+
+import { Command } from "commander";
+
+import {
+  detectUnknownCommand,
+  findClosestCommand,
+  formatUnknownCommandMessage,
+  knownCommandNames,
+} from "../unknown-command.js";
+
+function buildToyProgram(): Command {
+  const program = new Command();
+  program.name("assistant").description("toy");
+  program.command("status").description("show status");
+  program.command("config").description("manage config");
+  program.command("pending").alias("ls").description("inspect pending");
+  return program;
+}
+
+describe("knownCommandNames", () => {
+  it("collects command names and aliases", () => {
+    const names = knownCommandNames(buildToyProgram());
+    expect([...names].sort()).toEqual(["config", "ls", "pending", "status"]);
+  });
+});
+
+describe("findClosestCommand", () => {
+  it("returns the closest match within 40% distance", () => {
+    expect(findClosestCommand("confg", ["config", "status"])).toBe("config");
+  });
+
+  it("returns undefined when nothing is close enough", () => {
+    expect(findClosestCommand("xyzzy", ["config", "status"])).toBeUndefined();
+  });
+
+  it("is case-insensitive for comparison", () => {
+    expect(findClosestCommand("STATUS", ["status"])).toBe("status");
+  });
+});
+
+describe("detectUnknownCommand", () => {
+  const program = buildToyProgram();
+
+  it("returns null when no positional is present (root --help / --version)", () => {
+    expect(detectUnknownCommand(program, ["--help"])).toBeNull();
+    expect(detectUnknownCommand(program, ["-V"])).toBeNull();
+    expect(detectUnknownCommand(program, [])).toBeNull();
+  });
+
+  it("returns null when the first positional is a known command", () => {
+    expect(detectUnknownCommand(program, ["status"])).toBeNull();
+    expect(detectUnknownCommand(program, ["status", "--json"])).toBeNull();
+  });
+
+  it("returns null when the first positional is a registered alias", () => {
+    expect(detectUnknownCommand(program, ["ls"])).toBeNull();
+  });
+
+  it("flags an unknown first positional even when --help follows", () => {
+    expect(detectUnknownCommand(program, ["invalid", "--help"])).toEqual({
+      token: "invalid",
+    });
+  });
+
+  it("flags an unknown first positional even when --help precedes it", () => {
+    expect(detectUnknownCommand(program, ["--help", "invalid"])).toEqual({
+      token: "invalid",
+    });
+  });
+
+  it("includes a suggestion when the unknown token is close to a known one", () => {
+    expect(detectUnknownCommand(program, ["confg", "--help"])).toEqual({
+      token: "confg",
+      suggestion: "config",
+    });
+  });
+
+  it("omits suggestion when nothing is close enough", () => {
+    expect(detectUnknownCommand(program, ["xyzzy"])).toEqual({
+      token: "xyzzy",
+    });
+  });
+});
+
+describe("formatUnknownCommandMessage", () => {
+  it("emits two lines when there is no suggestion", () => {
+    const msg = formatUnknownCommandMessage({ token: "invalid" });
+    expect(msg.split("\n")).toEqual([
+      "unknown command 'invalid'",
+      "Run 'assistant --help' to see a list of available commands.",
+    ]);
+  });
+
+  it("inserts the suggestion line between the header and footer", () => {
+    const msg = formatUnknownCommandMessage({
+      token: "confg",
+      suggestion: "config",
+    });
+    expect(msg.split("\n")).toEqual([
+      "unknown command 'confg'",
+      "(Did you mean 'config'?)",
+      "Run 'assistant --help' to see a list of available commands.",
+    ]);
+  });
+});

package/src/cli/lib/cli-colors.ts

@@ -0,0 +1,12 @@
+/**
+ * Minimal ANSI red wrapper for CLI error output. Respects `NO_COLOR`
+ * (https://no-color.org/) and skips coloring when stderr is not a TTY so
+ * piped/captured output stays clean.
+ */
+export function red(text: string): string {
+  if (!process.stderr.isTTY) return text;
+  if (process.env.NO_COLOR !== undefined && process.env.NO_COLOR !== "") {
+    return text;
+  }
+  return `\x1b[31m${text}\x1b[0m`;
+}