@vellumai/assistant 0.10.0 → 0.10.1-staging.1

package/src/cli/lib/__tests__/plugin-pin-history.test.ts

@@ -0,0 +1,162 @@
+/**
+ * Tests for {@link listPinHistory} and {@link resolvePinToMarketplaceCommit}.
+ *
+ * The marketplace manifest stores only the current pin, so pin history is
+ * reconstructed by walking the manifest's commit history and reading the
+ * plugin's pin at each commit. The fixtures model that timeline with an
+ * in-memory `fetch`: a commits-list endpoint plus a manifest-at-ref endpoint
+ * keyed by commit SHA.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import type { FetchLike } from "../install-from-github.js";
+import {
+  listPinHistory,
+  resolvePinToMarketplaceCommit,
+} from "../plugin-pin-history.js";
+
+const PIN_A = "a".repeat(40);
+const PIN_B = "b".repeat(40);
+const PIN_C = "c".repeat(40);
+
+// Marketplace-manifest commits, newest → oldest. `C2B` touches the manifest
+// without changing this plugin's pin (a bump for some other plugin), so it must
+// collapse into the same distinct pin as `C3`.
+const C3 = "3".repeat(40);
+const C2B = "d".repeat(40);
+const C2 = "2".repeat(40);
+const C1 = "1".repeat(40);
+
+const COMMIT_DATES: Record<string, string> = {
+  [C3]: "2026-06-10T00:00:00.000Z",
+  [C2B]: "2026-06-08T00:00:00.000Z",
+  [C2]: "2026-06-05T00:00:00.000Z",
+  [C1]: "2026-06-01T00:00:00.000Z",
+};
+
+/** Plugin pin resolved from the manifest at each ref (`main` = current tip). */
+const PIN_BY_REF: Record<string, string> = {
+  main: PIN_C,
+  [C3]: PIN_C,
+  [C2B]: PIN_C,
+  [C2]: PIN_B,
+  [C1]: PIN_A,
+};
+
+function manifest(pin: string): string {
+  return JSON.stringify({
+    name: "vellum",
+    plugins: [
+      {
+        name: "level-up",
+        source: { source: "github", repo: "example-org/level-up", ref: pin },
+      },
+    ],
+  });
+}
+
+/**
+ * Build a `fetch` serving the commits list and the manifest at each ref.
+ * `commits` is the newest-first commit list the API returns.
+ */
+function makeFetch(commits: string[] = [C3, C2B, C2, C1]): FetchLike {
+  return (async (input: RequestInfo | URL) => {
+    const url = typeof input === "string" ? input : input.toString();
+    if (url.includes("/commits?")) {
+      const body = commits.map((sha) => ({
+        sha,
+        commit: { committer: { date: COMMIT_DATES[sha] } },
+      }));
+      return new Response(JSON.stringify(body), { status: 200 });
+    }
+    const m = url.match(/contents\/plugins\/marketplace\.json\?ref=([^&]+)/);
+    if (m) {
+      const ref = decodeURIComponent(m[1]!);
+      const pin = PIN_BY_REF[ref];
+      if (!pin) return new Response("not found", { status: 404 });
+      return new Response(manifest(pin), { status: 200 });
+    }
+    return new Response("unexpected url: " + url, { status: 500 });
+  }) as FetchLike;
+}
+
+describe("listPinHistory", () => {
+  test("lists distinct pins newest-first, collapsing unchanged revisions", async () => {
+    // GIVEN a manifest history with three distinct pins (one commit left the
+    // plugin's pin unchanged)
+    const history = await listPinHistory("level-up", { fetch: makeFetch() });
+
+    // THEN one entry per distinct pin, newest first, each tagged with the
+    // newest marketplace commit that carries it
+    expect(history).toEqual([
+      {
+        pin: PIN_C,
+        marketplaceCommit: C3,
+        promotedAt: COMMIT_DATES[C3]!,
+        current: true,
+      },
+      {
+        pin: PIN_B,
+        marketplaceCommit: C2,
+        promotedAt: COMMIT_DATES[C2]!,
+        current: false,
+      },
+      {
+        pin: PIN_A,
+        marketplaceCommit: C1,
+        promotedAt: COMMIT_DATES[C1]!,
+        current: false,
+      },
+    ]);
+  });
+
+  test("honors the limit (newest pins win)", async () => {
+    const history = await listPinHistory(
+      "level-up",
+      { fetch: makeFetch() },
+      { limit: 2 },
+    );
+    expect(history.map((e) => e.pin)).toEqual([PIN_C, PIN_B]);
+  });
+
+  test("returns an empty list for a plugin absent from every revision", async () => {
+    const history = await listPinHistory("ghost", { fetch: makeFetch() });
+    expect(history).toEqual([]);
+  });
+
+  test("returns an empty list when the manifest has no commit history", async () => {
+    const history = await listPinHistory("level-up", {
+      fetch: makeFetch([]),
+    });
+    expect(history).toEqual([]);
+  });
+});
+
+describe("resolvePinToMarketplaceCommit", () => {
+  test("maps a reviewed pin to the marketplace commit that introduced it", async () => {
+    const entry = await resolvePinToMarketplaceCommit("level-up", PIN_B, {
+      fetch: makeFetch(),
+    });
+    expect(entry?.marketplaceCommit).toBe(C2);
+    expect(entry?.pin).toBe(PIN_B);
+  });
+
+  test("is case-insensitive on the pin SHA", async () => {
+    const entry = await resolvePinToMarketplaceCommit(
+      "level-up",
+      PIN_B.toUpperCase(),
+      { fetch: makeFetch() },
+    );
+    expect(entry?.marketplaceCommit).toBe(C2);
+  });
+
+  test("returns null for a pin not in the reviewed history", async () => {
+    const entry = await resolvePinToMarketplaceCommit(
+      "level-up",
+      "f".repeat(40),
+      { fetch: makeFetch() },
+    );
+    expect(entry).toBeNull();
+  });
+});

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

