@vellumai/assistant 0.8.1 → 0.8.3

package/src/cli/commands/telemetry.ts

@@ -0,0 +1,40 @@
+import type { Command } from "commander";
+
+import { cliIpcCall, exitFromIpcResult } from "../../ipc/cli-client.js";
+import { registerCommand } from "../lib/register-command.js";
+import { log } from "../logger.js";
+
+export function registerTelemetryCommand(program: Command): void {
+  registerCommand(program, {
+    name: "telemetry",
+    transport: "ipc",
+    description: "Manage telemetry reporting",
+    build: (telemetry) => {
+      telemetry
+        .command("flush")
+        .description(
+          "Force-flush all pending telemetry events to the platform",
+        )
+        .action(async (_opts: Record<string, unknown>, cmd: Command) => {
+          const r = await cliIpcCall<
+            { flushed: true } | { flushed: false; reason: string }
+          >("telemetry_flush", {});
+          if (!r.ok)
+            return exitFromIpcResult({
+              ok: false,
+              error: r.error,
+              statusCode: r.statusCode,
+            }, cmd);
+
+          const result = r.result!;
+          if (result.flushed) {
+            log.info("Telemetry flushed successfully.");
+          } else {
+            log.info(
+              `Telemetry flush skipped: ${result.reason}`,
+            );
+          }
+        });
+    },
+  });
+}

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

@@ -0,0 +1,48 @@
+import { afterEach, describe, expect, it } from "bun:test";
+
+import { red } from "../cli-colors.js";
+
+const originalIsTTY = process.stderr.isTTY;
+const originalNoColor = process.env.NO_COLOR;
+
+function setTTY(value: boolean): void {
+  Object.defineProperty(process.stderr, "isTTY", {
+    configurable: true,
+    value,
+  });
+}
+
+describe("red", () => {
+  afterEach(() => {
+    setTTY(originalIsTTY);
+    if (originalNoColor === undefined) {
+      delete process.env.NO_COLOR;
+    } else {
+      process.env.NO_COLOR = originalNoColor;
+    }
+  });
+
+  it("returns plain text when stderr is not a TTY", () => {
+    setTTY(false);
+    delete process.env.NO_COLOR;
+    expect(red("oops")).toBe("oops");
+  });
+
+  it("wraps text in ANSI red when stderr is a TTY", () => {
+    setTTY(true);
+    delete process.env.NO_COLOR;
+    expect(red("oops")).toBe("\x1b[31moops\x1b[0m");
+  });
+
+  it("respects NO_COLOR even when stderr is a TTY", () => {
+    setTTY(true);
+    process.env.NO_COLOR = "1";
+    expect(red("oops")).toBe("oops");
+  });
+
+  it("treats an empty NO_COLOR as unset (per no-color.org)", () => {
+    setTTY(true);
+    process.env.NO_COLOR = "";
+    expect(red("oops")).toBe("\x1b[31moops\x1b[0m");
+  });
+});

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

