@vellumai/assistant 0.11.4-dev.202608201011.f81ab8d → 0.11.4-dev.202608201142.dc27263

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.11.4-dev.202608201011.f81ab8d",
+  "version": "0.11.4-dev.202608201142.dc27263",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/plugin-config-data-migration.test.ts

@@ -32,7 +32,10 @@ import {
   populateCacheAtBoot,
   resetPluginCacheForTests,
 } from "../plugins/mtime-cache.js";
-import { PRESERVED_ENTRIES } from "../plugins/plugin-tree-walk.js";
+import {
+  PRESERVED_ENTRIES,
+  USER_STATE_ENTRIES,
+} from "../plugins/plugin-tree-walk.js";
 
 const ROOT = join(
   tmpdir(),
@@ -87,6 +90,10 @@ describe("PRESERVED_ENTRIES", () => {
     expect(PRESERVED_ENTRIES).toContain("data");
     expect(PRESERVED_ENTRIES).toContain(".disabled");
   });
+
+  test("user-state entries are the preserved set minus the provenance sidecar", () => {
+    expect([...USER_STATE_ENTRIES]).toEqual(["config.json", "data", ".disabled"]);
+  });
 });
 
 describe("fingerprint exclusion of preserved entries", () => {

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

@@ -303,6 +303,44 @@ describe("installPlugin — install lifecycle", () => {
     expect(existsSync(join(target, "README.md"))).toBe(true);
   });
 
+  test("--force keeps live config.json instead of a pin-shipped default", async () => {
+    // GIVEN an install with user config, and a clone that materializes a default
+    const target = join(pluginsDir, "caveman");
+    mkdirSync(target, { recursive: true });
+    writeFileSync(join(target, "package.json"), '{"name":"caveman"}');
+    writeFileSync(
+      join(target, "config.json"),
+      '{"provider":"photon","ingressMode":"live"}\n',
+    );
+    mkdirSync(join(target, "data"), { recursive: true });
+    writeFileSync(join(target, "data", "cursor.json"), '{"n":1}\n');
+
+    const fetch = makeContentsFetch({ tree: {}, manifest: CAVEMAN_MANIFEST });
+    const runGit = fakeGitRunner({
+      tree: {
+        "package.json": '{"name":"caveman"}',
+        "README.md": "# caveman",
+        "config.json": '{"provider":"comms","ingressMode":"webhook"}\n',
+      },
+      commit: CAVEMAN_SHA,
+    });
+
+    // WHEN we reinstall with --force
+    await installPlugin(
+      { name: "caveman", force: true, ref: "main" },
+      { fetch, runGit, workspacePluginsDir: pluginsDir },
+    );
+
+    // THEN user-owned state survives and the pin's default config does not win
+    expect(readFileSync(join(target, "config.json"), "utf-8")).toBe(
+      '{"provider":"photon","ingressMode":"live"}\n',
+    );
+    expect(readFileSync(join(target, "data", "cursor.json"), "utf-8")).toBe(
+      '{"n":1}\n',
+    );
+    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);

package/src/cli/lib/__tests__/merge-plugin-tree.test.ts

@@ -440,4 +440,38 @@ describe("mergePluginTree", () => {
     expect(result.conflicts).toEqual(["f.txt"]);
     expect(result.binaryConflicts).toEqual([]);
   });
+
+  test("copies live config.json, data/, and .disabled from ours, ignoring the pin", async () => {
+    // GIVEN user-owned state on the live install and different defaults at the pin
+    writeTree(baseDir, { "package.json": '{"name":"p"}\n' });
+    writeTree(oursDir, {
+      "package.json": '{"name":"p"}\n',
+      "config.json": '{"provider":"photon","ingressMode":"live"}\n',
+      "data/cursor.json": '{"n":1}\n',
+      ".disabled": "",
+    });
+    writeTree(theirsDir, {
+      "package.json": '{"name":"p"}\n',
+      "config.json": '{"provider":"comms","ingressMode":"webhook"}\n',
+      "data/cursor.json": '{"n":0}\n',
+    });
+
+    // WHEN merged with theirs (the strategy that would otherwise take the pin)
+    const result = await mergePluginTree({
+      baseDir,
+      oursDir,
+      theirsDir,
+      destDir,
+      strategy: "theirs",
+    });
+
+    // THEN user-owned state is the live copy, not the pin, and is not counted
+    // as a merged source file
+    expect(read("config.json")).toBe(
+      '{"provider":"photon","ingressMode":"live"}\n',
+    );
+    expect(read("data/cursor.json")).toBe('{"n":1}\n');
+    expect(read(".disabled")).toBe("");
+    expect(result.fileCount).toBe(1);
+  });
 });

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

@@ -920,6 +920,70 @@ describe("upgradePlugin --strategy", () => {
     expect(installedFile("level-up", "local-only.txt")).toBeNull();
   });
 
+  test("keeps live config.json, data/, and .disabled under overwrite, theirs, and ours", async () => {
+    // GIVEN user-owned state on the live install, and a pin that ships defaults
+    const userConfig = '{"provider":"photon","ingressMode":"live"}\n';
+    const pinConfig = '{"provider":"comms","ingressMode":"webhook"}\n';
+    const liveOurs: Tree = {
+      ...OURS,
+      "config.json": userConfig,
+      "data/cursor.json": '{"n":1}\n',
+      ".disabled": "",
+    };
+    const pinTheirs: Tree = {
+      ...THEIRS,
+      "config.json": pinConfig,
+      "data/cursor.json": '{"n":0}\n',
+    };
+
+    for (const strategy of ["overwrite", "theirs", "ours"] as const) {
+      rmSync(join(pluginsDir, "level-up"), { recursive: true, force: true });
+      installMergeCopy("level-up", liveOurs, SHA_A, BASE);
+      const fetch = makeFetch({ manifest: manifestWith("level-up", SHA_B) });
+      const runGit = treeGitRunner({
+        [SHA_A]: BASE,
+        [SHA_B]: pinTheirs,
+      });
+
+      // WHEN the plugin is upgraded
+      const result = await upgradePlugin(
+        { name: "level-up", strategy },
+        { fetch, runGit, workspacePluginsDir: pluginsDir },
+      );
+
+      // THEN user-owned state is unchanged, including under `theirs` and
+      // overwrite, which would otherwise take the pin wholesale
+      expect(result.outcome).toBe("upgraded");
+      expect(installedFile("level-up", "config.json")).toBe(userConfig);
+      expect(installedFile("level-up", "data/cursor.json")).toBe('{"n":1}\n');
+      expect(existsSync(join(pluginsDir, "level-up", ".disabled"))).toBe(true);
+    }
+  });
+
+  test("does not seed config.json from the pin when the live install has none", async () => {
+    // GIVEN an install with no config.json, and a pin that ships defaults
+    installMergeCopy("level-up", OURS, SHA_A, BASE);
+    const fetch = makeFetch({ manifest: manifestWith("level-up", SHA_B) });
+    const runGit = treeGitRunner({
+      [SHA_A]: BASE,
+      [SHA_B]: {
+        ...THEIRS,
+        "config.json": '{"provider":"comms","ingressMode":"webhook"}\n',
+      },
+    });
+
+    // WHEN upgraded (overwrite materializes the pin tree directly)
+    const result = await upgradePlugin(
+      { name: "level-up", strategy: "overwrite" },
+      { fetch, runGit, workspacePluginsDir: pluginsDir },
+    );
+
+    // THEN the pin's config.json does not land: host-owned config is created
+    // by the plugin at runtime, not by the installer
+    expect(result.outcome).toBe("upgraded");
+    expect(installedFile("level-up", "config.json")).toBeNull();
+  });
+
   test("defaults to overwrite when no strategy is given", async () => {
     // GIVEN an install with a local-only file and an advanced pin
     installMergeCopy("level-up", OURS, SHA_A, BASE);

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

@@ -26,7 +26,6 @@
 import { execFile } from "node:child_process";
 import {
   copyFileSync,
-  cpSync,
   existsSync,
   mkdirSync,
   readdirSync,
@@ -40,7 +39,12 @@ import { tmpdir } from "node:os";
 import { dirname, join, resolve, sep } from "node:path";
 import { promisify } from "node:util";
 
-import { PRESERVED_ENTRIES } from "../../plugins/plugin-tree-walk.js";
+import {
+  copyPreservedUserState,
+  isPluginUserStateEntry,
+  PRESERVED_ENTRIES,
+  stripPreservedUserState,
+} from "../../plugins/plugin-tree-walk.js";
 import { ensureBun } from "../../util/bun-runtime.js";
 import { getWorkspacePluginsDir } from "../../util/platform.js";
 import type { FetchLike } from "./fetch-like.js";
@@ -687,27 +691,13 @@ export async function finalizeStagedInstall(
     }
   }
 
-  // Copy preserved entries (config.json, data/, .disabled) from the existing
-  // install into the staging dir before the swap so user-owned state survives
-  // upgrades and reinstalls. Without this, the rm+rename below would destroy
-  // user config and runtime data.
+  // User-owned state (config.json, data/, .disabled) is not plugin source.
+  // Drop any copy the pin materialized into staging, then copy the live
+  // install's bytes over so an upgrade cannot reset user config to pin
+  // defaults. Without the live copy, the rm+rename below would destroy it.
+  stripPreservedUserState(stagingDir);
   if (existsSync(target)) {
-    for (const entry of PRESERVED_ENTRIES) {
-      if (entry === INSTALL_META_FILENAME) {
-        continue;
-      } // sidecar is rewritten above
-      const src = join(target, entry);
-      if (!existsSync(src)) {
-        continue;
-      }
-      const dest = join(stagingDir, entry);
-      const stat = statSync(src);
-      if (stat.isDirectory()) {
-        cpSync(src, dest, { recursive: true });
-      } else {
-        copyFileSync(src, dest);
-      }
-    }
+    copyPreservedUserState(target, stagingDir);
     rmSync(target, { recursive: true, force: true });
   }
   renameSync(stagingDir, target);
@@ -1287,7 +1277,8 @@ function pluginPostinstallEnv(bun: string): NodeJS.ProcessEnv {
 
 /**
  * Recursively copy regular files from `srcRoot` into `destDir`, skipping the
- * top-level `.git` directory, a top-level `bunfig.toml` (see below), and any
+ * top-level `.git` directory, a top-level `bunfig.toml` (see below), top-level
+ * user-state entries (`config.json`, `data/`, `.disabled`), and any
  * symlinks. Returns the file count.
  */
 function copyTreeSkippingGit(srcRoot: string, destDir: string): number {
@@ -1300,6 +1291,12 @@ function copyTreeSkippingGit(srcRoot: string, destDir: string): number {
       if (relDir === "" && entry.name === ".git") {
         continue;
       }
+      // Runtime-owned state is not plugin source. A pin that ships
+      // `config.json` or `data/` must not land in the staged tree, or an
+      // upgrade would reset user config to whatever the revision committed.
+      if (relDir === "" && isPluginUserStateEntry(entry.name)) {
+        continue;
+      }
       // Drop a top-level `bunfig.toml`. The adapter postinstall runs `bun` with
       // its cwd at the staged root, and Bun auto-loads `$cwd/bunfig.toml` as
       // project config — including a `preload` list it executes before the
@@ -1712,6 +1709,7 @@ async function copyDir(
   ref: string,
   destDir: string,
   fetchFn: FetchLike,
+  atPluginRoot = true,
 ): Promise<number> {
   const entries = await listDir(owner, repo, apiPath, ref, fetchFn);
   if (entries === null) {
@@ -1725,11 +1723,24 @@ async function copyDir(
       continue;
     }
     assertSafeFilename("entry name", entry.name);
+    // Adapter stubs overlay the plugin root. User-state names at that root
+    // are host-owned, not adapter input.
+    if (atPluginRoot && isPluginUserStateEntry(entry.name)) {
+      continue;
+    }
 
     if (entry.type === "dir") {
       const subDest = join(destDir, entry.name);
       mkdirSync(subDest, { recursive: true });
-      count += await copyDir(owner, repo, entry.path, ref, subDest, fetchFn);
+      count += await copyDir(
+        owner,
+        repo,
+        entry.path,
+        ref,
+        subDest,
+        fetchFn,
+        false,
+      );
       continue;
     }
 

package/src/cli/lib/merge-plugin-tree.ts

@@ -23,6 +23,13 @@
  * one side) is resolved here before any line merge, since `git merge-file`
  * operates on three existing blobs.
  *
+ * Runtime-owned user state (`config.json`, `data/`, `.disabled`) is never
+ * merged. Those paths are excluded from the fingerprints and copied from the
+ * live install (`ours`) into the destination after the source merge, so a
+ * pin that ships default config cannot reset user settings. The provenance
+ * sidecar is excluded on every side and rewritten by the caller after the swap.
+ *
+ *
  * Binary files cannot be line-merged, so a binary file that diverged on both
  * sides is resolved whole-file by the strategy (`ours`/`theirs`); under
  * `assistant` the local copy is kept and the path is reported as a binary
@@ -44,7 +51,10 @@ import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { promisify } from "node:util";
 
-import { PRESERVED_ENTRIES } from "../../plugins/plugin-tree-walk.js";
+import {
+  copyPreservedUserState,
+  PRESERVED_ENTRIES,
+} from "../../plugins/plugin-tree-walk.js";
 import { computeFingerprint } from "./plugin-fingerprint.js";
 
 const execFileAsync = promisify(execFile);
@@ -230,9 +240,11 @@ async function threeWayMergeFile(
 
 /**
  * Three-way merge `oursDir`/`theirsDir` against `baseDir` into `destDir` per
- * `strategy`. The provenance sidecar is excluded on every side — it is
- * rewritten by the caller after the swap and must not be carried through the
- * merge.
+ * `strategy`. User-owned state (`config.json`, `data/`, `.disabled`) is
+ * excluded from the line merge and copied from `oursDir` afterward, so the
+ * pin cannot reset it. The provenance sidecar is excluded on every side — it
+ * is rewritten by the caller after the swap and must not be carried through
+ * the merge.
  *
  * Returns the file count plus, for the `assistant` strategy, the paths left for
  * the assistant to resolve (text files with conflict markers and modify/delete
@@ -332,5 +344,11 @@ export async function mergePluginTree({
     // Present only in the base: removed on both sides, so it stays removed.
   }
 
+  // User-owned state is not plugin source, so it is never a merge input.
+  // Copy it from the live install so `--strategy theirs` cannot take a
+  // pin-shipped `config.json` (or drop an untracked one the fingerprint
+  // walk never saw).
+  copyPreservedUserState(oursDir, destDir);
+
   return { fileCount, conflicts, binaryConflicts };
 }

package/src/plugins/plugin-tree-walk.ts

@@ -15,9 +15,30 @@
  * root (`realpathSync`) before walking.
  */
 
-import { readdirSync } from "node:fs";
+import {
+  copyFileSync,
+  cpSync,
+  existsSync,
+  readdirSync,
+  rmSync,
+  statSync,
+} from "node:fs";
 import { join } from "node:path";
 
+/**
+ * Top-level runtime-owned entries that belong to the live install, not the
+ * plugin's source tree. An upgrade must never take these from the incoming
+ * pin: `config.json` is user-edited, `data/` is whatever the plugin wrote at
+ * runtime, and `.disabled` is created by `assistant plugins disable`.
+ *
+ * The provenance sidecar is not in this list. Install rewrites `install-meta.json`
+ * at the swap boundary; carrying the outgoing copy forward would pin the
+ * upgrade to the previous commit.
+ */
+export const USER_STATE_ENTRIES = ["config.json", "data", ".disabled"] as const;
+
+const USER_STATE_NAME_SET: ReadonlySet<string> = new Set(USER_STATE_ENTRIES);
+
 /**
  * Top-level entries that are preserved across upgrades and excluded from
  * fingerprinting / drift detection / content hashing. These are runtime-owned
@@ -35,11 +56,49 @@ import { join } from "node:path";
  */
 export const PRESERVED_ENTRIES = [
   "install-meta.json",
-  "config.json",
-  "data",
-  ".disabled",
+  ...USER_STATE_ENTRIES,
 ] as const;
 
+/** True when `name` is a top-level user-state entry (`config.json`, `data`, `.disabled`). */
+export function isPluginUserStateEntry(name: string): boolean {
+  return USER_STATE_NAME_SET.has(name);
+}
+
+/**
+ * Remove user-state entries from `dir` so a pin-shipped `config.json` or
+ * `data/` cannot ride the swap. No-op when those paths are already absent.
+ */
+export function stripPreservedUserState(dir: string): void {
+  for (const entry of USER_STATE_ENTRIES) {
+    rmSync(join(dir, entry), { recursive: true, force: true });
+  }
+}
+
+/**
+ * Copy live user-state (`config.json`, `data/`, `.disabled`) from `fromDir`
+ * into `toDir`, replacing any copy already at the destination so the live
+ * bytes win whole-file / whole-tree.
+ */
+export function copyPreservedUserState(fromDir: string, toDir: string): void {
+  if (!existsSync(fromDir)) {
+    return;
+  }
+  for (const entry of USER_STATE_ENTRIES) {
+    const src = join(fromDir, entry);
+    if (!existsSync(src)) {
+      continue;
+    }
+    const dest = join(toDir, entry);
+    rmSync(dest, { recursive: true, force: true });
+    const stat = statSync(src);
+    if (stat.isDirectory()) {
+      cpSync(src, dest, { recursive: true });
+    } else {
+      copyFileSync(src, dest);
+    }
+  }
+}
+
 /**
  * Directory names {@link walkPluginTree} skips at any depth, unconditionally.
  * `node_modules` holds a plugin's installed dependencies — derived from the