@vellumai/assistant 0.10.0 → 0.10.1-dev.202606240317.ea25efe

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

@@ -13,10 +13,25 @@
  */
 
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 
 import { getWorkspacePluginsDir } from "../../util/platform.js";
 
+/**
+ * Directory containing first-party default plugin packages. Each subdirectory
+ * has a `package.json` with `name` (prefixed `default-`) and `version`.
+ * Read from the filesystem at call time to avoid pulling hook/tool
+ * implementations into the CLI process (which would create circular
+ * dependencies in test environments).
+ */
+const DEFAULT_PLUGINS_DIR = join(
+  dirname(new URL(import.meta.url).pathname),
+  "..",
+  "..",
+  "plugins",
+  "defaults",
+);
+
 /** Minimal manifest fields surfaced to the CLI. */
 export interface PluginPackageMetadata {
   readonly name?: string;
@@ -40,6 +55,20 @@ export interface InstalledPluginInfo {
   readonly issues: readonly string[];
 }
 
+/** Where the plugin comes from. */
+export type PluginSource = "user" | "default";
+
+/**
+ * Extended plugin entry that includes source (`user` vs `default`) and
+ * disabled status. Used by {@link listAllPlugins}.
+ */
+export interface AllPluginInfo extends InstalledPluginInfo {
+  /** Whether this is a user-installed or first-party default plugin. */
+  readonly source: PluginSource;
+  /** Whether the plugin is disabled via a `.disabled` sentinel file. */
+  readonly disabled: boolean;
+}
+
 /** Options accepted by {@link listInstalledPlugins}. */
 export interface ListInstalledPluginsOptions {
   /** Override the workspace plugins directory. Falls back to {@link getWorkspacePluginsDir}. */
@@ -146,3 +175,152 @@ function readPluginEntry(
 
   return { name, target, packageJson, issues };
 }
+
+/**
+ * List all plugins — both user-installed (from `<workspace>/plugins/`) and
+ * first-party defaults (from the source tree). Each entry is annotated with
+ * its `source` (`"user"` or `"default"`) and `disabled` status (whether a
+ * `.disabled` sentinel file exists in the plugin's workspace directory).
+ *
+ * For user plugins, the `.disabled` file lives in the plugin's own install
+ * directory. For default plugins, it lives in a stub directory at
+ * `<workspace>/plugins/<manifest-name>/` (created by `plugins disable`).
+ *
+ * Stub directories created by `plugins disable <default-name>` are excluded
+ * from the user listing so a disabled default plugin appears only once (as a
+ * default entry, not a duplicate user entry with "missing package.json").
+ *
+ * Sort order:
+ * 1. Enabled user plugins (by install date, oldest first — matches
+ *    hook/tool resolution order)
+ * 2. Disabled user plugins (by install date)
+ * 3. Enabled default plugins (by repo array order — matches registration
+ *    order which fixes hook-chain order)
+ * 4. Disabled default plugins (by repo array order)
+ */
+export function listAllPlugins(
+  opts: ListInstalledPluginsOptions = {},
+): AllPluginInfo[] {
+  const pluginsDir = opts.workspacePluginsDir ?? getWorkspacePluginsDir();
+
+  // ── User plugins ───────────────────────────────────────────────────────
+  // Filter out default-plugin stub directories (created by `plugins disable
+  // default-<name>`) so they don't show up as duplicate user entries.
+  const defaultNames = new Set(
+    readDefaultPluginManifests().map((m) => m.name),
+  );
+  const userPlugins: AllPluginInfo[] = listInstalledPlugins(opts)
+    .filter((entry) => !defaultNames.has(entry.name))
+    .map((entry) => ({
+      ...entry,
+      source: "user" as const,
+      disabled: existsSync(join(entry.target, ".disabled")),
+    }));
+
+  // ── Default plugins ────────────────────────────────────────────────────
+  // Default plugins live in the source tree at src/plugins/defaults/<name>/.
+  // Read each package.json from the filesystem to get name+version without
+  // importing hook/tool implementations (which would create circular
+  // dependencies in test environments). The .disabled sentinel lives in a
+  // stub directory at <workspace>/plugins/<manifest-name>/.
+  // readDefaultPluginManifests returns in repo array (registration) order.
+  const defaultPlugins: AllPluginInfo[] = readDefaultPluginManifests().map(
+    (manifest) => {
+      const target = join(pluginsDir, manifest.name);
+      const disabled = existsSync(join(target, ".disabled"));
+      return {
+        name: manifest.name,
+        target,
+        packageJson: {
+          name: manifest.name,
+          version: manifest.version,
+        },
+        issues: [],
+        source: "default" as const,
+        disabled,
+      };
+    },
+  );
+
+  // Sort: enabled user (install date), disabled user (install date),
+  // enabled default (repo order), disabled default (repo order).
+  const enabledUser = userPlugins.filter((p) => !p.disabled);
+  const disabledUser = userPlugins.filter((p) => p.disabled);
+  const enabledDefault = defaultPlugins.filter((p) => !p.disabled);
+  const disabledDefault = defaultPlugins.filter((p) => p.disabled);
+
+  enabledUser.sort((a, b) => getPluginInstallDate(a) - getPluginInstallDate(b));
+  disabledUser.sort(
+    (a, b) => getPluginInstallDate(a) - getPluginInstallDate(b),
+  );
+  // enabledDefault and disabledDefault keep repo array order (no sort).
+
+  return [...enabledUser, ...disabledUser, ...enabledDefault, ...disabledDefault];
+}
+
+interface DefaultPluginManifest {
+  readonly name: string;
+  readonly version?: string;
+}
+
+/**
+ * Read first-party default plugin manifests from the filesystem. Each
+ * subdirectory under {@link DEFAULT_PLUGINS_DIR} that has a `package.json`
+ * with a `name` field is included. This avoids importing `defaults/index.ts`
+ * (which would pull in hook/tool implementations and create circular
+ * dependencies in test environments).
+ */
+function readDefaultPluginManifests(): readonly DefaultPluginManifest[] {
+  if (!existsSync(DEFAULT_PLUGINS_DIR)) return [];
+
+  const entries = readdirSync(DEFAULT_PLUGINS_DIR, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    .sort();
+
+  const manifests: DefaultPluginManifest[] = [];
+  for (const name of entries) {
+    const pkgJsonPath = join(DEFAULT_PLUGINS_DIR, name, "package.json");
+    if (!existsSync(pkgJsonPath)) continue;
+    try {
+      const raw = readFileSync(pkgJsonPath, "utf8");
+      const parsed = JSON.parse(raw) as Record<string, unknown>;
+      if (typeof parsed.name === "string") {
+        manifests.push({
+          name: parsed.name,
+          version:
+            typeof parsed.version === "string" ? parsed.version : undefined,
+        });
+      }
+    } catch {
+      // Skip malformed entries — lenient like listInstalledPlugins.
+    }
+  }
+  return manifests;
+}
+
+/**
+ * Resolve the install date for a user plugin directory, in epoch ms.
+ * Reads `install-meta.json`'s `installedAt` field first, falling back to
+ * the directory's birthtime. Mirrors the logic in mtime-cache's
+ * `getInstallDate` so the sort order matches hook/tool resolution order.
+ */
+function getPluginInstallDate(plugin: AllPluginInfo): number {
+  const metaPath = join(plugin.target, "install-meta.json");
+  try {
+    if (existsSync(metaPath)) {
+      const raw = JSON.parse(readFileSync(metaPath, "utf8")) as Record<string, unknown>;
+      if (typeof raw.installedAt === "string") {
+        const ms = Date.parse(raw.installedAt);
+        if (Number.isFinite(ms)) return ms;
+      }
+    }
+  } catch {
+    // Fall through to birthtime.
+  }
+  try {
+    return statSync(plugin.target).birthtimeMs;
+  } catch {
+    return 0;
+  }
+}

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)
 // ---------------------------------------------------------------------------

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

@@ -0,0 +1,257 @@
+/**
+ * Reconstruct the history of marketplace pins for a single plugin.
+ *
+ * The curated `plugins/marketplace.json` manifest (see {@link ./plugin-marketplace})
+ * records only the *current* pin for each plugin — there is no stored version
+ * list. But the manifest is a file in a Git repo, and every time a curator bumps
+ * a plugin's pin, that is a commit to the manifest. So the history of reviewed
+ * pins already exists as the commit history of that one file: this module walks
+ * it (newest → oldest) via the GitHub API and reports the distinct pins a plugin
+ * has been promoted to over time, each tagged with the marketplace commit an
+ * install can reproduce it from.
+ *
+ * Why this is the safe source for "install an older version": every commit on
+ * the default branch was reviewed and merged, so a pin drawn from this history
+ * is a reviewed, known-good revision — unlike an arbitrary caller-supplied ref,
+ * which the install route deliberately refuses. Resolving an older pin to the
+ * marketplace commit that introduced it (rather than the plugin SHA directly)
+ * also means the install reads that era's manifest, so the curated adapter stub
+ * matches the pin and the historical version reproduces coherently.
+ *
+ * Designed for direct programmatic use with an injected `fetch`, mirroring the
+ * sibling plugin libraries.
+ */
+
+import { type FetchLike, sanitizePluginName } from "./install-from-github.js";
+import {
+  fetchMarketplaceEntries,
+  MARKETPLACE_MANIFEST_LOCATION,
+} from "./plugin-marketplace.js";
+
+/** Default number of distinct historical pins surfaced by `plugins versions`. */
+export const DEFAULT_PIN_HISTORY_LIMIT = 5;
+
+/**
+ * Cap on how many manifest-touching commits are inspected in one walk. Bounds
+ * the GitHub API cost: a plugin whose pin changes rarely could otherwise force
+ * a fetch of the manifest at every commit that touched it for *any* plugin.
+ * Well above {@link DEFAULT_PIN_HISTORY_LIMIT} so the default listing is
+ * complete in all but pathological histories.
+ */
+const MAX_MARKETPLACE_COMMITS_SCANNED = 100;
+
+/** A single point in a plugin's marketplace-pin history. */
+export interface PluginPinHistoryEntry {
+  /** Plugin commit SHA pinned at this point in history. */
+  readonly pin: string;
+  /**
+   * Marketplace-manifest commit to install this pin from — the newest commit
+   * that carries it. Installing with this as the marketplace ref reproduces the
+   * pin together with the curated adapter stub of the same era.
+   */
+  readonly marketplaceCommit: string;
+  /**
+   * ISO-8601 committer date (UTC) of {@link PluginPinHistoryEntry.marketplaceCommit},
+   * i.e. when this pin was promoted; `null` when the date could not be read.
+   */
+  readonly promotedAt: string | null;
+  /** True for the pin currently active on the default branch. */
+  readonly current: boolean;
+}
+
+/** Options controlling the pin-history walk. */
+export interface ListPinHistoryOptions {
+  /** Max distinct pins to return (newest first). Defaults to {@link DEFAULT_PIN_HISTORY_LIMIT}. */
+  readonly limit?: number;
+  /** Marketplace branch to read history from. Defaults to `main`. */
+  readonly ref?: string;
+}
+
+/** Dependencies injected by the caller. */
+export interface ListPinHistoryDeps {
+  /** HTTP client. Production callers pass `globalThis.fetch.bind(globalThis)`. */
+  readonly fetch: FetchLike;
+}
+
+/** Shape of a commit entry from the GitHub commits API. */
+interface GitHubCommitListEntry {
+  readonly sha: string;
+  readonly commit: {
+    readonly committer?: { readonly date?: string } | null;
+  } | null;
+}
+
+/** A manifest-touching commit and its committer date. */
+interface ManifestCommit {
+  readonly sha: string;
+  readonly date: string | null;
+}
+
+/** The pin-history walk could not read the marketplace commit list. */
+export class PluginPinHistoryError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "PluginPinHistoryError";
+  }
+}
+
+/**
+ * List the commits that touched the marketplace manifest on `ref`, newest
+ * first, capped at {@link MAX_MARKETPLACE_COMMITS_SCANNED}. A 404 (the file
+ * never existed at this ref) yields an empty list.
+ */
+async function listManifestCommits(
+  ref: string,
+  fetchFn: FetchLike,
+): Promise<ManifestCommit[]> {
+  const { owner, repo, path } = MARKETPLACE_MANIFEST_LOCATION;
+  const url =
+    `https://api.github.com/repos/${owner}/${repo}/commits` +
+    `?path=${encodeURIComponent(path)}` +
+    `&sha=${encodeURIComponent(ref)}` +
+    `&per_page=${MAX_MARKETPLACE_COMMITS_SCANNED}`;
+
+  const res = await fetchFn(url, {
+    headers: {
+      Accept: "application/vnd.github+json",
+      "User-Agent": "vellum-assistant-cli",
+    },
+  });
+  if (res.status === 404) return [];
+  if (!res.ok) {
+    throw new PluginPinHistoryError(
+      `Marketplace commit history fetch failed for ${path} @ ${ref}: HTTP ${res.status}`,
+    );
+  }
+
+  let body: unknown;
+  try {
+    body = JSON.parse(await res.text());
+  } catch (err) {
+    throw new PluginPinHistoryError(
+      `Marketplace commit history is not valid JSON: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  if (!Array.isArray(body)) {
+    throw new PluginPinHistoryError(
+      "Marketplace commit history response was not an array",
+    );
+  }
+
+  const commits: ManifestCommit[] = [];
+  for (const item of body as GitHubCommitListEntry[]) {
+    if (typeof item?.sha !== "string") continue;
+    const rawDate = item.commit?.committer?.date;
+    commits.push({
+      sha: item.sha,
+      date: typeof rawDate === "string" ? rawDate : null,
+    });
+  }
+  return commits;
+}
+
+/**
+ * Resolve the plugin's pinned SHA in the manifest at a specific marketplace
+ * commit, or `null` when no entry claims the name at that revision.
+ */
+async function pinAtCommit(
+  name: string,
+  marketplaceCommit: string,
+  fetchFn: FetchLike,
+): Promise<string | null> {
+  const entries = await fetchMarketplaceEntries(
+    { fetch: fetchFn },
+    { ref: marketplaceCommit },
+  );
+  return entries.find((e) => e.name === name)?.source.ref ?? null;
+}
+
+/**
+ * Walk a plugin's distinct marketplace pins, newest first. Each pin is yielded
+ * once, tagged with the newest marketplace commit carrying it. Revisions where
+ * the plugin is absent from the manifest are skipped (a gap, not a pin). The
+ * `current` flag is set against the pin live on `ref` today.
+ *
+ * Bounded by {@link MAX_MARKETPLACE_COMMITS_SCANNED} commits scanned.
+ */
+async function* iteratePinHistory(
+  name: string,
+  ref: string,
+  fetchFn: FetchLike,
+): AsyncGenerator<PluginPinHistoryEntry> {
+  const commits = await listManifestCommits(ref, fetchFn);
+  if (commits.length === 0) return;
+
+  // The pin live on the branch today, used to flag the current entry. Reading
+  // it explicitly (rather than assuming the newest commit carries it) stays
+  // correct even if the plugin was just removed from the manifest at the tip.
+  const currentPin = await pinAtCommit(name, ref, fetchFn);
+
+  let lastPin: string | null = null;
+  for (const commit of commits) {
+    const pin = await pinAtCommit(name, commit.sha, fetchFn);
+    if (pin === null) continue;
+    if (pin === lastPin) continue;
+    lastPin = pin;
+    yield {
+      pin,
+      marketplaceCommit: commit.sha,
+      promotedAt: commit.date,
+      current: currentPin !== null && pin === currentPin,
+    };
+  }
+}
+
+/**
+ * List a plugin's distinct marketplace pins, newest first, capped at
+ * `limit` (default {@link DEFAULT_PIN_HISTORY_LIMIT}). The first entry is the
+ * current pin. An empty list means the plugin has no resolvable history at this
+ * ref (never in the manifest, or the manifest does not exist).
+ *
+ * Throws {@link PluginPinHistoryError} when the commit list cannot be read, and
+ * propagates a `MarketplaceFetchError` if a manifest revision fails to parse.
+ */
+export async function listPinHistory(
+  name: string,
+  deps: ListPinHistoryDeps,
+  opts: ListPinHistoryOptions = {},
+): Promise<PluginPinHistoryEntry[]> {
+  const sanitized = sanitizePluginName(name);
+  const ref = opts.ref ?? "main";
+  const limit = opts.limit ?? DEFAULT_PIN_HISTORY_LIMIT;
+
+  const out: PluginPinHistoryEntry[] = [];
+  for await (const entry of iteratePinHistory(sanitized, ref, deps.fetch)) {
+    out.push(entry);
+    if (out.length >= limit) break;
+  }
+  return out;
+}
+
+/**
+ * Resolve a plugin pin (a full commit SHA) to the marketplace commit it should
+ * be installed from, by searching the plugin's pin history. Returns `null` when
+ * the pin is not found in the scanned history — i.e. it is not a reviewed pin
+ * this plugin was ever promoted to (or it predates the scan window).
+ *
+ * Case-insensitive on the SHA, matching the rest of the install pipeline. The
+ * search walks the full scan window, not just the `limit` shown by
+ * {@link listPinHistory}, so a pin older than the default listing still
+ * resolves.
+ */
+export async function resolvePinToMarketplaceCommit(
+  name: string,
+  pin: string,
+  deps: ListPinHistoryDeps,
+  opts: { readonly ref?: string } = {},
+): Promise<PluginPinHistoryEntry | null> {
+  const sanitized = sanitizePluginName(name);
+  const ref = opts.ref ?? "main";
+  const target = pin.trim().toLowerCase();
+  if (target.length === 0) return null;
+
+  for await (const entry of iteratePinHistory(sanitized, ref, deps.fetch)) {
+    if (entry.pin.toLowerCase() === target) return entry;
+  }
+  return null;
+}

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

@@ -0,0 +1,146 @@
+/**
+ * Enable / disable plugins by creating or removing a `.disabled` sentinel
+ * file inside the plugin's workspace directory.
+ *
+ * The sentinel is read by the daemon at boot:
+ * - User plugins: {@link ../../plugins/mtime-cache.ts} skips any plugin
+ *   whose directory contains `.disabled`.
+ * - Default plugins: {@link ../../daemon/external-plugins-bootstrap.ts}
+ *   checks `<workspace>/plugins/<manifest-name>/.disabled` before init.
+ *
+ * For user plugins the directory already exists (it is the install target).
+ * For default plugins (which live in the source tree) the directory may not
+ * exist yet, so `disable` creates a stub directory and drops the sentinel
+ * inside it. `enable` removes the sentinel and cleans up the stub directory
+ * if it becomes empty (so the workspace stays tidy when the only thing in
+ * it was the sentinel).
+ */
+
+import { existsSync, mkdirSync, readdirSync, rmSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+
+import { getWorkspacePluginsDir } from "../../util/platform.js";
+
+const DISABLED_FILE = ".disabled";
+
+/**
+ * Plugin name pattern: single path segment, kebab-case alphanumerics.
+ * Rejects path traversal (`../`, slashes, null bytes) and any name that
+ * is not a flat directory entry. Same pattern as {@link sanitizePluginName}
+ * but does NOT reject the `default-` prefix, since enable/disable must
+ * accept default plugin names.
+ */
+const PLUGIN_NAME_RE = /^[a-z0-9][a-z0-9_-]*$/;
+
+/** The plugin is already in the requested state. */
+export class PluginAlreadyInStateException extends Error {
+  constructor(
+    public readonly name: string,
+    public readonly action: "enable" | "disable",
+  ) {
+    super(
+      `Plugin "${name}" is already ${action === "disable" ? "disabled" : "enabled"}.`,
+    );
+    this.name = "PluginAlreadyInStateException";
+  }
+}
+
+/** The plugin name contains invalid characters or path segments. */
+export class InvalidPluginNameError extends Error {
+  constructor(public readonly name: string) {
+    super(
+      `Invalid plugin name "${name}". Names must be kebab-case alphanumerics (a-z, 0-9, -, _).`,
+    );
+    this.name = "InvalidPluginNameError";
+  }
+}
+
+/** No plugin directory found for the given name. */
+export class PluginDirectoryNotFoundError extends Error {
+  constructor(public readonly name: string) {
+    super(
+      `No plugin directory found for "${name}". Run \`assistant plugins list\` to see installed plugins. To disable a default plugin, prefix the name with "default-" (e.g. "default-advisor").`,
+    );
+    this.name = "PluginDirectoryNotFoundError";
+  }
+}
+
+export interface TogglePluginResult {
+  readonly name: string;
+  readonly action: "enable" | "disable";
+  readonly sentinelPath: string;
+}
+
+/**
+ * Validate a plugin name for enable/disable. Same kebab-case rule as
+ * {@link sanitizePluginName} but allows the `default-` prefix (needed for
+ * toggling default plugins).
+ */
+function validatePluginName(name: string): string {
+  const trimmed = name.trim();
+  if (!PLUGIN_NAME_RE.test(trimmed)) {
+    throw new InvalidPluginNameError(name);
+  }
+  return trimmed;
+}
+
+/**
+ * Disable a plugin by creating a `.disabled` sentinel file in its workspace
+ * directory. For default plugins (names starting with `default-`), creates a
+ * stub directory under `<workspace>/plugins/<name>/` if one does not exist.
+ * For user plugins, the directory must already exist.
+ */
+export function disablePlugin(name: string): TogglePluginResult {
+  const validated = validatePluginName(name);
+  const pluginsDir = getWorkspacePluginsDir();
+  const pluginDir = join(pluginsDir, validated);
+  const sentinelPath = join(pluginDir, DISABLED_FILE);
+
+  if (existsSync(sentinelPath)) {
+    throw new PluginAlreadyInStateException(validated, "disable");
+  }
+
+  if (!existsSync(pluginDir)) {
+    // Only create stub directories for default plugins. User plugins must
+    // already be installed — creating a directory for a name that has no
+    // plugin would be misleading.
+    if (!validated.startsWith("default-")) {
+      throw new PluginDirectoryNotFoundError(validated);
+    }
+    mkdirSync(pluginDir, { recursive: true });
+  }
+
+  // Write empty sentinel file — content is irrelevant, existence is the signal.
+  Bun.write(sentinelPath, "");
+  return { name: validated, action: "disable", sentinelPath };
+}
+
+/**
+ * Enable a plugin by removing the `.disabled` sentinel file from its
+ * workspace directory. If the directory was a stub created by `disable`
+ * (i.e. it contains nothing but the sentinel), it is removed entirely.
+ */
+export function enablePlugin(name: string): TogglePluginResult {
+  const validated = validatePluginName(name);
+  const pluginsDir = getWorkspacePluginsDir();
+  const pluginDir = join(pluginsDir, validated);
+  const sentinelPath = join(pluginDir, DISABLED_FILE);
+
+  if (!existsSync(sentinelPath)) {
+    throw new PluginAlreadyInStateException(validated, "enable");
+  }
+
+  unlinkSync(sentinelPath);
+
+  // Clean up the stub directory if it is now empty (default plugin case).
+  // A user plugin directory has package.json and source files, so it will
+  // never be empty after removing the sentinel.
+  if (existsSync(pluginDir)) {
+    const remaining = readdirSync(pluginDir);
+    if (remaining.length === 0) {
+      rmSync(pluginDir, { recursive: true });
+    }
+  }
+
+  return { name: validated, action: "enable", sentinelPath };
+}