@vellumai/assistant 0.9.0 → 0.10.0-dev.202606192226.8ed8a6a

package/src/cli/commands/plugins.ts

@@ -10,6 +10,11 @@
 import type { Command } from "commander";
 
 import { confirmPrompt } from "../lib/confirm-prompt.js";
+import {
+  diffPlugin,
+  type PluginDiffResult,
+  PluginDiffUnavailableError,
+} from "../lib/diff-plugin.js";
 import {
   inspectPlugin,
   type PluginInspection,
@@ -19,12 +24,20 @@ 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 { 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,
@@ -35,8 +48,12 @@ import {
   uninstallPlugin,
 } from "../lib/uninstall-plugin.js";
 import {
+  DEFAULT_PLUGIN_UPGRADE_STRATEGY,
+  PLUGIN_UPGRADE_STRATEGIES,
+  PluginMergeBaselineError,
   PluginNotUpgradableError,
   type PluginUpgradeResult,
+  type PluginUpgradeStrategy,
   upgradePlugin,
 } from "../lib/upgrade-plugin.js";
 import { getCliLogger } from "../logger.js";
@@ -56,12 +73,20 @@ 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 inspect example
   $ assistant plugins inspect example --json
+  $ assistant plugins diff example
+  $ assistant plugins diff example --json
   $ assistant plugins upgrade example
   $ assistant plugins upgrade example --dry-run
+  $ assistant plugins upgrade example --strategy ours
+  $ assistant plugins upgrade example --strategy theirs
+  $ assistant plugins upgrade example --strategy assistant
   $ assistant plugins search example
   $ assistant plugins search "^example"
   $ assistant plugins search example --json
@@ -76,19 +101,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,
@@ -117,6 +158,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;
@@ -124,6 +173,61 @@ 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/")
@@ -166,7 +270,7 @@ Examples:
       plugins
         .command("inspect <name>")
         .description(
-          "Show a plugin's local install metadata and the marketplace pin, and whether an update is available",
+          "Show a plugin's local install metadata, the marketplace pin, whether an update is available, and the surfaces (skills, hooks, tools) it contributes",
         )
         .option("--json", "Emit machine-readable JSON instead of a summary")
         .action(async (name: string, opts: { json?: boolean }) => {
@@ -212,6 +316,73 @@ Examples:
           }
         });
 
+      plugins
+        .command("diff <name>")
+        .description(
+          "Show a unified diff of local edits to an installed plugin against the commit it was installed at",
+        )
+        .option(
+          "--json",
+          "Emit the machine-readable diff result as JSON (files: { path, status, diff, binary, reconstructed }[]) instead of a unified diff",
+        )
+        .addHelpText(
+          "after",
+          `
+Arguments:
+  name   Install name (kebab-case directory under the workspace plugins dir);
+         run 'assistant plugins list' to see installed names.
+
+The baseline is the exact commit the plugin was installed at (recorded in its
+install-meta.json), re-materialized through the install pipeline — so an
+install-time adapter transform never reads as a local change. To compare
+against the marketplace's current pin instead, use 'plugins upgrade --dry-run'.
+
+Examples:
+  $ assistant plugins diff example
+  $ assistant plugins diff example --json`,
+        )
+        .action(async (name: string, opts: { json?: boolean }) => {
+          try {
+            const result = await diffPlugin(
+              { name },
+              { 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,
+                clean: result.clean,
+                files: result.files.length,
+              },
+              "plugin diff",
+            );
+
+            for (const line of formatDiff(result)) {
+              console.log(line);
+            }
+          } catch (err) {
+            if (
+              err instanceof PluginNotInstalledError ||
+              err instanceof PluginDiffUnavailableError ||
+              err instanceof InvalidPluginNameError
+            ) {
+              console.error(err.message);
+              process.exitCode = 1;
+              return;
+            }
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`Plugin diff failed: ${message}`);
+            process.exitCode = 1;
+          }
+        });
+
       plugins
         .command("search <query>")
         .description(
@@ -327,12 +498,36 @@ Examples:
           "--dry-run",
           "Show what would change without modifying the install",
         )
