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

package/src/cli/lib/plugin-surfaces.ts

@@ -0,0 +1,104 @@
+/**
+ * Detect the surfaces an installed plugin contributes to the running assistant,
+ * read directly from its on-disk tree.
+ *
+ * The host discovers a plugin's contributions from fixed directory conventions:
+ *
+ * - `hooks/<name>.{ts,js}`     → a lifecycle hook keyed by the file basename
+ *                                (see the external plugin loader's `loadHooks`).
+ * - `tools/<name>.{ts,js}`     → a tool, also keyed by the file basename
+ *                                (see the external plugin loader's tool walk).
+ * - `skills/<id>/SKILL.md`     → a skill owned by the plugin (see the skills
+ *                                catalog's `discoverPluginResidentSkills`).
+ *
+ * This module re-derives those same sets so `plugins inspect` can report exactly
+ * what a plugin contributes. Detection is intentionally a self-contained walk of
+ * the install tree — `cli/lib` does not reach into the daemon-internal loader or
+ * skills catalog — but it mirrors their conventions so inspect agrees with what
+ * the runtime actually loads.
+ */
+
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+/** The surfaces an installed plugin contributes, each sorted and de-duplicated. */
+export interface PluginSurfaces {
+  /** Skill ids shipped at `skills/<id>/SKILL.md`. */
+  readonly skills: readonly string[];
+  /** Lifecycle hook names from `hooks/<name>.{ts,js}` (e.g. `pre-model-call`). */
+  readonly hooks: readonly string[];
+  /**
+   * Registered tool names from `tools/<name>.{ts,js}`. The loader derives a
+   * tool's name from its filename via {@link deriveToolName} (e.g.
+   * `create-issue.ts` registers as `create_issue`), so the derived form is
+   * reported rather than the raw basename. A tool module that overrides its own
+   * name via an exported `name` is not reflected here: that would require
+   * importing and executing untrusted plugin code, which inspection avoids.
+   */
+  readonly tools: readonly string[];
+}
+
+/**
+ * Derive a tool's registered name from its file basename, mirroring the
+ * external plugin loader's `deriveToolName`: non-alphanumeric runs collapse to
+ * `_`, leading/trailing `_` are trimmed, and an empty result falls back to
+ * `tool`. Keeps the inspected tool name aligned with the callable tool name.
+ */
+function deriveToolName(basename: string): string {
+  return (
+    basename.replace(/[^a-zA-Z0-9]+/g, "_").replace(/^_+|_+$/g, "") || "tool"
+  );
+}
+
+/**
+ * List the basenames of every `.ts`/`.js` module directly under `dir`,
+ * preferring `.js` over `.ts` for the same basename (compiled-binary semantics)
+ * and skipping `.d.ts` declaration files. Returns names sorted for a
+ * deterministic listing. A missing or non-directory path yields `[]`.
+ *
+ * Mirrors the external plugin loader's `listSurfaceDir`, the gate it uses to
+ * turn a `hooks/`/`tools/` directory into loadable surfaces.
+ */
+function listModuleBasenames(dir: string): string[] {
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) return [];
+  const bases = new Set<string>();
+  for (const entry of readdirSync(dir)) {
+    if (entry.endsWith(".d.ts")) continue;
+    if (!entry.endsWith(".ts") && !entry.endsWith(".js")) continue;
+    bases.add(entry.slice(0, -3));
+  }
+  return [...bases].sort();
+}
+
+/**
+ * List the skill ids a plugin ships: each subdirectory of `skills/` that
+ * contains a `SKILL.md`. Mirrors the skills catalog's plugin-resident skill
+ * discovery so inspect reports the same set the runtime would surface.
+ */
+function listSkillIds(skillsDir: string): string[] {
+  if (!existsSync(skillsDir) || !statSync(skillsDir).isDirectory()) return [];
+  const ids: string[] = [];
+  for (const entry of readdirSync(skillsDir, { withFileTypes: true })) {
+    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+    if (existsSync(join(skillsDir, entry.name, "SKILL.md"))) {
+      ids.push(entry.name);
+    }
+  }
+  return ids.sort();
+}
+
+/**
+ * Detect the {@link PluginSurfaces} an installed plugin contributes by walking
+ * its install tree at `pluginDir`. Surface types with no contributions come
+ * back as empty arrays; callers omit empty types from the rendered output.
+ */
+export function detectPluginSurfaces(pluginDir: string): PluginSurfaces {
+  const toolNames = listModuleBasenames(join(pluginDir, "tools")).map(
+    deriveToolName,
+  );
+  return {
+    skills: listSkillIds(join(pluginDir, "skills")),
+    hooks: listModuleBasenames(join(pluginDir, "hooks")),
+    tools: [...new Set(toolNames)].sort(),
+  };
+}