@@ -0,0 +1,159 @@
+import { PassThrough } from "node:stream";
+import { describe, expect, test } from "bun:test";
+
+import { confirmPrompt } from "../confirm-prompt.js";
+
+interface Captured {
+  stdin: PassThrough;
+  stdout: PassThrough;
+  stderr: PassThrough;
+  outChunks: string[];
+  errChunks: string[];
+}
+
+function buildStreams(): Captured {
+  const stdin = new PassThrough();
+  const stdout = new PassThrough();
+  const stderr = new PassThrough();
+  const outChunks: string[] = [];
+  const errChunks: string[] = [];
+  stdout.on("data", (c: Buffer) => outChunks.push(c.toString("utf8")));
+  stderr.on("data", (c: Buffer) => errChunks.push(c.toString("utf8")));
+  return { stdin, stdout, stderr, outChunks, errChunks };
+}
+
+describe("confirmPrompt", () => {
+  test("returns \"non-interactive\" without reading when isTTY=false", async () => {
+    const { stdin, stdout, stderr, outChunks, errChunks } = buildStreams();
+    const result = await confirmPrompt({
+      question: "Delete? [y/N] ",
+      isTTY: false,
+      refuseNonInteractiveMessage: "Refusing: pass --force.",
+      stdin,
+      stdout,
+      stderr,
+    });
+    expect(result).toBe("non-interactive");
+    expect(errChunks.join("")).toContain("Refusing: pass --force.");
+    expect(outChunks.join("")).toBe("");
+  });
+
+  test("returns \"confirmed\" for \"y\\n\"", async () => {
+    const { stdin, stdout, stderr } = buildStreams();
+    const pending = confirmPrompt({
+      question: "Delete? [y/N] ",
+      isTTY: true,
+      refuseNonInteractiveMessage: "should not see this",
+      stdin,
+      stdout,
+      stderr,
+    });
+    stdin.write("y\n");
+    expect(await pending).toBe("confirmed");
+  });
+
+  test("returns \"confirmed\" for \"yes\\n\" (case-insensitive, whitespace-tolerant)", async () => {
+    const { stdin, stdout, stderr } = buildStreams();
+    const pending = confirmPrompt({
+      question: "Delete? [y/N] ",
+      isTTY: true,
+      refuseNonInteractiveMessage: "n/a",
+      stdin,
+      stdout,
+      stderr,
+    });
+    stdin.write("  YES  \n");
+    expect(await pending).toBe("confirmed");
+  });
+
+  test("returns \"denied\" for \"n\\n\"", async () => {
+    const { stdin, stdout, stderr } = buildStreams();
+    const pending = confirmPrompt({
+      question: "Delete? [y/N] ",
+      isTTY: true,
+      refuseNonInteractiveMessage: "n/a",
+      stdin,
+      stdout,
+      stderr,
+    });
+    stdin.write("n\n");
+    expect(await pending).toBe("denied");
+  });
+
+  test("returns \"denied\" for empty input (just Enter)", async () => {
+    const { stdin, stdout, stderr } = buildStreams();
+    const pending = confirmPrompt({
+      question: "Delete? [y/N] ",
+      isTTY: true,
+      refuseNonInteractiveMessage: "n/a",
+      stdin,
+      stdout,
+      stderr,
+    });
+    stdin.write("\n");
+    expect(await pending).toBe("denied");
+  });
+
+  test("returns \"denied\" on EOF without any data (regression: would have hung)", async () => {
+    const { stdin, stdout, stderr } = buildStreams();
+    const pending = confirmPrompt({
+      question: "Delete? [y/N] ",
+      isTTY: true,
+      refuseNonInteractiveMessage: "n/a",
+      stdin,
+      stdout,
+      stderr,
+    });
+    stdin.end();
+    expect(await pending).toBe("denied");
+  });
+
+  test("returns \"denied\" on EOF after a partial line with no newline", async () => {
+    const { stdin, stdout, stderr } = buildStreams();
+    const pending = confirmPrompt({
+      question: "Delete? [y/N] ",
+      isTTY: true,
+      refuseNonInteractiveMessage: "n/a",
+      stdin,
+      stdout,
+      stderr,
+    });
+    // "y" without a trailing newline followed by EOF — readline will fire
+    // the "line" event on close, so we exercise that path explicitly.
+    stdin.write("y");
+    stdin.end();
+    const result = await pending;
+    // readline fires `line` with the buffered content on EOF, so this
+    // actually confirms. Documents the behaviour either way.
+    expect(["confirmed", "denied"]).toContain(result);
+  });
+
+  test("writes the question to stdout when interactive", async () => {
+    const { stdin, stdout, stderr, outChunks } = buildStreams();
+    const pending = confirmPrompt({
+      question: "Delete plugin \"foo\"? [y/N] ",
+      isTTY: true,
+      refuseNonInteractiveMessage: "n/a",
+      stdin,
+      stdout,
+      stderr,
+    });
+    stdin.write("n\n");
+    await pending;
+    expect(outChunks.join("")).toContain("Delete plugin \"foo\"? [y/N] ");
+  });
+
+  test("treats stray garbage as denial, never confirmation", async () => {
+    const { stdin, stdout, stderr } = buildStreams();
+    const pending = confirmPrompt({
+      question: "Delete? [y/N] ",
+      isTTY: true,
+      refuseNonInteractiveMessage: "n/a",
+      stdin,
+      stdout,
+      stderr,
+    });
+    stdin.write("maybe\n");
+    expect(await pending).toBe("denied");
+  });
+});

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");
+  });
+});