@vellumai/assistant 0.8.11 → 0.8.12-staging.1

package/src/cli/commands/plugins.ts

@@ -10,6 +10,11 @@
 import type { Command } from "commander";
 
 import { confirmPrompt } from "../lib/confirm-prompt.js";
+import {
+  inspectPlugin,
+  type PluginInspection,
+  PluginInspectNotFoundError,
+} from "../lib/inspect-plugin.js";
 import {
   DEFAULT_PLUGIN_REF,
   installPlugin,
@@ -18,6 +23,7 @@ import {
   PluginNotFoundError,
 } from "../lib/install-from-github.js";
 import { listInstalledPlugins } from "../lib/list-installed-plugins.js";
+import type { FingerprintComparison } from "../lib/plugin-fingerprint.js";
 import { registerCommand } from "../lib/register-command.js";
 import {
   InvalidSearchPatternError,
@@ -27,6 +33,11 @@ import {
   PluginNotInstalledError,
   uninstallPlugin,
 } from "../lib/uninstall-plugin.js";
+import {
+  PluginNotUpgradableError,
+  type PluginUpgradeResult,
+  upgradePlugin,
+} from "../lib/upgrade-plugin.js";
 import { getCliLogger } from "../logger.js";
 
 const log = getCliLogger("plugins");
@@ -41,15 +52,19 @@ export function registerPluginsCommand(program: Command): void {
         "after",
         `
 Examples:
-  $ assistant plugins install simple-memory
-  $ assistant plugins install simple-memory --force
-  $ assistant plugins install simple-memory --ref my-feature-branch
+  $ assistant plugins install example
+  $ assistant plugins install example --force
+  $ assistant plugins install example --ref my-feature-branch
   $ assistant plugins list
   $ assistant plugins list --json
-  $ assistant plugins search memory
-  $ assistant plugins search "^simple"
-  $ assistant plugins search memory --json
-  $ assistant plugins uninstall simple-memory`,
+  $ assistant plugins inspect example
+  $ assistant plugins inspect example --json
+  $ assistant plugins upgrade example
+  $ assistant plugins upgrade example --dry-run
+  $ assistant plugins search example
+  $ assistant plugins search "^example"
+  $ assistant plugins search example --json
+  $ assistant plugins uninstall example`,
       );
 
       plugins
@@ -147,6 +162,55 @@ Examples:
           );
         });
 
+      plugins
+        .command("inspect <name>")
+        .description(
+          "Show a plugin's local install metadata and the marketplace pin, and whether an update is available",
+        )
+        .option("--json", "Emit machine-readable JSON instead of a summary")
+        .action(async (name: string, opts: { json?: boolean }) => {
+          try {
+            const inspection = await inspectPlugin(
+              { name },
+              { fetch: globalThis.fetch.bind(globalThis) },
+            );
+
+            if (opts.json) {
+              process.stdout.write(JSON.stringify(inspection, null, 2) + "\n");
+              return;
+            }
+
+            // Logged after the JSON early-return: the CLI logger writes
+            // info to stdout, which would otherwise corrupt --json output.
+            log.info(
+              {
+                name: inspection.name,
+                installed: inspection.installed,
+                status: inspection.status,
+              },
+              "plugin inspect",
+            );
+
+            for (const line of formatInspection(inspection)) {
+              console.log(line);
+            }
+          } catch (err) {
+            if (err instanceof PluginInspectNotFoundError) {
+              console.error(err.message);
+              process.exitCode = 1;
+              return;
+            }
+            if (err instanceof InvalidPluginNameError) {
+              console.error(err.message);
+              process.exitCode = 1;
+              return;
+            }
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`Plugin inspect failed: ${message}`);
+            process.exitCode = 1;
+          }
+        });
+
       plugins
         .command("search <query>")
         .description(
@@ -160,9 +224,13 @@ Examples:
               { fetch: globalThis.fetch.bind(globalThis) },
             );
 
-            // Log on every success path — JSON output, empty results, and
-            // populated tables alike — so observability doesn't depend on
-            // which formatting branch the caller landed in.
+            if (opts.json) {
+              process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+              return;
+            }
+
+            // Logged after the JSON early-return: the CLI logger writes info
+            // to stdout, which would otherwise corrupt --json output.
             log.info(
               {
                 query: result.query,
@@ -172,11 +240,6 @@ Examples:
               "external plugin search",
             );
 
-            if (opts.json) {
-              process.stdout.write(JSON.stringify(result, null, 2) + "\n");
-              return;
-            }
-
             if (result.matches.length === 0) {
               console.log(`No plugins matched "${result.query}".`);
               return;
@@ -253,6 +316,176 @@ Examples:
             process.exitCode = 1;
           }
         });
+
+      plugins
+        .command("upgrade <name>")
+        .description(
+          "Upgrade an installed plugin to the marketplace's current pin",
+        )
+        .option(
+          "--dry-run",
+          "Show what would change without modifying the install",
+        )
+        .option("--json", "Emit machine-readable JSON instead of a summary")
+        .action(
+          async (name: string, opts: { dryRun?: boolean; json?: boolean }) => {
+            try {
+              const result = await upgradePlugin(
+                { name, dryRun: opts.dryRun },
+                { fetch: globalThis.fetch.bind(globalThis) },
+              );
+
+              if (opts.json) {
+                process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+                return;
+              }
+
+              // Logged after the JSON early-return: the CLI logger writes
+              // info to stdout, which would otherwise corrupt --json output.
+              log.info(
+                {
+                  name: result.name,
+                  outcome: result.outcome,
+                  from: result.fromCommit,
+                  to: result.toCommit,
+                },
+                "plugin upgrade",
+              );
+
+              for (const line of formatUpgrade(result)) {
+                console.log(line);
+              }
+            } catch (err) {
+              if (
+                err instanceof PluginNotInstalledError ||
+                err instanceof PluginNotUpgradableError ||
+                err instanceof InvalidPluginNameError
+              ) {
+                console.error(err.message);
+                process.exitCode = 1;
+                return;
+              }
+              const message = err instanceof Error ? err.message : String(err);
+              console.error(`Plugin upgrade failed: ${message}`);
+              process.exitCode = 1;
+            }
+          },
+        );
     },
   });
 }
+
+/** Abbreviate a commit SHA for display; passes through non-SHA / null values. */
+function shortSha(sha: string | null): string {
+  return sha ? sha.slice(0, 7) : "—";
+}
+
+/** Human-readable status line for an inspection result. */
+function statusLine(inspection: PluginInspection): string {
+  const { status, local, remote } = inspection;
+  switch (status) {
+    case "up-to-date":
+      return "up to date";
+    case "update-available":
+      return `update available  (${shortSha(local?.commit ?? null)} → ${shortSha(
+        remote?.commit ?? null,
+      )})`;
+    case "not-installed":
+      return "not installed";
+    case "not-in-marketplace":
+      return "installed (not in marketplace)";
+    case "unknown-provenance":
+      return "unknown — reinstall to record provenance";
+    case "remote-unavailable":
+      return "installed (marketplace unavailable)";
+  }
+}
+
+/**
+ * Summarize local edits relative to the install-time fingerprint. Reports
+ * "unknown" when no baseline was recorded (an older or manually-copied
+ * install), "none" when the on-disk tree matches, or a per-category count.
+ */
+function localEditsLine(changes: FingerprintComparison | null): string {
+  if (!changes)
+    return "unknown (no recorded baseline; reinstall to record one)";
+  if (changes.clean) return "none";
+  const parts = [
+    `${changes.modified.length} modified`,
+    `${changes.added.length} added`,
+    `${changes.removed.length} removed`,
+  ];
+  return parts.join(", ");
+}
+
+/** Render an inspection as aligned, human-readable summary lines. */
+function formatInspection(inspection: PluginInspection): string[] {
+  const { name, local, remote, remoteError } = inspection;
+  const lines: string[] = [`${name}  plugin`];
+  const row = (label: string, value: string) =>
+    lines.push(`  ${label.padEnd(11)} ${value}`);
+
+  row("status", statusLine(inspection));
+
+  if (local) {
+    const installedAt = local.installedAt
+      ? `  (${local.installedAt.slice(0, 10)})`
+      : "";
+    row("installed", `${shortSha(local.commit)}${installedAt}`);
+    row("local edits", localEditsLine(local.localChanges));
+  }
+
+  if (remote) {
+    const where = remote.path ? `${remote.repo}/${remote.path}` : remote.repo;
+    row(
+      "remote pin",
+      `${shortSha(remote.commit)}  (${where}, ${remote.marketplaceRef})`,
+    );
+  } else if (remoteError) {
+    row("remote", `unavailable — ${remoteError}`);
+  }
+
+  const version = local?.version ?? null;
+  if (version) row("version", version);
+
+  const license = remote?.license ?? null;
+  const homepage = remote?.homepage ?? null;
+  if (license && homepage) row("license", `${license}   homepage  ${homepage}`);
+  else if (license) row("license", license);
+  else if (homepage) row("homepage", homepage);
+
+  const description = remote?.description ?? local?.description ?? null;
+  if (description) row("description", description);
+
+  for (const issue of local?.issues ?? []) row("issue", issue);
+
+  return lines;
+}
+
+/** Render an upgrade result as human-readable summary lines. */
+function formatUpgrade(result: PluginUpgradeResult): string[] {
+  const { name, fromCommit, toCommit } = result;
+  const move = `${shortSha(fromCommit)} → ${shortSha(toCommit)}`;
+  const provenanceNote = result.provenanceWasUnknown
+    ? " (previous install had no recorded provenance)"
+    : "";
+
+  switch (result.outcome) {
+    case "already-up-to-date":
+      return [`"${name}" is already up to date (${shortSha(toCommit)}).`];
+    case "would-upgrade":
+      return [
+        `"${name}" would upgrade ${move}${provenanceNote} (dry run; no changes made).`,
+      ];
+    case "upgraded": {
+      const count =
+        result.fileCount === null
+          ? ""
+          : ` (${result.fileCount} file${result.fileCount === 1 ? "" : "s"})`;
+      return [
+        `Upgraded "${name}" ${move}${count}${provenanceNote} → ${result.target}`,
+        "Restart the assistant to pick up the upgrade.",
+      ];
+    }
+  }
+}

package/src/cli/lib/__tests__/inspect-plugin.test.ts

@@ -0,0 +1,318 @@
+/**
+ * Tests for {@link inspectPlugin}.
+ *
+ * The marketplace fetch is replaced with an in-memory fixture passed via the
+ * `fetch` dependency, and the installed-copy path is exercised against a real
+ * temp directory passed via `workspacePluginsDir` — no globals are monkeypatched.
+ * Drift is the exact comparison of the provenance sidecar's commit against the
+ * marketplace pin, so the fixtures vary those two SHAs.
+ */
+
+import { mkdirSync, mkdtempSync, 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 {
+  inspectPlugin,
+  PluginInspectNotFoundError,
+} from "../inspect-plugin.js";
+import type { FetchLike } from "../install-from-github.js";
+import { computeFingerprint } from "../plugin-fingerprint.js";
+
+const SHA_A = "a".repeat(40);
+const SHA_B = "b".repeat(40);
+
+/** A marketplace manifest object with a single entry for `name`. */
+function manifestWith(name: string, ref: string): unknown {
+  return {
+    name: "vellum",
+    plugins: [
+      {
+        name,
+        source: { source: "github", repo: `example-org/${name}`, ref },
+        description: "A test plugin.",
+        category: "developer",
+        homepage: `https://github.com/example-org/${name}`,
+        license: "MIT",
+      },
+    ],
+  };
+}
+
+/**
+ * Build a `fetch` that serves the marketplace manifest. `marketplace:
+ * undefined` answers 404 (empty catalog); `fail: true` rejects with a network
+ * error. Anything else surfaces a 500 so test bugs are loud.
+ */
+function makeFetch(opts: { marketplace?: unknown; fail?: boolean }): FetchLike {
+  return (async (input: RequestInfo | URL) => {
+    const url = typeof input === "string" ? input : input.toString();
+    if (url.includes("marketplace.json")) {
+      if (opts.fail) throw new Error("network down");
+      if (opts.marketplace === undefined) {
+        return new Response("not found", { status: 404 });
+      }
+      return new Response(JSON.stringify(opts.marketplace), { status: 200 });
+    }
+    return new Response("unexpected url: " + url, { status: 500 });
+  }) as FetchLike;
+}
+
+/** Materialize an installed plugin copy with an optional provenance sidecar. */
+function installPlugin(
+  workspace: string,
+  name: string,
+  opts: {
+    version?: string;
+    sidecar?: { commit?: string | null; ref?: string } | null;
+    /** Embed a content fingerprint of the materialized tree in the sidecar. */
+    fingerprint?: boolean;
+  } = {},
+): void {
+  const dir = join(workspace, name);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(
+    join(dir, "package.json"),
+    JSON.stringify({
+      name,
+      version: opts.version ?? "0.1.0",
+      description: "Installed copy.",
+    }),
+  );
+  if (opts.sidecar !== null) {
+    const sidecar = opts.sidecar ?? { commit: SHA_A };
+    // Mirror install: fingerprint the tree before the sidecar is written so it
+    // is not part of its own baseline.
+    const fingerprint = opts.fingerprint
+      ? computeFingerprint(dir, ["install-meta.json"])
+      : undefined;
+    writeFileSync(
+      join(dir, "install-meta.json"),
+      JSON.stringify({
+        origin: "vellum",
+        name,
+        source: {
+          kind: "github",
+          owner: "example-org",
+          repo: name,
+          ref: sidecar.ref ?? sidecar.commit ?? SHA_A,
+        },
+        commit: sidecar.commit ?? undefined,
+        installedAt: "2026-06-10T12:00:00.000Z",
+        fingerprint,
+      }),
+    );
+  }
+}
+
+let workspace: string;
+
+beforeEach(() => {
+  workspace = mkdtempSync(join(tmpdir(), "inspect-plugin-"));
+});
+
+afterEach(() => {
+  rmSync(workspace, { recursive: true, force: true });
+});
+
+describe("inspectPlugin", () => {
+  test("reports up-to-date when the installed commit equals the marketplace pin", async () => {
+    // GIVEN an installed plugin pinned to the same commit the marketplace pins
+    installPlugin(workspace, "level-up", { sidecar: { commit: SHA_A } });
+    const fetch = makeFetch({ marketplace: manifestWith("level-up", SHA_A) });
+
+    // WHEN it is inspected
+    const result = await inspectPlugin(
+      { name: "level-up" },
+      { fetch, workspacePluginsDir: workspace },
+    );
+
+    // THEN the status is up-to-date and both sides resolve the same commit
+    expect(result.status).toBe("up-to-date");
+    expect(result.installed).toBe(true);
+    expect(result.local?.commit).toBe(SHA_A);
+    expect(result.remote?.commit).toBe(SHA_A);
+    // AND local + remote metadata are surfaced
+    expect(result.local?.version).toBe("0.1.0");
+    expect(result.remote?.repo).toBe("example-org/level-up");
+    expect(result.remote?.license).toBe("MIT");
+  });
+
+  test("reports update-available when the marketplace pin has advanced", async () => {
+    // GIVEN an installed plugin whose commit differs from the marketplace pin
+    installPlugin(workspace, "level-up", { sidecar: { commit: SHA_A } });
+    const fetch = makeFetch({ marketplace: manifestWith("level-up", SHA_B) });
+
+    // WHEN it is inspected
+    const result = await inspectPlugin(
+      { name: "level-up" },
+      { fetch, workspacePluginsDir: workspace },
+    );
+
+    // THEN drift is reported with both commits
+    expect(result.status).toBe("update-available");
+    expect(result.local?.commit).toBe(SHA_A);
+    expect(result.remote?.commit).toBe(SHA_B);
+  });
+
+  test("falls back to the sidecar ref when no commit was recorded", async () => {
+    // GIVEN a sidecar with no commit but a full-SHA ref equal to the pin
+    installPlugin(workspace, "level-up", {
+      sidecar: { commit: null, ref: SHA_A },
+    });
+    const fetch = makeFetch({ marketplace: manifestWith("level-up", SHA_A) });
+
+    // WHEN it is inspected
+    const result = await inspectPlugin(
+      { name: "level-up" },
+      { fetch, workspacePluginsDir: workspace },
+    );
+
+    // THEN the ref stands in for the commit and the status is up-to-date
+    expect(result.status).toBe("up-to-date");
+    expect(result.local?.commit).toBe(SHA_A);
+  });
+
+  test("reports unknown-provenance when installed without a resolvable commit", async () => {
+    // GIVEN an installed copy with no provenance sidecar at all
+    installPlugin(workspace, "level-up", { sidecar: null });
+    const fetch = makeFetch({ marketplace: manifestWith("level-up", SHA_A) });
+
+    // WHEN it is inspected
+    const result = await inspectPlugin(
+      { name: "level-up" },
+      { fetch, workspacePluginsDir: workspace },
+    );
+
+    // THEN the commit cannot be compared
+    expect(result.status).toBe("unknown-provenance");
+    expect(result.local?.commit).toBeNull();
+    expect(result.remote?.commit).toBe(SHA_A);
+  });
+
+  test("reports not-in-marketplace when installed but no entry claims the name", async () => {
+    // GIVEN an installed plugin and an empty catalog
+    installPlugin(workspace, "level-up", { sidecar: { commit: SHA_A } });
+    const fetch = makeFetch({ marketplace: undefined });
+
+    // WHEN it is inspected
+    const result = await inspectPlugin(
+      { name: "level-up" },
+      { fetch, workspacePluginsDir: workspace },
+    );
+
+    // THEN there is no remote to compare against
+    expect(result.status).toBe("not-in-marketplace");
+    expect(result.installed).toBe(true);
+    expect(result.remote).toBeNull();
+  });
+
+  test("reports not-installed but previews the marketplace entry", async () => {
+    // GIVEN a marketplace entry with no local copy installed
+    const fetch = makeFetch({ marketplace: manifestWith("level-up", SHA_B) });
+
+    // WHEN it is inspected
+    const result = await inspectPlugin(
+      { name: "level-up" },
+      { fetch, workspacePluginsDir: workspace },
+    );
+
+    // THEN the remote metadata previews what would be installed
+    expect(result.status).toBe("not-installed");
+    expect(result.installed).toBe(false);
+    expect(result.local).toBeNull();
+    expect(result.remote?.commit).toBe(SHA_B);
+  });
+
+  test("reports remote-unavailable when the marketplace cannot be reached", async () => {
+    // GIVEN an installed plugin and a failing marketplace fetch
+    installPlugin(workspace, "level-up", { sidecar: { commit: SHA_A } });
+    const fetch = makeFetch({ fail: true });
+
+    // WHEN it is inspected
+    const result = await inspectPlugin(
+      { name: "level-up" },
+      { fetch, workspacePluginsDir: workspace },
+    );
+
+    // THEN local info is still reported alongside the fetch error
+    expect(result.status).toBe("remote-unavailable");
+    expect(result.local?.commit).toBe(SHA_A);
+    expect(result.remote).toBeNull();
+    expect(result.remoteError).toContain("network down");
+  });
+
+  test("reports no local changes when the on-disk tree matches the fingerprint", async () => {
+    // GIVEN an installed plugin with a recorded content fingerprint, untouched
+    installPlugin(workspace, "level-up", {
+      sidecar: { commit: SHA_A },
+      fingerprint: true,
+    });
+    const fetch = makeFetch({ marketplace: manifestWith("level-up", SHA_A) });
+
+    // WHEN it is inspected
+    const result = await inspectPlugin(
+      { name: "level-up" },
+      { fetch, workspacePluginsDir: workspace },
+    );
+
+    // THEN the local copy is reported clean against its baseline
+    expect(result.local?.localChanges?.clean).toBe(true);
+    expect(result.local?.localChanges?.modified).toEqual([]);
+  });
+
+  test("detects a locally modified file against the fingerprint", async () => {
+    // GIVEN an installed plugin with a recorded fingerprint
+    installPlugin(workspace, "level-up", {
+      sidecar: { commit: SHA_A },
+      fingerprint: true,
+    });
+
+    // AND a tracked file is edited after install
+    writeFileSync(
+      join(workspace, "level-up", "package.json"),
+      JSON.stringify({ name: "level-up", version: "9.9.9" }),
+    );
+    const fetch = makeFetch({ marketplace: manifestWith("level-up", SHA_A) });
+
+    // WHEN it is inspected
+    const result = await inspectPlugin(
+      { name: "level-up" },
+      { fetch, workspacePluginsDir: workspace },
+    );
+
+    // THEN the edited file surfaces as a local modification
+    expect(result.local?.localChanges?.clean).toBe(false);
+    expect(result.local?.localChanges?.modified).toEqual(["package.json"]);
+  });
+
+  test("reports unknown local changes when no fingerprint was recorded", async () => {
+    // GIVEN an install whose sidecar predates fingerprinting
+    installPlugin(workspace, "level-up", { sidecar: { commit: SHA_A } });
+    const fetch = makeFetch({ marketplace: manifestWith("level-up", SHA_A) });
+
+    // WHEN it is inspected
+    const result = await inspectPlugin(
+      { name: "level-up" },
+      { fetch, workspacePluginsDir: workspace },
+    );
+
+    // THEN modification cannot be determined
+    expect(result.local).not.toBeNull();
+    expect(result.local?.localChanges).toBeNull();
+  });
+
+  test("throws when the plugin is neither installed nor in the marketplace", async () => {
+    // GIVEN no local copy and an empty catalog
+    const fetch = makeFetch({ marketplace: undefined });
+
+    // WHEN/THEN inspecting a missing plugin rejects with a not-found error
+    await expect(
+      inspectPlugin(
+        { name: "ghost" },
+        { fetch, workspacePluginsDir: workspace },
+      ),
+    ).rejects.toBeInstanceOf(PluginInspectNotFoundError);
+  });
+});

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