package/src/cli/lib/upgrade-plugin.ts

@@ -10,14 +10,17 @@
  * This is deliberately a distinct operation from install: `install` is
  * first-time materialization (and errors on an existing install unless
  * `--force` is passed), whereas `upgrade` moves an existing install forward.
- * Mechanically the move is a forced re-install at the current pin, which the
- * underlying {@link ./install-from-github.installPlugin} performs atomically —
- * the previously installed copy is preserved until the fetch succeeds.
  *
- * Conflict resolution for locally-modified plugins is intentionally out of
- * scope here: this overwrites the install with the pinned tree. A future
- * iteration will detect local edits (installed SHA = merge base) and resolve
- * them before the swap.
+ * How local edits are reconciled with the pin is controlled by the
+ * {@link PluginUpgradeStrategy}. `overwrite` (the default) moves via a forced
+ * re-install at the current pin — the underlying
+ * {@link ./install-from-github.installPlugin} performs that atomically, and the
+ * previously installed copy (including any local edits) is replaced wholesale.
+ * `ours`/`theirs`/`assistant` instead three-way merge the on-disk tree and the
+ * pin against the re-materialized install commit so non-conflicting local edits
+ * survive; conflicting hunks resolve toward the local edit (`ours`) or the pin
+ * (`theirs`), while `assistant` writes git conflict markers into the file and
+ * reports the conflicted paths for the assistant to resolve.
  *
  * Designed for direct programmatic use with injected dependencies, mirroring
  * the sibling plugin libraries. The CLI command `assistant plugins upgrade
@@ -25,24 +28,66 @@
  * result.
  */
 
-import { join } from "node:path";
+import { existsSync, mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
 
 import { getWorkspacePluginsDir } from "../../util/platform.js";
 import {
   inspectPlugin,
   type PluginInspection,
   PluginInspectNotFoundError,
+  type PluginLocalInfo,
+  type PluginRemoteInfo,
 } from "./inspect-plugin.js";
 import {
+  DEFAULT_PLUGIN_REF,
   type FetchLike,
+  finalizeStagedInstall,
   type GitRunner,
+  INSTALL_META_FILENAME,
   installPlugin,
+  materializePluginTree,
+  type PluginFetchSource,
+  PluginNotFoundError,
   PluginSourceUnavailableError,
   type PostinstallRunner,
+  readInstallMeta,
   sanitizePluginName,
 } from "./install-from-github.js";
+import { type ConflictLabels, mergePluginTree } from "./merge-plugin-tree.js";
+import { computeFingerprint, fingerprintsEqual } from "./plugin-fingerprint.js";
 import { PluginNotInstalledError } from "./uninstall-plugin.js";
 
+/**
+ * How local edits to an installed plugin are reconciled with the marketplace
+ * pin during an upgrade.
+ *
+ * - `overwrite` (default) — discard all local edits and re-install the pin
+ *   wholesale. Matches the historical upgrade behavior.
+ * - `ours` — three-way merge; conflicting hunks resolve toward the local edit.
+ * - `theirs` — three-way merge; conflicting hunks resolve toward the pin.
+ * - `assistant` — three-way merge that writes git conflict markers into
+ *   conflicting files and reports them for the assistant to resolve.
+ */
+export type PluginUpgradeStrategy =
+  | "ours"
+  | "theirs"
+  | "overwrite"
+  | "assistant";
+
+/** The set of accepted `--strategy` values, for validation and help text. */
+export const PLUGIN_UPGRADE_STRATEGIES: readonly PluginUpgradeStrategy[] = [
+  "ours",
+  "theirs",
+  "overwrite",
+  "assistant",
+];
+
+/** The strategy applied when a caller omits `--strategy`. */
+export const DEFAULT_PLUGIN_UPGRADE_STRATEGY: PluginUpgradeStrategy =
+  "overwrite";
+
 /**
  * Outcome of an upgrade attempt.
  *
@@ -61,6 +106,11 @@ export interface UpgradePluginOptions {
   readonly name: string;
   /** Report what would change without modifying the install. */
   readonly dryRun?: boolean;
+  /**
+   * How to reconcile local edits with the pin. Defaults to
+   * {@link DEFAULT_PLUGIN_UPGRADE_STRATEGY}.
+   */
+  readonly strategy?: PluginUpgradeStrategy;
 }
 
 /** Dependencies injected by the caller. */
@@ -99,6 +149,21 @@ export interface PluginUpgradeResult {
   readonly fileCount: number | null;
   /** Whether this was a dry run (no changes made). */
   readonly dryRun: boolean;
+  /** Conflict-resolution strategy the upgrade applied. */
+  readonly strategy: PluginUpgradeStrategy;
+  /**
+   * Paths (relative to {@link PluginUpgradeResult.target}) left for the
+   * assistant to resolve under the `assistant` strategy: text files carry git
+   * conflict markers, modify/delete divergences keep the surviving content.
+   * Always empty for other strategies.
+   */
+  readonly conflicts: readonly string[];
+  /**
+   * Paths of binary files that conflicted under the `assistant` strategy; the
+   * local copy was kept since markers cannot be written into binary content.
+   * Always empty for other strategies.
+   */
+  readonly binaryConflicts: readonly string[];
   /**
    * Whether the installed copy lacked resolvable provenance before the
    * upgrade. Such installs are re-pinned to the current SHA, which also
@@ -118,6 +183,22 @@ export class PluginNotUpgradableError extends Error {
   }
 }
 
+/**
+ * A merge strategy (`ours`/`theirs`) was requested but the install-time
+ * baseline needed for a three-way merge cannot be reconstructed.
+ */
+export class PluginMergeBaselineError extends Error {
+  constructor(
+    readonly pluginName: string,
+    reason: string,
+  ) {
+    super(
+      `Plugin "${pluginName}" cannot be merge-upgraded: ${reason}. Use '--strategy overwrite' to take the pin wholesale, or reinstall with 'plugins install ${pluginName} --force'.`,
+    );
+    this.name = "PluginMergeBaselineError";
+  }
+}
+
 function pluginTarget(name: string, deps: UpgradePluginDeps): string {
   const dir = deps.workspacePluginsDir ?? getWorkspacePluginsDir();
   return join(dir, name);
@@ -126,10 +207,19 @@ function pluginTarget(name: string, deps: UpgradePluginDeps): string {
 /**
  * Move an installed plugin to the marketplace's current pin.
  *
+ * The `strategy` controls how local edits are reconciled with the pin:
+ * `overwrite` (default) re-installs the pin wholesale; `ours`/`theirs`/
+ * `assistant` do a three-way merge that carries non-conflicting local edits
+ * forward, resolving conflicting hunks toward the local edit (`ours`) or the
+ * pin (`theirs`), or leaving git conflict markers in the file for the assistant
+ * to resolve (`assistant`).
+ *
  * Throws {@link PluginNotInstalledError} when no copy is installed,
  * {@link PluginNotUpgradableError} when the install has no marketplace entry to
- * advance to, {@link PluginSourceUnavailableError} when the marketplace catalog
- * is temporarily unreachable (a retryable outage, distinct from the permanent
+ * advance to, {@link PluginMergeBaselineError} when a merge strategy is
+ * requested but the install-time baseline cannot be reconstructed,
+ * {@link PluginSourceUnavailableError} when the marketplace catalog is
+ * temporarily unreachable (a retryable outage, distinct from the permanent
  * no-entry case), and propagates {@link installPlugin}'s errors (e.g. source
  * unavailable, postinstall failure) when the re-install itself fails.
  */
@@ -139,6 +229,7 @@ export async function upgradePlugin(
 ): Promise<PluginUpgradeResult> {
   const name = sanitizePluginName(opts.name);
   const dryRun = opts.dryRun ?? false;
+  const strategy = opts.strategy ?? DEFAULT_PLUGIN_UPGRADE_STRATEGY;
 
   let inspection: PluginInspection;
   try {
@@ -199,6 +290,9 @@ export async function upgradePlugin(
       target: local.target,
       fileCount: null,
       dryRun,
+      strategy,
+      conflicts: [],
+      binaryConflicts: [],
       provenanceWasUnknown: false,
     };
   }
@@ -214,10 +308,37 @@ export async function upgradePlugin(
       target: local.target,
       fileCount: null,
       dryRun: true,
+      strategy,
+      conflicts: [],
+      binaryConflicts: [],
       provenanceWasUnknown,
     };
   }
 
+  // `ours`/`theirs`/`assistant` carry local edits forward via a three-way
+  // merge; the default `overwrite` discards them and re-installs the pin
+  // wholesale.
+  if (
+    strategy === "ours" ||
+    strategy === "theirs" ||
+    strategy === "assistant"
+  ) {
+    return mergeUpgrade(
+      {
+        name,
+        strategy,
+        local,
+        remote,
+        fromCommit,
+        fromTimestamp,
+        toCommit,
+        toTimestamp,
+        provenanceWasUnknown,
+      },
+      deps,
+    );
+  }
+
   const result = await installPlugin(
     { name, force: true },
     {
@@ -238,6 +359,173 @@ export async function upgradePlugin(
     target: result.target,
     fileCount: result.fileCount,
     dryRun: false,
+    strategy,
+    conflicts: [],
+    binaryConflicts: [],
     provenanceWasUnknown,
   };
 }
+
+/**
+ * Carry local edits forward by three-way merging the on-disk install (`ours`)
+ * and the marketplace pin (`theirs`) against the re-materialized install commit
+ * (`base`), then atomically swapping the merged tree into place pinned at the
+ * new commit. Conflicting hunks resolve toward `ours` or `theirs` per the
+ * strategy, or are left as git conflict markers under `assistant`;
+ * non-conflicting edits from both sides survive.
+ */
+async function mergeUpgrade(
+  ctx: {
+    readonly name: string;
+    readonly strategy: "ours" | "theirs" | "assistant";
+    readonly local: PluginLocalInfo;
+    readonly remote: PluginRemoteInfo;
+    readonly fromCommit: string | null;
+    readonly fromTimestamp: string | null;
+    readonly toCommit: string;
+    readonly toTimestamp: string | null;
+    readonly provenanceWasUnknown: boolean;
+  },
+  deps: UpgradePluginDeps,
+): Promise<PluginUpgradeResult> {
+  const { name, strategy, local, remote } = ctx;
+
+  // Marker labels name each side by its commit so the assistant can tell the
+  // local edit from the incoming pin when resolving.
+  const shortSha = (sha: string | null): string =>
+    sha ? sha.slice(0, 7) : "unknown";
+  const conflictLabels: ConflictLabels = {
+    ours: `local edits (was ${shortSha(ctx.fromCommit)})`,
+    base: `install baseline ${shortSha(ctx.fromCommit)}`,
+    theirs: `upgrade pin ${shortSha(ctx.toCommit)}`,
+  };
+
+  const meta = readInstallMeta(local.target);
+  if (!meta || !meta.commit || !meta.fingerprint) {
+    throw new PluginMergeBaselineError(
+      name,
+      "no install commit or fingerprint was recorded (an older or manually-copied install)",
+    );
+  }
+  const recorded = meta.fingerprint;
+
+  const baseSource: PluginFetchSource = {
+    owner: meta.source.owner,
+    repo: meta.source.repo,
+    rootPath: meta.source.path ?? "",
+    ref: meta.commit,
+  };
+  const [remoteOwner, remoteRepo] = remote.repo.split("/");
+  const theirsSource: PluginFetchSource = {
+    owner: remoteOwner ?? "",
+    repo: remoteRepo ?? "",
+    rootPath: remote.path,
+    ref: remote.commit,
+  };
+
+  const pluginsDir = deps.workspacePluginsDir ?? getWorkspacePluginsDir();
+  const baseDir = mkdtempSync(join(tmpdir(), `plugin-upgrade-base-${name}-`));
+  const theirsDir = mkdtempSync(
+    join(tmpdir(), `plugin-upgrade-theirs-${name}-`),
+  );
+  // Stage outside the served `plugins/` directory and on its filesystem so the
+  // final swap is an atomic rename, mirroring `installPlugin`.
+  const stagingRoot = join(dirname(pluginsDir), ".plugins-staging");
+  mkdirSync(stagingRoot, { recursive: true });
+  const stagingDir = join(stagingRoot, `${name}.upgrading.${process.pid}`);
+  if (existsSync(stagingDir)) {
+    rmSync(stagingDir, { recursive: true, force: true });
+  }
+  mkdirSync(stagingDir, { recursive: true });
+
+  try {
+    const base = await materializePluginTree(
+      {
+        source: baseSource,
+        name,
+        stubRef: DEFAULT_PLUGIN_REF,
+        destDir: baseDir,
+      },
+      deps,
+    );
+    if (base.fileCount === 0) {
+      throw new PluginNotFoundError(
+        name,
+        baseSource.ref,
+        `${baseSource.owner}/${baseSource.repo}`,
+      );
+    }
+    // The merge base must faithfully reproduce what install materialized;
+    // otherwise a curated adapter overlay that moved since install would read
+    // as base→ours/theirs edits and corrupt the merge. Verify against the
+    // recorded fingerprint, exactly as `plugins diff` does.
+    const baseFingerprint = computeFingerprint(baseDir, [
+      INSTALL_META_FILENAME,
+    ]);
+    if (!fingerprintsEqual(baseFingerprint, recorded)) {
+      throw new PluginMergeBaselineError(
+        name,
+        "the install-time baseline could not be faithfully reconstructed (a curated adapter overlay it was built from has changed since install)",
+      );
+    }
+
+    const theirs = await materializePluginTree(
+      {
+        source: theirsSource,
+        name,
+        stubRef: remote.marketplaceRef,
+        destDir: theirsDir,
+      },
+      deps,
+    );
+    if (theirs.fileCount === 0) {
+      throw new PluginNotFoundError(
+        name,
+        theirsSource.ref,
+        `${theirsSource.owner}/${theirsSource.repo}`,
+      );
+    }
+
+    const merge = await mergePluginTree({
+      baseDir,
+      oursDir: local.target,
+      theirsDir,
+      destDir: stagingDir,
+      strategy,
+      conflictLabels,
+    });
+
+    const toCommit = theirs.commit ?? remote.commit;
+    const toTimestamp = theirs.committedAt ?? remote.committedAt;
+    finalizeStagedInstall(stagingDir, {
+      name,
+      source: theirsSource,
+      ref: theirsSource.ref,
+      commit: toCommit,
+      committedAt: toTimestamp,
+      pluginsDir,
+    });
+
+    return {
+      name,
+      outcome: "upgraded",
+      fromCommit: ctx.fromCommit,
+      fromTimestamp: ctx.fromTimestamp,
+      toCommit,
+      toTimestamp,
+      target: join(pluginsDir, name),
+      fileCount: merge.fileCount,
+      dryRun: false,
+      strategy,
+      conflicts: merge.conflicts,
+      binaryConflicts: merge.binaryConflicts,
+      provenanceWasUnknown: ctx.provenanceWasUnknown,
+    };
+  } catch (err) {
+    rmSync(stagingDir, { recursive: true, force: true });
+    throw err;
+  } finally {
+    rmSync(baseDir, { recursive: true, force: true });
+    rmSync(theirsDir, { recursive: true, force: true });
+  }
+}

package/src/cli/program.ts

@@ -34,8 +34,7 @@ import { registerImageGenerationCommand } from "./commands/image-generation.js";
 import { registerInferenceCommand } from "./commands/inference.js";
 import { registerKeysCommand } from "./commands/keys.js";
 import { registerMcpCommand } from "./commands/mcp.js";
-import { registerMemoryV2Command } from "./commands/memory-v2.js";
-import { registerMemoryV3Command } from "./commands/memory-v3.js";
+import { registerMemoryCommand } from "./commands/memory/index.js";
 import { registerNotificationsCommand } from "./commands/notifications.js";
 import { registerOAuthCommand } from "./commands/oauth/index.js";
 import { registerPendingCommand } from "./commands/pending.js";
@@ -47,7 +46,6 @@ import { registerSequenceCommand } from "./commands/sequence.js";
 import { registerSkillsCommand } from "./commands/skills.js";
 import { registerStatusCommand } from "./commands/status.js";
 import { registerSttCommand } from "./commands/stt.js";
-import { registerTaskCommand } from "./commands/task.js";
 import { registerTelemetryCommand } from "./commands/telemetry.js";
 import { registerToolsCommand } from "./commands/tools.js";
 import { registerTrustCommand } from "./commands/trust.js";
@@ -131,8 +129,7 @@ Examples:
   registerInferenceCommand(program);
   registerKeysCommand(program);
   registerMcpCommand(program);
-  registerMemoryV2Command(program);
-  registerMemoryV3Command(program);
+  registerMemoryCommand(program);
   registerNotificationsCommand(program);
   registerOAuthCommand(program);
   registerPendingCommand(program);
@@ -146,7 +143,6 @@ Examples:
   registerStatusCommand(program);
   registerSkillsCommand(program);
   registerSttCommand(program);
-  registerTaskCommand(program);
   registerTelemetryCommand(program);
   registerToolsCommand(program);
   registerTrustCommand(program);