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

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

@@ -24,17 +24,36 @@ import {
 import {
   DEFAULT_PLUGIN_REF,
   installPlugin,
+  type InstallPluginOptions,
   InvalidPluginNameError,
   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,
+  listPinHistory,
+  type PluginPinHistoryEntry,
+  PluginPinHistoryError,
+  resolvePinToMarketplaceCommit,
+} from "../lib/plugin-pin-history.js";
 import { registerCommand } from "../lib/register-command.js";
 import {
   InvalidSearchPatternError,
   searchPlugins,
 } from "../lib/search-plugins.js";
+import {
+  disablePlugin,
+  enablePlugin,
+  InvalidPluginNameError as ToggleInvalidPluginNameError,
+  PluginAlreadyInStateException,
+  PluginDirectoryNotFoundError,
+} from "../lib/toggle-plugin.js";
 import {
   PluginNotInstalledError,
   uninstallPlugin,
@@ -65,8 +84,13 @@ Examples:
   $ assistant plugins install example
   $ assistant plugins install example --force
   $ assistant plugins install example --ref my-feature-branch
+  $ assistant plugins versions example
+  $ assistant plugins versions example --json
+  $ 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
@@ -79,7 +103,9 @@ Examples:
   $ assistant plugins search example
   $ assistant plugins search "^example"
   $ assistant plugins search example --json
-  $ assistant plugins uninstall example`,
+  $ assistant plugins uninstall example
+  $ assistant plugins enable example
+  $ assistant plugins disable example`,
       );
 
       plugins
@@ -90,19 +116,35 @@ Examples:
         .option("--force", "Overwrite an existing install")
         .option(
           "--ref <ref>",
-          `Git ref to fetch from (default: ${DEFAULT_PLUGIN_REF})`,
+          `Marketplace manifest revision to read the pin from (default: ${DEFAULT_PLUGIN_REF})`,
+        )
+        .option(
+          "--pin <sha>",
+          "Install a specific reviewed marketplace pin (full commit SHA); run `plugins versions <name>` to list them",
+        )
+        .option(
+          "--allow-unreviewed",
+          "With --pin, install a SHA that is not in the reviewed marketplace history (advanced; the curated adapter may not match)",
         )
         .action(
-          async (name: string, opts: { force?: boolean; ref?: string }) => {
+          async (
+            name: string,
+            opts: {
+              force?: boolean;
+              ref?: string;
+              pin?: string;
+              allowUnreviewed?: boolean;
+            },
+          ) => {
             try {
-              const result = await installPlugin(
-                {
-                  name,
-                  force: opts.force ?? false,
-                  ref: opts.ref ?? DEFAULT_PLUGIN_REF,
-                },
-                { fetch: globalThis.fetch.bind(globalThis) },
-              );
+              const installOpts = await resolveInstallOptions(name, opts);
+              if (installOpts === null) {
+                process.exitCode = 1;
+                return;
+              }
+              const result = await installPlugin(installOpts, {
+                fetch: globalThis.fetch.bind(globalThis),
+              });
               log.info(
                 {
                   name: result.name,
@@ -131,6 +173,14 @@ Examples:
                 process.exitCode = 1;
                 return;
               }
+              if (
+                err instanceof InvalidPluginNameError ||
+                err instanceof PluginPinHistoryError
+              ) {
+                console.error(err.message);
+                process.exitCode = 1;
+                return;
+              }
               const message = err instanceof Error ? err.message : String(err);
               console.error(`Plugin install failed: ${message}`);
               process.exitCode = 1;
@@ -138,11 +188,120 @@ Examples:
           },
         );
 
+      plugins
+        .command("versions <name>")
+        .description(
+          "List the recent reviewed marketplace pins for a plugin, newest first. Install an older one with `plugins install <name> --pin <sha>`",
+        )
+        .option("--json", "Emit machine-readable JSON instead of a table")
+        .option(
+          "--limit <n>",
+          `Maximum number of pins to show (default: ${DEFAULT_PIN_HISTORY_LIMIT})`,
+        )
+        .action(
+          async (name: string, opts: { json?: boolean; limit?: string }) => {
+            let limit: number | undefined;
+            if (opts.limit !== undefined) {
+              limit = Number.parseInt(opts.limit, 10);
+              if (!Number.isInteger(limit) || limit < 1) {
+                console.error("--limit must be a positive integer.");
+                process.exitCode = 1;
+                return;
+              }
+            }
+            try {
+              const history = await listPinHistory(
+                name,
+                { fetch: globalThis.fetch.bind(globalThis) },
+                limit !== undefined ? { limit } : {},
+              );
+
+              if (opts.json) {
+                process.stdout.write(JSON.stringify(history, null, 2) + "\n");
+                return;
+              }
+
+              // Logged after the JSON early-return so the logger's stdout
+              // writes never corrupt --json output.
+              log.info({ name, count: history.length }, "plugin versions");
+              for (const line of formatVersions(name, history)) {
+                console.log(line);
+              }
+            } catch (err) {
+              if (
+                err instanceof InvalidPluginNameError ||
+                err instanceof PluginPinHistoryError
+              ) {
+                console.error(err.message);
+                process.exitCode = 1;
+                return;
+              }
+              const message = err instanceof Error ? err.message : String(err);
+              console.error(`Plugin versions failed: ${message}`);
+              process.exitCode = 1;
+            }
+          },
+        );
+
       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) {
@@ -399,6 +558,61 @@ Examples:
           }
         });
 
+      plugins
+        .command("disable <name>")
+        .description(
+          "Disable a plugin by creating a .disabled sentinel file. Works for both user-installed and default plugins. Restart the assistant for the change to take effect.",
+        )
+        .action((name: string) => {
+          try {
+            const result = disablePlugin(name);
+            log.info({ name: result.name }, "plugin disabled");
+            console.log(
+              `Disabled plugin "${result.name}". Restart the assistant for the change to take effect.`,
+            );
+          } catch (err) {
+            if (
+              err instanceof PluginAlreadyInStateException ||
+              err instanceof ToggleInvalidPluginNameError ||
+              err instanceof PluginDirectoryNotFoundError
+            ) {
+              console.error(err.message);
+              process.exitCode = 1;
+              return;
+            }
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`Plugin disable failed: ${message}`);
+            process.exitCode = 1;
+          }
+        });
+
+      plugins
+        .command("enable <name>")
+        .description(
+          "Re-enable a disabled plugin by removing the .disabled sentinel file. Restart the assistant for the change to take effect.",
+        )
+        .action((name: string) => {
+          try {
+            const result = enablePlugin(name);
+            log.info({ name: result.name }, "plugin enabled");
+            console.log(
+              `Enabled plugin "${result.name}". Restart the assistant for the change to take effect.`,
+            );
+          } catch (err) {
+            if (
+              err instanceof PluginAlreadyInStateException ||
+              err instanceof ToggleInvalidPluginNameError
+            ) {
+              console.error(err.message);
+              process.exitCode = 1;
+              return;
+            }
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`Plugin enable failed: ${message}`);
+            process.exitCode = 1;
+          }
+        });
+
       plugins
         .command("upgrade <name>")
         .description(
@@ -483,6 +697,109 @@ Examples:
 }
 
 /** Abbreviate a commit SHA for display; passes through non-SHA / null values. */