+        .option(
+          "--strategy <strategy>",
+          `How to reconcile local edits with the pin: ${PLUGIN_UPGRADE_STRATEGIES.join(", ")} (default: ${DEFAULT_PLUGIN_UPGRADE_STRATEGY})`,
+        )
         .option("--json", "Emit machine-readable JSON instead of a summary")
         .action(
-          async (name: string, opts: { dryRun?: boolean; json?: boolean }) => {
+          async (
+            name: string,
+            opts: { dryRun?: boolean; strategy?: string; json?: boolean },
+          ) => {
+            const strategy = opts.strategy;
+            if (
+              strategy !== undefined &&
+              !(PLUGIN_UPGRADE_STRATEGIES as readonly string[]).includes(
+                strategy,
+              )
+            ) {
+              console.error(
+                `Invalid --strategy "${strategy}". Expected one of: ${PLUGIN_UPGRADE_STRATEGIES.join(", ")}.`,
+              );
+              process.exitCode = 1;
+              return;
+            }
             try {
               const result = await upgradePlugin(
-                { name, dryRun: opts.dryRun },
+                {
+                  name,
+                  dryRun: opts.dryRun,
+                  strategy: strategy as PluginUpgradeStrategy | undefined,
+                },
                 { fetch: globalThis.fetch.bind(globalThis) },
               );
 
@@ -360,6 +555,7 @@ Examples:
               if (
                 err instanceof PluginNotInstalledError ||
                 err instanceof PluginNotUpgradableError ||
+                err instanceof PluginMergeBaselineError ||
                 err instanceof InvalidPluginNameError
               ) {
                 console.error(err.message);
@@ -377,6 +573,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) : "—";
 }
@@ -443,12 +742,20 @@ function remoteLocation(remote: PluginRemoteInfo): string {
  * `location`, with a `drift` line under the installed copy.
  */
 function formatInspection(inspection: PluginInspection): string[] {
-  const { name, status, local, remote, remoteError } = inspection;
+  const { name, status, local, remote, remoteError, surfaces } = inspection;
   const lines: string[] = [name, "─".repeat(44)];
   const topRow = (label: string, value: string) =>
     lines.push(`${label.padEnd(11)} ${value}`);
   const blockRow = (label: string, value: string) =>
     lines.push(`  ${label.padEnd(9)} ${value}`);
+  // A surface block: the surface type as a heading, then its items indented
+  // under it. Omitted entirely when the plugin contributes none of that type,
+  // so the listing only ever shows what the plugin actually contributes.
+  const surfaceBlock = (label: string, items: readonly string[]) => {
+    if (items.length === 0) return;
+    lines.push(label);
+    for (const item of items) lines.push(`  ${item}`);
+  };
 
   topRow("status", statusLine(status));
 
@@ -483,6 +790,12 @@ function formatInspection(inspection: PluginInspection): string[] {
   const description = remote?.description ?? local?.description ?? null;
   if (description) topRow("description", description);
 
+  if (surfaces) {
+    surfaceBlock("skills", surfaces.skills);
+    surfaceBlock("hooks", surfaces.hooks);
+    surfaceBlock("tools", surfaces.tools);
+  }
+
   for (const issue of local?.issues ?? []) topRow("issue", issue);
 
   return lines;
@@ -521,14 +834,87 @@ function formatUpgrade(result: PluginUpgradeResult): string[] {
         result.fileCount === null
           ? ""
           : `(${result.fileCount} file${result.fileCount === 1 ? "" : "s"}) `;
+      const hasConflicts =
+        result.conflicts.length > 0 || result.binaryConflicts.length > 0;
+
+      // Under `assistant`, an unresolved merge leaves conflicts in the tree —
+      // the plugin would fail to load while any remain, so the usual "restart
+      // now" guidance is replaced with resolution instructions. Most conflicts
+      // carry git markers, but a modify/delete divergence (a file edited on one
+      // side and deleted on the other) keeps the surviving content with no
+      // markers, so the guidance covers both rather than assuming markers.
+      if (result.strategy === "assistant" && hasConflicts) {
+        const lines = [
+          `Merged "${name}" ${move} with conflicts`,
+          "",
+          `${count}→ ${result.target}`,
+        ];
+        if (result.conflicts.length > 0) {
+          lines.push(
+            "",
+            `Resolve ${result.conflicts.length} conflicted file${result.conflicts.length === 1 ? "" : "s"} (open each: resolve its git conflict markers, or — if a modify/delete divergence kept the file with none — decide whether to keep or remove it):`,
+            ...result.conflicts.map((p) => `  ${p}`),
+          );
+        }
+        if (result.binaryConflicts.length > 0) {
+          lines.push(
+            "",
+            `Binary conflict${result.binaryConflicts.length === 1 ? "" : "s"} (kept the local copy — choose a version manually):`,
+            ...result.binaryConflicts.map((p) => `  ${p}`),
+          );
+        }
+        lines.push(
+          "",
+          "Resolve the conflicts, then restart the assistant to pick up the upgrade.",
+        );
+        if (provenanceNote) lines.push(provenanceNote);
+        return lines;
+      }
+
+      const mergeNote =
+        result.strategy === "ours" || result.strategy === "theirs"
+          ? `Local edits were merged (--strategy ${result.strategy}).`
+          : result.strategy === "assistant"
+            ? "Local edits were merged with no conflicts (--strategy assistant)."
+            : null;
       const lines = [
         `Upgraded "${name}" ${move}`,
         "",
         `${count}→ ${result.target}`,
         "Restart the assistant to pick up the upgrade.",
       ];
+      if (mergeNote) lines.push(mergeNote);
       if (provenanceNote) lines.push(provenanceNote);
       return lines;
     }
   }
 }
+
+/**
+ * Render a diff result: a one-line "no local changes" when clean, otherwise a
+ * header naming the install-commit baseline followed by each file's unified
+ * diff (blank-line separated, mirroring how `git diff` stacks file patches).
+ */
+function formatDiff(result: PluginDiffResult): string[] {
+  const baseline = `${formatTimestamp(result.committedAt)} (${shortSha(result.commit)})`;
+  if (result.clean) {
+    return [
+      `"${result.name}" has no local changes (matches install commit ${baseline}).`,
+    ];
+  }
+  const count = result.files.length;
+  const lines = [
+    `"${result.name}" — ${count} file${count === 1 ? "" : "s"} changed vs install commit ${baseline}`,
+    "",
+  ];
+  for (const file of result.files) {
+    // A non-reconstructed baseline carries an explanatory marker, not a patch
+    // with `a/`–`b/` headers, so name the file it refers to.
+    if (!file.reconstructed) {
+      lines.push(`${file.path}: ${file.diff.trimEnd()}`, "");
+      continue;
+    }
+    lines.push(file.diff.trimEnd(), "");
+  }
+  return lines;
+}