@vellumai/assistant 0.8.0 → 0.8.2

package/src/cli/lib/__tests__/install-from-github.test.ts

@@ -0,0 +1,355 @@
+/**
+ * Tests for {@link installPlugin}.
+ *
+ * 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 {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  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 {
+  type FetchLike,
+  installPlugin,
+  InvalidPluginNameError,
+  PluginAlreadyInstalledError,
+  PluginNotFoundError,
+  sanitizePluginName,
+} from "../install-from-github.js";
+
+/**
+ * Build a GitHub Contents API fixture from an in-memory file tree.
+ *
+ * `tree` maps a path under the canonical prefix (e.g. `simple-memory`,
+ * `simple-memory/hooks/init.ts`) to either:
+ *   - a `Uint8Array`/`string` → a file with that content
+ *   - `null` → a directory
+ *
+ * The fixture answers GET requests against
+ *  - `https://api.github.com/repos/vellum-ai/vellum-assistant/contents/...`
+ *  - any other URL we hand out as `download_url`
+ */
+function fixtureFetch(
+  tree: Record<string, Uint8Array | string | null>,
+): FetchLike {
+  const PREFIX_API =
+    "https://api.github.com/repos/vellum-ai/vellum-assistant/contents/experimental/plugins/";
+  const PREFIX_RAW =
+    "https://raw.githubusercontent.com/vellum-ai/vellum-assistant/main/experimental/plugins/";
+
+  function listing(apiPath: string): unknown {
+    const rel = apiPath.startsWith("experimental/plugins/")
+      ? apiPath.slice("experimental/plugins/".length)
+      : apiPath;
+    const prefix = rel ? rel + "/" : "";
+    const direct = new Map<string, "file" | "dir">();
+    for (const key of Object.keys(tree)) {
+      if (!key.startsWith(prefix)) continue;
+      const remainder = key.slice(prefix.length);
+      if (!remainder) continue;
+      const [head, ...rest] = remainder.split("/");
+      if (rest.length === 0) {
+        const isDir = tree[key] === null;
+        if (!direct.has(head!)) direct.set(head!, isDir ? "dir" : "file");
+      } else {
+        if (!direct.has(head!)) direct.set(head!, "dir");
+      }
+    }
+    if (direct.size === 0) return null;
+    return Array.from(direct.entries()).map(([name, type]) => ({
+      name,
+      // GitHub returns `path` rooted at the repo, not relative to the queried
+      // directory — mirror that so the recursive copy hits the same fixture
+      // handler on the way down.
+      path: `experimental/plugins/${prefix}${name}`,
+      type,
+      size: type === "file" ? (tree[`${prefix}${name}`] as string).length : 0,
+      download_url:
+        type === "file" ? `${PREFIX_RAW}${prefix}${name}` : null,
+    }));
+  }
+
+  return (async (input: RequestInfo | URL, _init?: RequestInit) => {
+    const url = typeof input === "string" ? input : input.toString();
+
+    if (url.startsWith(PREFIX_API)) {
+      const after = url.slice(PREFIX_API.length).split("?")[0]!;
+      const apiPath = `experimental/plugins/${decodeURIComponent(after)}`;
+      const body = listing(apiPath);
+      if (body === null) {
+        return new Response("not found", { status: 404 });
+      }
+      return new Response(JSON.stringify(body), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      });
+    }
+
+    if (url.startsWith(PREFIX_RAW)) {
+      const key =
+        "experimental/plugins/" +
+        decodeURIComponent(url.slice(PREFIX_RAW.length));
+      const rel = key.slice("experimental/plugins/".length);
+      const file = tree[rel];
+      if (file === null || file === undefined) {
+        return new Response("not found", { status: 404 });
+      }
+      const bytes =
+        typeof file === "string" ? new TextEncoder().encode(file) : file;
+      return new Response(Buffer.from(bytes), { status: 200 });
+    }
+
+    return new Response("unexpected url: " + url, { status: 500 });
+  }) as FetchLike;
+}
+
+describe("installPlugin", () => {
+  let ws: string;
+  let pluginsDir: string;
+
+  beforeEach(() => {
+    ws = mkdtempSync(join(tmpdir(), "vellum-plugins-install-"));
+    pluginsDir = join(ws, "plugins");
+    mkdirSync(pluginsDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(ws, { recursive: true, force: true });
+  });
+
+  test("copies the GitHub tree into <workspacePluginsDir>/<name>", async () => {
+    const result = await installPlugin(
+      { name: "simple-memory", force: false, ref: "main" },
+      {
+        fetch: fixtureFetch({
+          "simple-memory": null,
+          "simple-memory/package.json": '{"name":"simple-memory"}',
+          "simple-memory/README.md": "# simple-memory",
+          "simple-memory/hooks": null,
+          "simple-memory/hooks/init.ts": "export default async () => {};\n",
+          "simple-memory/tools": null,
+          "simple-memory/tools/ping.ts": "export default {};\n",
+        }),
+        workspacePluginsDir: pluginsDir,
+      },
+    );
+
+    const target = join(pluginsDir, "simple-memory");
+    expect(result.target).toBe(target);
+    expect(result.fileCount).toBe(4);
+    expect(result.ref).toBe("main");
+    expect(existsSync(join(target, "package.json"))).toBe(true);
+    expect(existsSync(join(target, "README.md"))).toBe(true);
+    expect(existsSync(join(target, "hooks", "init.ts"))).toBe(true);
+    expect(existsSync(join(target, "tools", "ping.ts"))).toBe(true);
+    expect(readFileSync(join(target, "package.json"), "utf-8")).toBe(
+      '{"name":"simple-memory"}',
+    );
+  });
+
+  test("refuses to overwrite an existing install without --force", async () => {
+    const target = join(pluginsDir, "simple-memory");
+    mkdirSync(target, { recursive: true });
+    writeFileSync(join(target, "marker"), "pre-existing");
+
+    await expect(
+      installPlugin(
+        { name: "simple-memory", force: false, ref: "main" },
+        {
+          fetch: fixtureFetch({
+            "simple-memory": null,
+            "simple-memory/package.json": "{}",
+          }),
+          workspacePluginsDir: pluginsDir,
+        },
+      ),
+    ).rejects.toBeInstanceOf(PluginAlreadyInstalledError);
+
+    // The pre-existing marker is left untouched on refusal.
+    expect(readFileSync(join(target, "marker"), "utf-8")).toBe("pre-existing");
+  });
+
+  test("--force replaces an existing install", async () => {
+    const target = join(pluginsDir, "simple-memory");
+    mkdirSync(target, { recursive: true });
+    writeFileSync(join(target, "marker"), "pre-existing");
+
+    await installPlugin(
+      { name: "simple-memory", force: true, ref: "main" },
+      {
+        fetch: fixtureFetch({
+          "simple-memory": null,
+          "simple-memory/package.json": '{"name":"simple-memory"}',
+        }),
+        workspacePluginsDir: pluginsDir,
+      },
+    );
+
+    expect(existsSync(join(target, "marker"))).toBe(false);
+    expect(existsSync(join(target, "package.json"))).toBe(true);
+  });
+
+  test("--force preserves the existing install when the fetch fails", async () => {
+    // Codex P1 from PR-5 review: a transient 5xx during a forced re-install
+    // must NOT delete the previously working plugin. The fetch error
+    // surfaces, but the existing tree on disk is untouched.
+    const target = join(pluginsDir, "simple-memory");
+    mkdirSync(target, { recursive: true });
+    writeFileSync(join(target, "marker"), "pre-existing");
+
+    await expect(
+      installPlugin(
+        { name: "simple-memory", force: true, ref: "main" },
+        {
+          fetch: (async () =>
+            new Response("upstream broken", { status: 503 })) as FetchLike,
+          workspacePluginsDir: pluginsDir,
+        },
+      ),
+    ).rejects.toThrow(/HTTP 503/);
+
+    // Marker is still there because the failed install never touched the
+    // target — the staging dir handles all writes until the swap.
+    expect(readFileSync(join(target, "marker"), "utf-8")).toBe("pre-existing");
+    // And no staging dir leaks into the plugins directory.
+    const remaining = readdirSync(pluginsDir);
+    expect(remaining).toEqual(["simple-memory"]);
+  });
+
+  test("404 on the canonical path is reported as not-found", async () => {
+    await expect(
+      installPlugin(
+        { name: "missing-plugin", force: false, ref: "main" },
+        {
+          fetch: fixtureFetch({}),
+          workspacePluginsDir: pluginsDir,
+        },
+      ),
+    ).rejects.toBeInstanceOf(PluginNotFoundError);
+
+    expect(existsSync(join(pluginsDir, "missing-plugin"))).toBe(false);
+    // And no staging dir leaks either.
+    expect(readdirSync(pluginsDir)).toEqual([]);
+  });
+
+  test("HTTP 5xx from GitHub propagates and leaves no staging behind", async () => {
+    await expect(
+      installPlugin(
+        { name: "demo", force: false, ref: "main" },
+        {
+          fetch: (async () =>
+            new Response("upstream broken", { status: 503 })) as FetchLike,
+          workspacePluginsDir: pluginsDir,
+        },
+      ),
+    ).rejects.toThrow(/HTTP 503/);
+
+    expect(existsSync(join(pluginsDir, "demo"))).toBe(false);
+    expect(readdirSync(pluginsDir)).toEqual([]);
+  });
+
+  test("respects ref by forwarding to GitHub", async () => {
+    let seenRef: string | undefined;
+    await installPlugin(
+      { name: "demo", force: false, ref: "feat-branch" },
+      {
+        fetch: (async (input: RequestInfo | URL) => {
+          const url = typeof input === "string" ? input : input.toString();
+          if (url.includes("api.github.com")) {
+            const m = /[?&]ref=([^&]+)/.exec(url);
+            seenRef = m ? decodeURIComponent(m[1]!) : undefined;
+            return new Response(
+              JSON.stringify([
+                {
+                  name: "package.json",
+                  path: "experimental/plugins/demo/package.json",
+                  type: "file",
+                  size: 2,
+                  download_url:
+                    "https://raw.githubusercontent.com/vellum-ai/vellum-assistant/feat-branch/experimental/plugins/demo/package.json",
+                },
+              ]),
+              {
+                status: 200,
+                headers: { "content-type": "application/json" },
+              },
+            );
+          }
+          return new Response("{}", { status: 200 });
+        }) as FetchLike,
+        workspacePluginsDir: pluginsDir,
+      },
+    );
+
+    expect(seenRef).toBe("feat-branch");
+    expect(existsSync(join(pluginsDir, "demo", "package.json"))).toBe(true);
+  });
+
+  test("rejects untrusted entry names from the GitHub response", async () => {
+    // Devin P2 from PR-5 review: even though GitHub returns trustworthy data,
+    // defense-in-depth requires us to validate `entry.name` before any
+    // filesystem write. A malicious or buggy upstream that hands us
+    // `../escape` must not be able to write outside the target.
+    const badFetch: FetchLike = (async (input: RequestInfo | URL) => {
+      const url = typeof input === "string" ? input : input.toString();
+      if (url.includes("api.github.com")) {
+        return new Response(
+          JSON.stringify([
+            {
+              name: "../escape",
+              path: "experimental/plugins/demo/../escape",
+              type: "file",
+              size: 1,
+              download_url:
+                "https://raw.githubusercontent.com/vellum-ai/vellum-assistant/main/experimental/plugins/demo/escape",
+            },
+          ]),
+          { status: 200, headers: { "content-type": "application/json" } },
+        );
+      }
+      return new Response("x", { status: 200 });
+    }) as FetchLike;
+
+    await expect(
+      installPlugin(
+        { name: "demo", force: false, ref: "main" },
+        { fetch: badFetch, workspacePluginsDir: pluginsDir },
+      ),
+    ).rejects.toThrow(/Unsafe entry name/);
+
+    // Nothing was written outside the target — in fact, the target itself
+    // is gone because the failed install rolled back the staging dir.
+    expect(existsSync(join(pluginsDir, "..", "escape"))).toBe(false);
+    expect(readdirSync(pluginsDir)).toEqual([]);
+  });
+});
+
+describe("sanitizePluginName", () => {
+  test.each([
+    ["../escape"],
+    ["/abs/path"],
+    [".hidden"],
+    ["Name-WithCaps"],
+    [""],
+    ["space name"],
+  ])("rejects invalid plugin name %p", (bad) => {
+    expect(() => sanitizePluginName(bad)).toThrow(InvalidPluginNameError);
+  });
+
+  test("accepts simple kebab-case + underscores + digits", () => {
+    expect(sanitizePluginName("simple-memory")).toBe("simple-memory");
+    expect(sanitizePluginName("plugin_2")).toBe("plugin_2");
+    expect(sanitizePluginName("a")).toBe("a");
+  });
+});

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__/register-command.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, test } from "bun:test";
+
+import { Command } from "commander";
+
+import { type CommandTransport, registerCommand } from "../register-command.js";
+
+describe("registerCommand", () => {
+  test("registers a command with the correct name and description", () => {
+    const parent = new Command();
+    const result = registerCommand(parent, {
+      name: "test-cmd",
+      transport: "ipc",
+      description: "A test command",
+      build: () => {},
+    });
+
+    expect(result.name()).toBe("test-cmd");
+    expect(result.description()).toBe("A test command");
+  });
+
+  test("calls build with the command instance", () => {
+    const parent = new Command();
+    let receivedCmd: Command | undefined;
+
+    registerCommand(parent, {
+      name: "my-cmd",
+      transport: "local",
+      description: "My command",
+      build: (cmd) => {
+        receivedCmd = cmd;
+      },
+    });
+
+    expect(receivedCmd).toBeDefined();
+    expect(receivedCmd!.name()).toBe("my-cmd");
+  });
+
+  test("returns the registered command", () => {
+    const parent = new Command();
+    const result = registerCommand(parent, {
+      name: "ret-cmd",
+      transport: "bootstrap",
+      description: "Return test",
+      build: () => {},
+    });
+
+    expect(result).toBeInstanceOf(Command);
+    expect(result.name()).toBe("ret-cmd");
+  });
+
+  test.each([
+    ["ipc" as CommandTransport],
+    ["local" as CommandTransport],
+    ["bootstrap" as CommandTransport],
+  ])("accepts transport value: %s", (transport) => {
+    const parent = new Command();
+    let buildCalled = false;
+
+    const result = registerCommand(parent, {
+      name: `cmd-${transport}`,
+      transport,
+      description: `Command with transport ${transport}`,
+      build: () => {
+        buildCalled = true;
+      },
+    });
+
+    expect(buildCalled).toBe(true);
+    expect(result.name()).toBe(`cmd-${transport}`);
+    expect(result.description()).toBe(`Command with transport ${transport}`);
+  });
+
+  test("attaches the command as a subcommand of parent", () => {
+    const parent = new Command("program");
+    registerCommand(parent, {
+      name: "sub",
+      transport: "ipc",
+      description: "Subcommand",
+      build: () => {},
+    });
+
+    const names = parent.commands.map((c) => c.name());
+    expect(names).toContain("sub");
+  });
+});