+/** Full Git commit SHA — 40 hex (SHA-1) or 64 (SHA-256). */
+const FULL_SHA_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i;
+
+/**
+ * Resolve `plugins install` flags into {@link InstallPluginOptions}, or `null`
+ * when the flag combination is invalid (a message is printed in that case, and
+ * the caller exits non-zero). Network / marketplace failures raised while
+ * resolving a `--pin` propagate to the caller's catch.
+ *
+ * `--pin <sha>` installs a specific reviewed marketplace pin: the SHA is looked
+ * up in the plugin's pin history and installed from the marketplace commit that
+ * introduced it, so the curated adapter stub of that era comes along. With
+ * `--allow-unreviewed` the SHA is materialized directly (adapter from `main`),
+ * bypassing the history check — the advanced escape hatch.
+ */
+async function resolveInstallOptions(
+  name: string,
+  opts: {
+    force?: boolean;
+    ref?: string;
+    pin?: string;
+    allowUnreviewed?: boolean;
+  },
+): Promise<InstallPluginOptions | null> {
+  const force = opts.force ?? false;
+
+  if (!opts.pin) {
+    if (opts.allowUnreviewed) {
+      console.error("--allow-unreviewed only applies together with --pin.");
+      return null;
+    }
+    return { name, force, ref: opts.ref ?? DEFAULT_PLUGIN_REF };
+  }
+
+  const pin = opts.pin.trim();
+  if (!FULL_SHA_RE.test(pin)) {
+    console.error(
+      `--pin must be a full commit SHA (40 or 64 hex chars); got ${JSON.stringify(opts.pin)}.`,
+    );
+    return null;
+  }
+  if (opts.ref) {
+    console.error(
+      "--ref and --pin cannot be combined; --pin already selects the revision.",
+    );
+    return null;
+  }
+
+  if (opts.allowUnreviewed) {
+    // Materialize the exact SHA from the plugin's current-manifest repo,
+    // bypassing the reviewed-history check. The adapter stub still comes from
+    // the default ref, so an adapted plugin may not reproduce faithfully.
+    return { name, force, ref: DEFAULT_PLUGIN_REF, commitOverride: pin };
+  }
+
+  const entry = await resolvePinToMarketplaceCommit(name, pin, {
+    fetch: globalThis.fetch.bind(globalThis),
+  });
+  if (!entry) {
+    console.error(
+      `"${pin}" is not a reviewed marketplace pin for "${name}".\n` +
+        `Run \`assistant plugins versions ${name}\` to see available pins, ` +
+        "or pass --allow-unreviewed to install it anyway.",
+    );
+    return null;
+  }
+  return { name, force, ref: entry.marketplaceCommit };
+}
+
+/**
+ * Render a plugin's marketplace-pin history as a table: the pinned commit (short
+ * SHA), when it was promoted, and a marker for the pin currently active. An
+ * empty history reports that none was found.
+ */
+function formatVersions(
+  name: string,
+  history: readonly PluginPinHistoryEntry[],
+): string[] {
+  if (history.length === 0) {
+    return [`No marketplace pin history found for "${name}".`];
+  }
+  const rows = history.map((entry) => ({
+    pin: shortSha(entry.pin),
+    promoted: formatTimestamp(entry.promotedAt),
+    marker: entry.current ? "(current)" : "",
+  }));
+  const pinW = Math.max(3, ...rows.map((r) => r.pin.length));
+  const promotedW = Math.max(8, ...rows.map((r) => r.promoted.length));
+  const pad = (s: string, w: number) => s + " ".repeat(w - s.length);
+  const lines = [
+    `${pad("PIN", pinW)}  ${pad("PROMOTED", promotedW)}  `.trimEnd(),
+  ];
+  for (const r of rows) {
+    lines.push(
+      `${pad(r.pin, pinW)}  ${pad(r.promoted, promotedW)}  ${r.marker}`.trimEnd(),
+    );
+  }
+  lines.push("");
+  lines.push("Install an older pin with:");
+  lines.push(`  assistant plugins install ${name} --pin <sha> --force`);
+  return lines;
+}
+
 function shortSha(sha: string | null): string {
   return sha ? sha.slice(0, 7) : "—";
 }
