@vellumai/assistant 0.8.1 → 0.8.2

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`;
+}

package/src/cli/lib/confirm-prompt.ts

@@ -0,0 +1,79 @@
+/**
+ * Interactive y/N prompt for destructive CLI subcommands. Uses
+ * `readline.createInterface` so EOF (Ctrl+D) is reported via the
+ * `close` event rather than hanging the process indefinitely.
+ *
+ * Returns one of:
+ *  - `"confirmed"`            user answered y/yes
+ *  - `"denied"`               user answered anything else (incl. EOF)
+ *  - `"non-interactive"`      stdin is not a TTY and the prompt was
+ *                             refused before any read happened
+ *
+ * Callers decide what each outcome means for `process.exitCode`. The
+ * convention used by `assistant plugins uninstall` is:
+ *   confirmed       → proceed
+ *   denied          → print "cancelled.", exit 0
+ *   non-interactive → exit 1 (script must pass `--force`)
+ */
+
+import readline from "node:readline";
+
+export type ConfirmResult = "confirmed" | "denied" | "non-interactive";
+
+export interface ConfirmPromptOptions {
+  /** The line written to stdout before reading. Should end with a space. */
+  question: string;
+  /** Whether stdin is attached to a TTY. Inject for testability. */
+  isTTY: boolean;
+  /**
+   * Message written to stderr when stdin is not a TTY. The caller chooses
+   * the wording so it can name the subject (plugin, file, command, etc.).
+   */
+  refuseNonInteractiveMessage: string;
+  /** Stream to read the answer from. Defaults to `process.stdin`. */
+  stdin?: NodeJS.ReadableStream;
+  /** Stream to write the prompt to. Defaults to `process.stdout`. */
+  stdout?: NodeJS.WritableStream;
+  /** Stream for the non-interactive refusal. Defaults to `process.stderr`. */
+  stderr?: NodeJS.WritableStream;
+}
+
+/**
+ * Pattern matched against the trimmed user response to decide
+ * confirmation. Case-insensitive. Anything else (including the empty
+ * string surfaced on EOF) is treated as denial — never trust silence
+ * to mean yes on a destructive prompt.
+ */
+const CONFIRM_PATTERN = /^(y|yes)$/i;
+
+export async function confirmPrompt(
+  opts: ConfirmPromptOptions,
+): Promise<ConfirmResult> {
+  const stderr = opts.stderr ?? process.stderr;
+
+  if (!opts.isTTY) {
+    stderr.write(`${opts.refuseNonInteractiveMessage}\n`);
+    return "non-interactive";
+  }
+
+  const rl = readline.createInterface({
+    input: opts.stdin ?? process.stdin,
+    output: opts.stdout ?? process.stdout,
+    terminal: false,
+  });
+
+  const answer = await new Promise<string>((resolve) => {
+    let settled = false;
+    const settle = (value: string) => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
+    rl.question(opts.question, (line) => settle(line));
+    rl.on("close", () => settle(""));
+  });
+
+  rl.close();
+
+  return CONFIRM_PATTERN.test(answer.trim()) ? "confirmed" : "denied";
+}

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

@@ -0,0 +1,304 @@
+/**
+ * Install an external plugin by name from the canonical GitHub source.
+ *
+ * The plugin source convention is fixed at
+ * `vellum-ai/vellum-assistant/experimental/plugins/<name>/` on the configured
+ * git ref. The {@link installPlugin} entry point fetches the directory tree
+ * via the GitHub Contents API and materializes it into
+ * `<workspacePluginsDir>/<name>/` so the daemon discovers it on next start.
+ *
+ * Designed for direct programmatic use. The CLI command
+ * `assistant plugins install <name>` is a thin wrapper that supplies
+ * production deps (`globalThis.fetch`, the live workspace directory) and
+ * formats the result for the terminal; downstream callers may supply their
+ * own `fetch` (e.g. an authenticated client, a retry-decorated client, or
+ * a test fixture) and an override workspace directory.
+ */
+
+import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { getWorkspacePluginsDir } from "../../util/platform.js";
+
+const PLUGIN_SOURCE_OWNER = "vellum-ai";
+const PLUGIN_SOURCE_REPO = "vellum-assistant";
+const PLUGIN_SOURCE_PATH_PREFIX = "experimental/plugins";
+/** Default git ref to fetch from when callers don't override. */
+export const DEFAULT_PLUGIN_REF = "main";
+
+/** Entry shape returned by the GitHub Contents API for a directory listing. */
+interface GitHubContentEntry {
+  readonly name: string;
+  readonly path: string;
+  readonly type: "file" | "dir" | "symlink" | "submodule";
+  readonly size: number;
+  readonly download_url: string | null;
+}
+
+/**
+ * Minimal `fetch` shape used by this module.
+ *
+ * Narrower than `typeof fetch` because Bun's `fetch` carries a `preconnect`
+ * static that this module does not need — pinning to the wider type would
+ * force every caller to construct a fully-featured Bun fetch.
+ */
+export type FetchLike = (
+  input: RequestInfo | URL,
+  init?: RequestInit,
+) => Promise<Response>;
+
+/** Options that control which plugin to install and how. */
+export interface InstallPluginOptions {
+  readonly name: string;
+  /** Overwrite an existing install in place. The previous content is
+   *  preserved on disk until the fetch succeeds. */
+  readonly force?: boolean;
+  /** Git ref (branch, tag, SHA) to fetch from. Defaults to {@link DEFAULT_PLUGIN_REF}. */
+  readonly ref?: string;
+}
+
+/** Dependencies injected by the caller. */
+export interface InstallPluginDeps {
+  /** HTTP client. Production callers pass `globalThis.fetch.bind(globalThis)`. */
+  readonly fetch: FetchLike;
+  /** Override the workspace plugins directory. Falls back to {@link getWorkspacePluginsDir}. */
+  readonly workspacePluginsDir?: string;
+}
+
+/** Successful install result. */
+export interface InstallPluginResult {
+  readonly name: string;
+  /** Absolute path the plugin was materialized into. */
+  readonly target: string;
+  readonly fileCount: number;
+  readonly ref: string;
+}
+
+/** Plugin name failed sanitization. */
+export class InvalidPluginNameError extends Error {
+  constructor(name: string) {
+    super(`Invalid plugin name "${name}". Names must match /^[a-z0-9][a-z0-9_-]*$/.`);
+    this.name = "InvalidPluginNameError";
+  }
+}
+
+/** A plugin with the same name is already installed and `--force` was not passed. */
+export class PluginAlreadyInstalledError extends Error {
+  constructor(
+    readonly pluginName: string,
+    readonly target: string,
+  ) {
+    super(`Plugin "${pluginName}" is already installed at ${target}.`);
+    this.name = "PluginAlreadyInstalledError";
+  }
+}
+
+/** GitHub responded that the plugin directory does not exist at this ref. */
+export class PluginNotFoundError extends Error {
+  constructor(
+    readonly pluginName: string,
+    readonly ref: string,
+  ) {
+    const sourcePath = `${PLUGIN_SOURCE_OWNER}/${PLUGIN_SOURCE_REPO}/${PLUGIN_SOURCE_PATH_PREFIX}/${pluginName}`;
+    super(`Plugin "${pluginName}" not found at ${sourcePath} (ref ${ref}).`);
+    this.name = "PluginNotFoundError";
+  }
+}
+
+/**
+ * Reject plugin names that could escape the canonical source path or the
+ * install target. The source convention is a flat namespace under
+ * `experimental/plugins/`, so a legitimate name is a single path segment
+ * built from kebab-case alphanumerics.
+ *
+ * Exported so callers (e.g. the CLI input prompt) can validate up front
+ * before invoking {@link installPlugin}.
+ */
+export function sanitizePluginName(name: string): string {
+  const trimmed = name.trim();
+  if (!/^[a-z0-9][a-z0-9_-]*$/.test(trimmed)) {
+    throw new InvalidPluginNameError(name);
+  }
+  return trimmed;
+}
+
+/**
+ * Reject path components that could escape the staging or install target via
+ * `path.join` resolution of `..`, or that contain platform path separators.
+ * Used to filter entries returned by the GitHub Contents API before they
+ * become filesystem paths.
+ */
+function assertSafeFilename(label: string, candidate: string): void {
+  if (
+    candidate.length === 0 ||
+    candidate === "." ||
+    candidate === ".." ||
+    candidate.includes("/") ||
+    candidate.includes("\\") ||
+    // Reject any name containing a null byte (filesystem terminator) or that
+    // resolves to a parent-segment when split — paranoid layer in case
+    // GitHub ever serves a name like "foo/../bar".
+    candidate.includes("\0") ||
+    candidate.split(/[/\\]/).some((seg) => seg === "..")
+  ) {
+    throw new Error(`Unsafe ${label} from GitHub response: ${JSON.stringify(candidate)}`);
+  }
+}
+
+/**
+ * Materialize a plugin tree into the local workspace.
+ *
+ * Staging: the new tree is written into a sibling staging directory and only
+ * swapped into place once the fetch completes. A transient failure (5xx,
+ * mid-stream 404, network loss) therefore leaves the previously installed
+ * copy untouched even when the caller passed `force: true`.
+ */
+export async function installPlugin(
+  opts: InstallPluginOptions,
+  deps: InstallPluginDeps,
+): Promise<InstallPluginResult> {
+  const name = sanitizePluginName(opts.name);
+  const ref = opts.ref ?? DEFAULT_PLUGIN_REF;
+  const force = opts.force ?? false;
+
+  const pluginsDir = deps.workspacePluginsDir ?? getWorkspacePluginsDir();
+  const target = join(pluginsDir, name);
+
+  if (existsSync(target) && !force) {
+    throw new PluginAlreadyInstalledError(name, target);
+  }
+
+  // Stage into a sibling temp dir so an in-progress install never destroys
+  // the currently installed version. `process.pid` keeps concurrent installs
+  // of the same plugin from clobbering each other's staging.
+  const stagingDir = `${target}.installing.${process.pid}`;
+  if (existsSync(stagingDir)) {
+    rmSync(stagingDir, { recursive: true, force: true });
+  }
+  mkdirSync(stagingDir, { recursive: true });
+
+  let fileCount: number;
+  try {
+    fileCount = await copyDir(
+      `${PLUGIN_SOURCE_PATH_PREFIX}/${name}`,
+      ref,
+      stagingDir,
+      deps.fetch,
+    );
+  } catch (err) {
+    rmSync(stagingDir, { recursive: true, force: true });
+    throw err;
+  }
+
+  if (fileCount === 0) {
+    rmSync(stagingDir, { recursive: true, force: true });
+    throw new PluginNotFoundError(name, ref);
+  }
+
+  // Atomic-ish swap: rmSync + renameSync. On POSIX the rename itself is
+  // atomic, so the only window where the target is absent is between the
+  // rm and the rename — and at that point the staging dir is fully populated.
+  if (existsSync(target)) {
+    rmSync(target, { recursive: true, force: true });
+  }
+  renameSync(stagingDir, target);
+
+  return { name, target, fileCount, ref };
+}
+
+async function copyDir(
+  apiPath: string,
+  ref: string,
+  destDir: string,
+  fetchFn: FetchLike,
+): Promise<number> {
+  const entries = await listDir(apiPath, ref, fetchFn);
+  if (entries === null) return 0;
+
+  let count = 0;
+  for (const entry of entries) {
+    assertSafeFilename("entry name", entry.name);
+    if (entry.type === "dir") {
+      const subDest = join(destDir, entry.name);
+      mkdirSync(subDest, { recursive: true });
+      count += await copyDir(entry.path, ref, subDest, fetchFn);
+      continue;
+    }
+    if (entry.type === "file") {
+      await copyFile(entry, destDir, fetchFn);
+      count++;
+      continue;
+    }
+    // Skip symlink + submodule deliberately. The daemon-side loader does not
+    // follow either, so reproducing them in the install target adds risk
+    // without value.
+  }
+  return count;
+}
+
+async function listDir(
+  apiPath: string,
+  ref: string,
+  fetchFn: FetchLike,
+): Promise<readonly GitHubContentEntry[] | null> {
+  const url =
+    `https://api.github.com/repos/${PLUGIN_SOURCE_OWNER}/${PLUGIN_SOURCE_REPO}` +
+    `/contents/${encodeURIComponent(apiPath).replaceAll("%2F", "/")}?ref=${encodeURIComponent(ref)}`;
+
+  const res = await githubFetch(url, "application/vnd.github+json", fetchFn);
+  if (res.status === 404) return null;
+  if (!res.ok) {
+    throw new Error(
+      `GitHub contents listing failed for ${apiPath} @ ${ref}: HTTP ${res.status}`,
+    );
+  }
+
+  const body = (await res.json()) as unknown;
+  if (!Array.isArray(body)) {
+    // A non-array body for a /contents/<dir> path means the path is a
+    // file, not a directory — i.e. the plugin name resolved to a single
+    // file rather than a plugin directory. Treat as not-a-plugin.
+    return null;
+  }
+  return body as readonly GitHubContentEntry[];
+}
+
+async function copyFile(
+  entry: GitHubContentEntry,
+  destDir: string,
+  fetchFn: FetchLike,
+): Promise<void> {
+  if (!entry.download_url) {
+    throw new Error(`GitHub contents entry has no download_url: ${entry.path}`);
+  }
+  const res = await githubFetch(entry.download_url, "application/octet-stream", fetchFn);
+  if (!res.ok) {
+    throw new Error(`Download failed for ${entry.path}: HTTP ${res.status}`);
+  }
+  const buf = Buffer.from(await res.arrayBuffer());
+  // entry.name was already validated by the caller; assert again as a
+  // belt-and-braces guard so copyFile is safe to call from future paths.
+  assertSafeFilename("file entry name", entry.name);
+  const dest = join(destDir, entry.name);
+  mkdirSync(dirname(dest), { recursive: true });
+  writeFileSync(dest, buf);
+}
+
+/**
+ * Wraps `fetchFn` with the headers we want to send to GitHub for every
+ * request. Honors `GITHUB_TOKEN` when present so users who hit the
+ * unauthenticated rate limit can opt into a higher cap.
+ */
+async function githubFetch(
+  url: string,
+  accept: string,
+  fetchFn: FetchLike,
+): Promise<Response> {
+  const headers: Record<string, string> = {
+    Accept: accept,
+    "User-Agent": "vellum-assistant-cli",
+  };
+  const token = process.env.GITHUB_TOKEN?.trim();
+  if (token) headers.Authorization = `Bearer ${token}`;
+  return fetchFn(url, { headers });
+}