@@ -0,0 +1,158 @@
+import { existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+
+import {
+  disablePlugin,
+  enablePlugin,
+  InvalidPluginNameError,
+  PluginAlreadyInStateException,
+  PluginDirectoryNotFoundError,
+} from "../toggle-plugin.js";
+
+// VELLUM_WORKSPACE_DIR is set to this; getWorkspacePluginsDir() returns
+// <workspace>/plugins, so the actual plugins directory is TMP_WS_DIR/plugins.
+const TMP_WS_DIR = join(import.meta.dir, "__tmp__toggle-plugin-test");
+const TMP_PLUGINS_DIR = join(TMP_WS_DIR, "plugins");
+
+beforeEach(() => {
+  rmSync(TMP_WS_DIR, { recursive: true, force: true });
+  mkdirSync(TMP_PLUGINS_DIR, { recursive: true });
+  process.env.VELLUM_WORKSPACE_DIR = TMP_WS_DIR;
+});
+
+afterEach(() => {
+  rmSync(TMP_WS_DIR, { recursive: true, force: true });
+  delete process.env.VELLUM_WORKSPACE_DIR;
+});
+
+describe("disablePlugin", () => {
+  it("creates .disabled sentinel for an existing user plugin directory", () => {
+    const pluginDir = join(TMP_PLUGINS_DIR, "my-plugin");
+    mkdirSync(pluginDir, { recursive: true });
+    writeFileSync(join(pluginDir, "package.json"), "{}");
+
+    const result = disablePlugin("my-plugin");
+
+    expect(result.action).toBe("disable");
+    expect(existsSync(join(pluginDir, ".disabled"))).toBe(true);
+  });
+
+  it("creates a stub directory for a default plugin that does not exist yet", () => {
+    const pluginDir = join(TMP_PLUGINS_DIR, "default-advisor");
+
+    const result = disablePlugin("default-advisor");
+
+    expect(result.action).toBe("disable");
+    expect(existsSync(pluginDir)).toBe(true);
+    expect(existsSync(join(pluginDir, ".disabled"))).toBe(true);
+  });
+
+  it("throws PluginAlreadyInStateException if already disabled", () => {
+    const pluginDir = join(TMP_PLUGINS_DIR, "my-plugin");
+    mkdirSync(pluginDir, { recursive: true });
+    writeFileSync(join(pluginDir, ".disabled"), "");
+
+    expect(() => disablePlugin("my-plugin")).toThrow(
+      PluginAlreadyInStateException,
+    );
+  });
+
+  it("throws PluginDirectoryNotFoundError for non-default plugin with no directory", () => {
+    expect(() => disablePlugin("nonexistent-plugin")).toThrow(
+      PluginDirectoryNotFoundError,
+    );
+  });
+
+  it("throws InvalidPluginNameError for path traversal attempts", () => {
+    expect(() => disablePlugin("../state")).toThrow(InvalidPluginNameError);
+    expect(() => disablePlugin("foo/bar")).toThrow(InvalidPluginNameError);
+    expect(() => disablePlugin("..")).toThrow(InvalidPluginNameError);
+  });
+
+  it("throws InvalidPluginNameError for names with invalid characters", () => {
+    expect(() => disablePlugin("My_Plugin!")).toThrow(InvalidPluginNameError);
+    expect(() => disablePlugin("")).toThrow(InvalidPluginNameError);
+    expect(() => disablePlugin(" ")).toThrow(InvalidPluginNameError);
+  });
+});
+
+describe("enablePlugin", () => {
+  it("removes .disabled sentinel from a user plugin directory", () => {
+    const pluginDir = join(TMP_PLUGINS_DIR, "my-plugin");
+    mkdirSync(pluginDir, { recursive: true });
+    writeFileSync(join(pluginDir, "package.json"), "{}");
+    writeFileSync(join(pluginDir, ".disabled"), "");
+
+    const result = enablePlugin("my-plugin");
+
+    expect(result.action).toBe("enable");
+    expect(existsSync(join(pluginDir, ".disabled"))).toBe(false);
+    // Plugin directory should still exist (it has package.json).
+    expect(existsSync(pluginDir)).toBe(true);
+  });
+
+  it("removes stub directory for a default plugin when it becomes empty", () => {
+    const pluginDir = join(TMP_PLUGINS_DIR, "default-advisor");
+    mkdirSync(pluginDir, { recursive: true });
+    writeFileSync(join(pluginDir, ".disabled"), "");
+
+    enablePlugin("default-advisor");
+
+    // Stub directory should be cleaned up since it only had the sentinel.
+    expect(existsSync(pluginDir)).toBe(false);
+  });
+
+  it("keeps stub directory if it has other files besides .disabled", () => {
+    const pluginDir = join(TMP_PLUGINS_DIR, "default-advisor");
+    mkdirSync(pluginDir, { recursive: true });
+    writeFileSync(join(pluginDir, ".disabled"), "");
+    writeFileSync(join(pluginDir, "README.md"), "hello");
+
+    enablePlugin("default-advisor");
+
+    expect(existsSync(pluginDir)).toBe(true);
+    expect(existsSync(join(pluginDir, ".disabled"))).toBe(false);
+    expect(readdirSync(pluginDir)).toContain("README.md");
+  });
+
+  it("throws PluginAlreadyInStateException if not disabled", () => {
+    const pluginDir = join(TMP_PLUGINS_DIR, "my-plugin");
+    mkdirSync(pluginDir, { recursive: true });
+    writeFileSync(join(pluginDir, "package.json"), "{}");
+
+    expect(() => enablePlugin("my-plugin")).toThrow(
+      PluginAlreadyInStateException,
+    );
+  });
+
+  it("throws InvalidPluginNameError for path traversal attempts", () => {
+    expect(() => enablePlugin("../state")).toThrow(InvalidPluginNameError);
+    expect(() => enablePlugin("foo/bar")).toThrow(InvalidPluginNameError);
+  });
+});
+
+describe("disable then enable round-trip", () => {
+  it("default plugin: disable creates stub, enable removes it", () => {
+    const pluginDir = join(TMP_PLUGINS_DIR, "default-memory-retrieval");
+
+    disablePlugin("default-memory-retrieval");
+    expect(existsSync(join(pluginDir, ".disabled"))).toBe(true);
+
+    enablePlugin("default-memory-retrieval");
+    expect(existsSync(pluginDir)).toBe(false);
+  });
+
+  it("user plugin: disable then enable leaves directory intact", () => {
+    const pluginDir = join(TMP_PLUGINS_DIR, "my-plugin");
+    mkdirSync(pluginDir, { recursive: true });
+    writeFileSync(join(pluginDir, "package.json"), '{"name":"my-plugin"}');
+
+    disablePlugin("my-plugin");
+    expect(existsSync(join(pluginDir, ".disabled"))).toBe(true);
+
+    enablePlugin("my-plugin");
+    expect(existsSync(join(pluginDir, ".disabled"))).toBe(false);
+    expect(existsSync(join(pluginDir, "package.json"))).toBe(true);
+  });
+});

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

@@ -112,6 +112,16 @@ export interface InstallPluginOptions {
   readonly force?: boolean;
   /** Git ref (branch, tag, SHA) to fetch from. Defaults to {@link DEFAULT_PLUGIN_REF}. */
   readonly ref?: string;
+  /**
+   * Materialize this exact plugin commit SHA instead of the pin the marketplace
+   * manifest records, while still resolving the plugin's owner/repo/path (and
+   * the curated adapter stub) from the manifest at {@link InstallPluginOptions.ref}.
+   * This is the CLI-only escape hatch for installing an unreviewed revision; the
+   * adapter stub therefore comes from the manifest's `ref`, not the override's
+   * era, so an adapted plugin may not reproduce a historical version faithfully.
+   * Unset for normal installs, which take the reviewed pin from the manifest.
+   */
+  readonly commitOverride?: string;
 }
 
 /** Dependencies injected by the caller. */
@@ -144,9 +154,11 @@ export interface InstallPluginResult {
 
 /** Plugin name failed sanitization. */
 export class InvalidPluginNameError extends Error {
-  constructor(name: string) {
+  constructor(name: string, reason?: string) {
     super(
-      `Invalid plugin name "${name}". Names must match /^[a-z0-9][a-z0-9_-]*$/.`,
+      reason
+        ? `Invalid plugin name "${name}". ${reason}`
+        : `Invalid plugin name "${name}". Names must match /^[a-z0-9][a-z0-9_-]*$/.`,
     );
     this.name = "InvalidPluginNameError";
   }
@@ -279,12 +291,24 @@ async function resolvePluginSource(
   };
 }
 
+/**
+ * Prefix reserved for first-party default plugins that ship in the assistant
+ * source tree. User-installable plugins must not use it — the `.disabled`
+ * sentinel and the plugin registry both key on manifest names, and a
+ * user plugin with a `default-` name would shadow or collide with the
+ * built-in.
+ */
+export const RESERVED_PLUGIN_PREFIX = "default-";
+
 /**
  * Reject plugin names that could escape the canonical source path or the
  * install target. The source convention is a flat namespace under
  * `plugins/`, so a legitimate name is a single path segment
  * built from kebab-case alphanumerics.
  *
+ * Names prefixed with {@link RESERVED_PLUGIN_PREFIX} (`default-`) are also
+ * rejected — that prefix is reserved for first-party default plugins.
+ *
  * Exported so callers (e.g. the CLI input prompt) can validate up front
  * before invoking {@link installPlugin}.
  */
@@ -293,6 +317,12 @@ export function sanitizePluginName(name: string): string {
   if (!/^[a-z0-9][a-z0-9_-]*$/.test(trimmed)) {
     throw new InvalidPluginNameError(name);
   }
+  if (trimmed.startsWith(RESERVED_PLUGIN_PREFIX)) {
+    throw new InvalidPluginNameError(
+      name,
+      `The "${RESERVED_PLUGIN_PREFIX}" prefix is reserved for first-party default plugins.`,
+    );
+  }
   return trimmed;
 }
 
@@ -345,7 +375,13 @@ export async function installPlugin(
       "plugins/marketplace.json",
     );
   }
-  const ref = source.ref;
+  // A commit override installs a specific plugin revision while still taking
+  // owner/repo/path (and the adapter stub, via `marketplaceRef`) from the
+  // manifest; otherwise the reviewed pin from the manifest is materialized.
+  const effectiveSource: PluginFetchSource = opts.commitOverride
+    ? { ...source, ref: opts.commitOverride }
+    : source;
+  const ref = effectiveSource.ref;
 
   const pluginsDir = deps.workspacePluginsDir ?? getWorkspacePluginsDir();
   const target = join(pluginsDir, name);
@@ -377,7 +413,12 @@ export async function installPlugin(
   let committedAt: string | null = null;
   try {
     const materialized = await materializePluginTree(
-      { source, name, stubRef: marketplaceRef, destDir: stagingDir },
+      {
+        source: effectiveSource,
+        name,
+        stubRef: marketplaceRef,
+        destDir: stagingDir,
+      },
       deps,
     );
     fileCount = materialized.fileCount;
@@ -390,12 +431,12 @@ export async function installPlugin(
 
   if (fileCount === 0) {
     rmSync(stagingDir, { recursive: true, force: true });
-    throw new PluginNotFoundError(name, ref, sourceLabel(source));
+    throw new PluginNotFoundError(name, ref, sourceLabel(effectiveSource));
   }
 
   finalizeStagedInstall(stagingDir, {
     name,
-    source,
+    source: effectiveSource,
     ref,
     commit,
     committedAt,

package/src/cli/lib/plugin-marketplace.ts

@@ -35,6 +35,17 @@ const MARKETPLACE_SOURCE_OWNER = "vellum-ai";
 const MARKETPLACE_SOURCE_REPO = "vellum-assistant";
 const MARKETPLACE_FILE_PATH = "plugins/marketplace.json";
 
+/**
+ * Canonical GitHub coordinates of the marketplace manifest, exported so
+ * sibling readers (e.g. {@link ./plugin-pin-history}) resolve the same
+ * `owner/repo:path` rather than re-declaring it.
+ */
+export const MARKETPLACE_MANIFEST_LOCATION = {
+  owner: MARKETPLACE_SOURCE_OWNER,
+  repo: MARKETPLACE_SOURCE_REPO,
+  path: MARKETPLACE_FILE_PATH,
+} as const;
+
 // ---------------------------------------------------------------------------
 // Manifest schema (subset of the Claude Code marketplace schema)
 // ---------------------------------------------------------------------------