@@ -500,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 {

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

@@ -32,6 +32,7 @@ import {
   PluginPostinstallError,
   PluginSourceUnavailableError,
   type PostinstallRunner,
+  readInstallMeta,
   sanitizePluginName,
 } from "../install-from-github.js";
 
@@ -292,6 +293,36 @@ describe("installPlugin — install lifecycle", () => {
     expect(existsSync(join(target, "README.md"))).toBe(true);
   });
 
+  test("commitOverride materializes a specific commit, keeping repo from the manifest", async () => {
+    // GIVEN a manifest pinning the current SHA, but an override to an older one
+    const OLD_SHA = "1".repeat(40);
+    const fetch = makeContentsFetch({ tree: {}, manifest: CAVEMAN_MANIFEST });
+    const calls: string[][] = [];
+    const runGit = fakeGitRunner({
+      tree: { "package.json": '{"name":"caveman"}' },
+      commit: OLD_SHA,
+      calls,
+    });
+
+    // WHEN we install with the commit override
+    const result = await installPlugin(
+      { name: "caveman", force: false, ref: "main", commitOverride: OLD_SHA },
+      { fetch, runGit, workspacePluginsDir: pluginsDir },
+    );
+
+    // THEN the clone fetched the override commit, not the manifest's pin
+    expect(calls.find((c) => c[0] === "fetch")?.at(-1)).toBe(OLD_SHA);
+    expect(result.commit).toBe(OLD_SHA);
+    expect(result.ref).toBe(OLD_SHA);
+
+    // AND provenance records the override as the installed ref while still
+    // resolving owner/repo from the manifest entry
+    const meta = readInstallMeta(join(pluginsDir, "caveman"));
+    expect(meta?.source.ref).toBe(OLD_SHA);
+    expect(meta?.source.repo).toBe("caveman");
+    expect(meta?.source.owner).toBe("JuliusBrussee");
+  });
+
   test("--force preserves the existing install when the clone fails", async () => {
     // GIVEN a working copy already on disk
     const target = join(pluginsDir, "caveman");
@@ -823,4 +854,13 @@ describe("sanitizePluginName", () => {
     expect(sanitizePluginName("plugin_2")).toBe("plugin_2");
     expect(sanitizePluginName("a")).toBe("a");
   });
+
+  test.each([
+    "default-advisor",
+    "default-memory-retrieval",
+    "default-",
+    "default-x",
+  ])("rejects reserved prefix name %p", (reserved) => {
+    expect(() => sanitizePluginName(reserved)).toThrow(InvalidPluginNameError);
+  });
 });