@@ -371,16 +371,23 @@ describe("installPlugin — marketplace resolution", () => {
       "https://github.com/JuliusBrussee/caveman.git",
     );
 
-    // AND a provenance manifest records the github source + commit.
-    const manifest = JSON.parse(
-      readFileSync(join(target, ".vellum-plugin.json"), "utf-8"),
+    // AND an install-meta sidecar records origin + github source + commit.
+    const meta = JSON.parse(
+      readFileSync(join(target, "install-meta.json"), "utf-8"),
     );
-    expect(manifest.source.kind).toBe("github");
-    expect(manifest.source.owner).toBe("JuliusBrussee");
-    expect(manifest.source.ref).toBe(
-      "63a91ecadbf4c4719a4602a5abb00883f9966034",
-    );
-    expect(manifest.commit).toBe("63a91ecadbf4c4719a4602a5abb00883f9966034");
+    expect(meta.origin).toBe("vellum");
+    expect(meta.sourceRepo).toBe("JuliusBrussee/caveman");
+    expect(meta.source.kind).toBe("github");
+    expect(meta.source.owner).toBe("JuliusBrussee");
+    expect(meta.source.ref).toBe("63a91ecadbf4c4719a4602a5abb00883f9966034");
+    expect(meta.commit).toBe("63a91ecadbf4c4719a4602a5abb00883f9966034");
+
+    // AND both content digests baseline the materialized tree (excluding the
+    // sidecar) so later local edits are detectable.
+    expect(meta.fingerprint.algorithm).toBe("sha256");
+    expect(meta.fingerprint.files["package.json"]).toMatch(/^[0-9a-f]{64}$/);
+    expect(meta.fingerprint.files["install-meta.json"]).toBeUndefined();
+    expect(meta.contentHash).toMatch(/^v2:[0-9a-f]{64}$/);
   });
 
   test("refuses to install when the checked-out commit differs from the pinned SHA", async () => {