@vellumai/assistant 0.10.1 → 0.10.2-dev.202606241651.2d2b40d

package/src/cli/commands/memory/__tests__/worker.test.ts

@@ -0,0 +1,302 @@
+/**
+ * Tests for the `assistant memory worker` CLI subgroup.
+ *
+ * Validates:
+ *   - Subcommand registration (start, stop, status) under `memory worker`.
+ *   - `status` reports running/not_running via PID-file liveness.
+ *   - `stop` sends SIGTERM to a live worker and errors when none is running.
+ *   - `start` refuses to spawn when a worker is already running, and reports
+ *     the PID once the spawned process writes its PID file.
+ */
+
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+
+import { Command } from "commander";
+
+// ---------------------------------------------------------------------------
+// Mock state
+// ---------------------------------------------------------------------------
+
+let tmpDir: string;
+let pidPath: string;
+let logOutput: string[] = [];
+
+/** Records (pid, signal) pairs passed to the mocked process.kill. */
+let killCalls: Array<{ pid: number; signal: string | number }> = [];
+
+// ---------------------------------------------------------------------------
+// Mocks
+// ---------------------------------------------------------------------------
+
+mock.module("../../../../util/platform.js", () => ({
+  getMemoryWorkerPidPath: () => pidPath,
+}));
+
+const capture = (...args: unknown[]) => {
+  logOutput.push(args.map(String).join(" "));
+};
+const fakeLogger = {
+  info: capture,
+  warn: capture,
+  error: capture,
+  debug: () => {},
+};
+mock.module("../../../../util/logger.js", () => ({
+  getLogger: () => fakeLogger,
+  getCliLogger: () => fakeLogger,
+}));
+
+// ---------------------------------------------------------------------------
+// Import module under test (after mocks)
+// ---------------------------------------------------------------------------
+
+const { registerMemoryWorkerCommand } = await import("../worker.js");
+
+// ---------------------------------------------------------------------------
+// Test helpers
+// ---------------------------------------------------------------------------
+
+function buildProgram(): Command {
+  const program = new Command();
+  program.exitOverride();
+  program.configureOutput({
+    writeErr: () => {},
+    writeOut: () => {},
+  });
+  const memory = program.command("memory");
+  registerMemoryWorkerCommand(memory);
+  return program;
+}
+
+async function runCommand(
+  args: string[],
+): Promise<{ stdout: string; exitCode: number }> {
+  const originalStdoutWrite = process.stdout.write.bind(process.stdout);
+  const originalStderrWrite = process.stderr.write.bind(process.stderr);
+  const stdoutChunks: string[] = [];
+
+  process.stdout.write = ((chunk: unknown) => {
+    stdoutChunks.push(typeof chunk === "string" ? chunk : String(chunk));
+    return true;
+  }) as typeof process.stdout.write;
+
+  process.stderr.write = (() => true) as typeof process.stderr.write;
+
+  process.exitCode = 0;
+
+  try {
+    const program = buildProgram();
+    await program.parseAsync(["node", "assistant", ...args]);
+  } catch {
+    if (process.exitCode === 0) process.exitCode = 1;
+  } finally {
+    process.stdout.write = originalStdoutWrite;
+    process.stderr.write = originalStderrWrite;
+  }
+
+  const exitCode = process.exitCode ?? 0;
+  process.exitCode = 0;
+
+  return { exitCode, stdout: stdoutChunks.join("") };
+}
+
+/**
+ * Replace process.kill with a recording stub. `signal 0` is the liveness
+ * probe: it resolves for `livePids` and throws ESRCH otherwise. Other signals
+ * are recorded and no-oped so the test runner is never actually signalled.
+ */
+function stubProcessKill(livePids: Set<number>): () => void {
+  const original = process.kill.bind(process);
+  killCalls = [];
+  process.kill = ((pid: number, signal?: string | number) => {
+    const sig = signal ?? 0;
+    if (sig === 0) {
+      if (livePids.has(pid)) return true;
+      const err = new Error("kill ESRCH") as NodeJS.ErrnoException;
+      err.code = "ESRCH";
+      throw err;
+    }
+    killCalls.push({ pid, signal: sig });
+    return true;
+  }) as typeof process.kill;
+  return () => {
+    process.kill = original;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Setup
+// ---------------------------------------------------------------------------
+
+beforeEach(() => {
+  tmpDir = mkdtempSync(join(tmpdir(), "memory-worker-test-"));
+  pidPath = join(tmpDir, "memory-worker.pid");
+  logOutput = [];
+  killCalls = [];
+  process.exitCode = 0;
+});
+
+afterEach(() => {
+  rmSync(tmpDir, { recursive: true, force: true });
+});
+
+// ---------------------------------------------------------------------------
+// Subcommand registration
+// ---------------------------------------------------------------------------
+
+describe("subcommand registration", () => {
+  test("registers worker under memory with start/stop/status", () => {
+    const program = buildProgram();
+    const memory = program.commands.find((c) => c.name() === "memory");
+    expect(memory).toBeDefined();
+    const worker = memory!.commands.find((c) => c.name() === "worker");
+    expect(worker).toBeDefined();
+    const subcommandNames = worker!.commands.map((c) => c.name()).sort();
+    expect(subcommandNames).toEqual(["start", "status", "stop"]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// status
+// ---------------------------------------------------------------------------
+
+describe("memory worker status", () => {
+  test("reports not_running when no PID file exists", async () => {
+    const { exitCode, stdout } = await runCommand([
+      "memory",
+      "worker",
+      "status",
+      "--json",
+    ]);
+    expect(exitCode).toBe(0);
+    expect(JSON.parse(stdout)).toEqual({ status: "not_running" });
+  });
+
+  test("reports running when PID file points at a live process", async () => {
+    writeFileSync(pidPath, String(process.pid));
+    const restore = stubProcessKill(new Set([process.pid]));
+    try {
+      const { exitCode, stdout } = await runCommand([
+        "memory",
+        "worker",
+        "status",
+        "--json",
+      ]);
+      expect(exitCode).toBe(0);
+      expect(JSON.parse(stdout)).toEqual({
+        status: "running",
+        pid: process.pid,
+      });
+    } finally {
+      restore();
+    }
+  });
+
+  test("treats a stale PID file as not_running and cleans it up", async () => {
+    writeFileSync(pidPath, "999999");
+    const restore = stubProcessKill(new Set());
+    try {
+      const { exitCode, stdout } = await runCommand([
+        "memory",
+        "worker",
+        "status",
+        "--json",
+      ]);
+      expect(exitCode).toBe(0);
+      expect(JSON.parse(stdout)).toEqual({ status: "not_running" });
+      expect(existsSync(pidPath)).toBe(false);
+    } finally {
+      restore();
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// stop
+// ---------------------------------------------------------------------------
+
+describe("memory worker stop", () => {
+  test("errors with exit 1 when no worker is running", async () => {
+    const { exitCode, stdout } = await runCommand([
+      "memory",
+      "worker",
+      "stop",
+      "--json",
+    ]);
+    expect(exitCode).toBe(1);
+    expect(JSON.parse(stdout)).toMatchObject({ ok: false });
+  });
+
+  test("sends SIGTERM to a running worker", async () => {
+    writeFileSync(pidPath, String(process.pid));
+    const restore = stubProcessKill(new Set([process.pid]));
+    try {
+      const { exitCode, stdout } = await runCommand([
+        "memory",
+        "worker",
+        "stop",
+        "--json",
+      ]);
+      expect(exitCode).toBe(0);
+      expect(JSON.parse(stdout)).toEqual({ ok: true, pid: process.pid });
+      expect(killCalls).toContainEqual({
+        pid: process.pid,
+        signal: "SIGTERM",
+      });
+    } finally {
+      restore();
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// start
+// ---------------------------------------------------------------------------
+
+describe("memory worker start", () => {
+  test("refuses to start when a worker is already running", async () => {
+    writeFileSync(pidPath, String(process.pid));
+    const restore = stubProcessKill(new Set([process.pid]));
+    try {
+      const { exitCode, stdout } = await runCommand([
+        "memory",
+        "worker",
+        "start",
+        "--json",
+      ]);
+      expect(exitCode).toBe(1);
+      expect(JSON.parse(stdout)).toMatchObject({
+        ok: false,
+        pid: process.pid,
+      });
+    } finally {
+      restore();
+    }
+  });
+
+  test("spawns the worker and reports the PID it writes", async () => {
+    const restore = stubProcessKill(new Set());
+    const originalSpawn = Bun.spawn;
+    // Simulate the spawned worker writing its PID file on startup.
+    (Bun as { spawn: typeof Bun.spawn }).spawn = (() => {
+      writeFileSync(pidPath, "424242");
+      return { unref: () => {}, pid: 424242 };
+    }) as unknown as typeof Bun.spawn;
+    try {
+      const { exitCode, stdout } = await runCommand([
+        "memory",
+        "worker",
+        "start",
+        "--json",
+      ]);
+      expect(exitCode).toBe(0);
+      expect(JSON.parse(stdout)).toMatchObject({ ok: true, pid: 424242 });
+    } finally {
+      (Bun as { spawn: typeof Bun.spawn }).spawn = originalSpawn;
+      restore();
+    }
+  });
+});

package/src/cli/commands/memory/index.ts

@@ -4,6 +4,7 @@ import { registerCommand } from "../../lib/register-command.js";
 import { registerMemoryRetrospectiveCommand } from "./memory-retrospective.js";
 import { registerMemoryV2Command } from "./memory-v2.js";
 import { registerMemoryV3Command } from "./memory-v3.js";
+import { registerMemoryWorkerCommand } from "./worker.js";
 
 export function registerMemoryCommand(program: Command): void {
   registerCommand(program, {
@@ -27,6 +28,7 @@ Examples:
       registerMemoryV2Command(memory);
       registerMemoryV3Command(memory);
       registerMemoryRetrospectiveCommand(memory);
+      registerMemoryWorkerCommand(memory);
     },
   });
 }

package/src/cli/commands/memory/worker.ts

@@ -0,0 +1,175 @@
+/**
+ * `assistant memory worker` CLI subgroup.
+ *
+ * Manages the memory jobs worker as its own OS process — separate from the
+ * daemon's main event loop. This prevents long-running embedding jobs from
+ * blocking user-facing HTTP traffic.
+ *
+ * Subcommands:
+ *
+ *   - `start`  — spawn the worker process (detached, background).
+ *   - `stop`   — send SIGTERM to the running worker process.
+ *   - `status` — report whether the worker process is running.
+ *
+ * All three run directly in the CLI process (transport: "local") — no IPC
+ * round-trip to the daemon.
+ */
+
+import type { Command } from "commander";
+
+import {
+  probeMemoryWorker,
+  spawnMemoryWorkerProcess,
+} from "../../../memory/worker-control.js";
+import { getMemoryWorkerPidPath } from "../../../util/platform.js";
+import { registerCommand } from "../../lib/register-command.js";
+import { log } from "../../logger.js";
+import { shouldOutputJson, writeOutput } from "../../output.js";
+
+// ---------------------------------------------------------------------------
+// `start`
+// ---------------------------------------------------------------------------
+
+async function startWorker(
+  opts: { json?: boolean },
+  cmd: Command,
+): Promise<void> {
+  let result: { pid: number; alreadyRunning: boolean };
+  try {
+    result = await spawnMemoryWorkerProcess();
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (shouldOutputJson(cmd)) {
+      writeOutput(cmd, { ok: false, error: msg });
+    } else {
+      log.error(msg);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  if (result.alreadyRunning) {
+    const msg = `Memory worker is already running (PID ${result.pid})`;
+    if (shouldOutputJson(cmd)) {
+      writeOutput(cmd, { ok: false, error: msg, pid: result.pid });
+    } else {
+      log.error(msg);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  if (shouldOutputJson(cmd)) {
+    writeOutput(cmd, {
+      ok: true,
+      pid: result.pid,
+      pidPath: getMemoryWorkerPidPath(),
+    });
+  } else {
+    log.info(`Memory worker started (PID ${result.pid})`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// `stop`
+// ---------------------------------------------------------------------------
+
+function stopWorker(opts: { json?: boolean }, cmd: Command): void {
+  const current = probeMemoryWorker();
+  if (current.status !== "running" || current.pid == null) {
+    const msg = "Memory worker is not running";
+    if (shouldOutputJson(cmd)) {
+      writeOutput(cmd, { ok: false, error: msg });
+    } else {
+      log.error(msg);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  const pid = current.pid;
+  try {
+    process.kill(pid, "SIGTERM");
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (shouldOutputJson(cmd)) {
+      writeOutput(cmd, { ok: false, error: msg, pid });
+    } else {
+      log.error(`Failed to stop memory worker (PID ${pid}): ${msg}`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  if (shouldOutputJson(cmd)) {
+    writeOutput(cmd, { ok: true, pid });
+  } else {
+    log.info(`Memory worker stop signal sent (PID ${pid})`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// `status`
+// ---------------------------------------------------------------------------
+
+function statusWorker(opts: { json?: boolean }, cmd: Command): void {
+  const result = probeMemoryWorker();
+  if (shouldOutputJson(cmd)) {
+    writeOutput(cmd, result);
+  } else {
+    if (result.status === "running") {
+      log.info(`Memory worker is running (PID ${result.pid})`);
+    } else {
+      log.info("Memory worker is not running");
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+
+export function registerMemoryWorkerCommand(memory: Command): void {
+  registerCommand(memory, {
+    name: "worker",
+    transport: "local",
+    description: "Manage the memory jobs worker process (start/stop/status)",
+    build: (worker) => {
+      worker.addHelpText(
+        "after",
+        `
+The memory worker processes embedding, consolidation, and cleanup jobs in a
+separate OS process so they do not block the daemon's main event loop.
+
+Examples:
+  $ assistant memory worker start
+  $ assistant memory worker status
+  $ assistant memory worker stop`,
+      );
+
+      worker
+        .command("start")
+        .description("Start the memory worker as a background process")
+        .option("--json", "Emit raw JSON instead of a formatted summary")
+        .action(async (opts: { json?: boolean }, cmd: Command) => {
+          await startWorker(opts, cmd);
+        });
+
+      worker
+        .command("stop")
+        .description("Stop the running memory worker process")
+        .option("--json", "Emit raw JSON instead of a formatted summary")
+        .action((opts: { json?: boolean }, cmd: Command) => {
+          stopWorker(opts, cmd);
+        });
+
+      worker
+        .command("status")
+        .description("Check whether the memory worker process is running")
+        .option("--json", "Emit raw JSON instead of a formatted summary")
+        .action((opts: { json?: boolean }, cmd: Command) => {
+          statusWorker(opts, cmd);
+        });
+    },
+  });
+}

package/src/cli/commands/plugins.ts

@@ -29,7 +29,11 @@ import {
   PluginAlreadyInstalledError,
   PluginNotFoundError,
 } from "../lib/install-from-github.js";
-import { listInstalledPlugins } from "../lib/list-installed-plugins.js";
+import {
+  type AllPluginInfo,
+  listAllPlugins,
+  listInstalledPlugins,
+} from "../lib/list-installed-plugins.js";
 import type { FingerprintComparison } from "../lib/plugin-fingerprint.js";
 import {
   DEFAULT_PIN_HISTORY_LIMIT,
@@ -85,6 +89,8 @@ Examples:
   $ assistant plugins install example --pin <sha> --force
   $ assistant plugins list
   $ assistant plugins list --json
+  $ assistant plugins list --all
+  $ assistant plugins list --all --json
   $ assistant plugins inspect example
   $ assistant plugins inspect example --json
   $ assistant plugins diff example
@@ -239,9 +245,63 @@ Examples:
 
       plugins
         .command("list")
-        .description("List plugins installed under <workspaceDir>/plugins/")
+        .description(
+          "List plugins installed in your workspace.",
+        )
         .option("--json", "Emit machine-readable JSON instead of a table")
-        .action((opts: { json?: boolean }) => {
+        .option(
+          "--all",
+          "Include first-party default plugins and disabled plugins in the listing",
+        )
+        .action((opts: { json?: boolean; all?: boolean }) => {
+          if (opts.all) {
+            const all = listAllPlugins();
+
+            if (opts.json) {
+              process.stdout.write(JSON.stringify(all, null, 2) + "\n");
+              return;
+            }
+
+            if (all.length === 0) {
+              console.log("No plugins found.");
+              return;
+            }
+
+            const rows = all.map((p) => ({
+              name: p.name,
+              version: p.packageJson?.version ?? "—",
+              source: p.source,
+              status: formatAllPluginStatus(p),
+            }));
+            const nameW = Math.max(4, ...rows.map((r) => r.name.length));
+            const versionW = Math.max(7, ...rows.map((r) => r.version.length));
+            const sourceW = Math.max(6, ...rows.map((r) => r.source.length));
+            const pad = (s: string, w: number) =>
+              s + " ".repeat(w - s.length);
+            console.log(
+              `${pad("NAME", nameW)}  ${pad("VERSION", versionW)}  ${pad("SOURCE", sourceW)}  STATUS`,
+            );
+            for (const r of rows) {
+              console.log(
+                `${pad(r.name, nameW)}  ${pad(r.version, versionW)}  ${pad(r.source, sourceW)}  ${r.status}`,
+              );
+            }
+
+            const userCount = all.filter((p) => p.source === "user").length;
+            const defaultCount = all.length - userCount;
+            const disabledCount = all.filter((p) => p.disabled).length;
+            console.log("");
+            console.log(
+              `${all.length} plugin${all.length === 1 ? "" : "s"} ` +
+                `(${userCount} user, ${defaultCount} default` +
+                (disabledCount > 0
+                  ? `, ${disabledCount} disabled`
+                  : "") +
+                `).`,
+            );
+            return;
+          }
+
           const installed = listInstalledPlugins();
 
           if (opts.json) {
@@ -757,6 +817,18 @@ function formatTimestamp(iso: string | null): string {
   return new Date(ms).toISOString().slice(0, 19);
 }
 
+/**
+ * Build a human-readable status string for a plugin in the `--all` listing.
+ * Combines disabled state with any structural issues.
+ */
+function formatAllPluginStatus(p: AllPluginInfo): string {
+  const parts: string[] = [];
+  if (p.disabled) parts.push("disabled");
+  if (p.issues.length > 0) parts.push(p.issues.join("; "));
+  if (parts.length === 0) parts.push("enabled");
+  return parts.join(", ");
+}
+
 /** Human-readable status line for an inspection result. The from/to revisions
  * now live in the installed/remote blocks, so the status itself is just words. */
 function statusLine(status: PluginInspection["status"]): string {