ccprofiles-core 0.7.3 → 0.8.1

package/dist/discovery.d.ts

@@ -14,9 +14,30 @@ export interface LiveProfile {
      *  for "present". enabledPlugins alone can be stale: an enabled-but-never-installed entry
      *  (e.g. written by the retired union-sharing feature) must still trigger an install. */
     installedPlugins: string[];
+    /** Comparable installed version per plugin id — a release version where there is one, else the
+     *  git sha (see readInstalledPluginVersions for why those are interchangeable here). Ids with no
+     *  version at all are absent. Feeds cross-profile drift detection (planPluginVersionDrift). */
+    installedPluginVersions: Record<string, string>;
     marketplaces: Record<string, {
         source: string;
     }>;
 }
+/**
+ * Pull a comparable installed version out of each entry of installed_plugins.json's `plugins` map.
+ * The value is an ARRAY of install records (one per scope), not an object.
+ *
+ * ONLY a real release `version` counts. `gitCommitSha` looks like a tempting fallback for the
+ * versionless plugins (Claude Code writes `"version": "unknown"` for those) but it is unusable as
+ * an identity, and comparing it produced drift that `fix` could never clear:
+ *  - it is the sha of the whole MARKETPLACE repo, not of the plugin — two profiles whose plugin
+ *    files are byte-identical still hold different shas if they installed at different times
+ *  - Claude Code never refreshes it when `claude plugin update` finds nothing to do, so the stale
+ *    value outlives every update. Seen on a real machine: context7 at 205b6e0b in one profile and
+ *    e14e8fe2 in three others, identical file contents, identical marketplace snapshot, and
+ *    `clp fix` looping forever because update kept (correctly) no-opping.
+ * A versionless plugin therefore contributes no drift signal at all. Detecting nothing beats
+ * detecting noise that has no remedy.
+ */
+export declare function readInstalledPluginVersions(plugins: Record<string, unknown>): Record<string, string>;
 export declare function discoverProfiles(home: string): Promise<LiveProfile[]>;
 export declare function liveProfileName(lp: Pick<LiveProfile, 'agent' | 'dirName'>): string;

package/dist/discovery.js

@@ -2,6 +2,44 @@ import { access, readdir, readFile, readlink } from 'node:fs/promises';
 import { join } from 'node:path';
 import { readCodexMcpServers } from './codex.js';
 import { logicalLinkEntry } from './links.js';
+/**
+ * ccprofiles manages a profile's USER-scope plugins. A project-scope install belongs to some project
+ * directory, not to the profile, and `claude plugin update/uninstall` only ever act on user scope —
+ * counting one made those calls fail with `Plugin "x" is not installed at scope user`. Entries
+ * predating the `scope` field are treated as user.
+ */
+function userScopeEntries(entries) {
+    return (Array.isArray(entries) ? entries : [entries])
+        .filter((e) => e && (e.scope ?? 'user') === 'user');
+}
+/**
+ * Pull a comparable installed version out of each entry of installed_plugins.json's `plugins` map.
+ * The value is an ARRAY of install records (one per scope), not an object.
+ *
+ * ONLY a real release `version` counts. `gitCommitSha` looks like a tempting fallback for the
+ * versionless plugins (Claude Code writes `"version": "unknown"` for those) but it is unusable as
+ * an identity, and comparing it produced drift that `fix` could never clear:
+ *  - it is the sha of the whole MARKETPLACE repo, not of the plugin — two profiles whose plugin
+ *    files are byte-identical still hold different shas if they installed at different times
+ *  - Claude Code never refreshes it when `claude plugin update` finds nothing to do, so the stale
+ *    value outlives every update. Seen on a real machine: context7 at 205b6e0b in one profile and
+ *    e14e8fe2 in three others, identical file contents, identical marketplace snapshot, and
+ *    `clp fix` looping forever because update kept (correctly) no-opping.
+ * A versionless plugin therefore contributes no drift signal at all. Detecting nothing beats
+ * detecting noise that has no remedy.
+ */
+export function readInstalledPluginVersions(plugins) {
+    const out = {};
+    for (const [id, entries] of Object.entries(plugins)) {
+        for (const { version } of userScopeEntries(entries)) {
+            if (typeof version === 'string' && version && version !== 'unknown') {
+                out[id] = version;
+                break;
+            }
+        }
+    }
+    return out;
+}
 export async function discoverProfiles(home) {
     const entries = await readdir(home, { withFileTypes: true });
     const out = [];
@@ -86,11 +124,14 @@ export async function discoverProfiles(home) {
             }
             catch { /* no plugins/known_marketplaces.json */ }
         const installedPlugins = [];
+        let installedPluginVersions = {};
         if (agent === 'claude')
             try {
                 const ip = JSON.parse(await readFile(join(dir, 'plugins', 'installed_plugins.json'), 'utf8'));
-                if (ip && typeof ip.plugins === 'object' && ip.plugins !== null)
-                    installedPlugins.push(...Object.keys(ip.plugins));
+                if (ip && typeof ip.plugins === 'object' && ip.plugins !== null) {
+                    installedPlugins.push(...Object.entries(ip.plugins).filter(([, v]) => userScopeEntries(v).length).map(([id]) => id));
+                    installedPluginVersions = readInstalledPluginVersions(ip.plugins);
+                }
             }
             catch { /* no plugins/installed_plugins.json */ }
         out.push({
@@ -105,6 +146,7 @@ export async function discoverProfiles(home) {
             settingsEnv,
             enabledPlugins,
             installedPlugins,
+            installedPluginVersions,
             marketplaces,
         });
     }

package/dist/plugins.d.ts

@@ -2,11 +2,42 @@ export interface PluginRunner {
     marketplaceAdd(configDir: string, source: string): Promise<void>;
     install(configDir: string, id: string): Promise<void>;
     uninstall(configDir: string, id: string): Promise<void>;
+    /** `claude plugin update` — moves a plugin to the marketplace's latest. There is deliberately no
+     *  version argument: the underlying CLI has none (see planPluginVersionDrift). */
+    update(configDir: string, id: string): Promise<void>;
 }
 export declare function marketplaceOf(id: string): string | null;
-export declare function planPluginReconcile(desired: string[], current: string[]): {
+/** One plugin installed at more than one version across profiles. */
+export interface PluginVersionDrift {
+    id: string;
+    /** profile name -> installed version, for the profiles that have this plugin at a known version */
+    byProfile: Record<string, string>;
+}
+/**
+ * Find plugins installed at DIFFERENT versions across profiles.
+ *
+ * Why this exists: profiles are separate config dirs, but some plugins keep global singleton state
+ * outside them and are therefore shared by every profile at once. claude-mem is the motivating case
+ * — all profiles share one `~/.claude-mem/` worker, and its hooks compare their own plugin version
+ * against the running worker's. When two profiles sit at different versions, each session decides
+ * the other's worker is stale, kills it and respawns its own, forever. On 2026-07-16 that loop
+ * orphaned 1,246 chroma-mcp processes and exhausted 40GB of swap. Presence parity (which this tool
+ * already enforced) is not enough; version parity is the real invariant.
+ *
+ * A profile missing the plugin entirely is NOT drift — that's planPluginReconcile's job. Only ids
+ * present at 2+ distinct known versions are reported.
+ */
+export declare function planPluginVersionDrift(profiles: {
+    name: string;
+    versions: Record<string, string>;
+}[]): PluginVersionDrift[];
+export declare function planPluginReconcile(desired: string[], current: string[], 
+/** ids to re-level to the marketplace's latest (from planPluginVersionDrift); ignored unless the
+ *  id is both desired and already installed — installing/uninstalling takes precedence. */
+updateIds?: string[]): {
     install: string[];
     uninstall: string[];
+    update: string[];
 };
 export declare function reconcileProfilePlugins(opts: {
     configDir: string;
@@ -16,6 +47,8 @@ export declare function reconcileProfilePlugins(opts: {
         source: string;
     }>;
     runner: PluginRunner;
+    /** ids drifting across profiles — update them here so every profile lands on the same latest. */
+    updateIds?: string[];
 }): Promise<string[]>;
 /** If a profile's plugins/ is a legacy symlink into the old shared pool, restore it to a real dir. */
 export declare function restoreLegacyPluginSymlink(pluginsDir: string): Promise<boolean>;

package/dist/plugins.js

@@ -4,13 +4,50 @@ export function marketplaceOf(id) {
     const at = id.lastIndexOf('@');
     return at > 0 ? id.slice(at + 1) : null;
 }
-export function planPluginReconcile(desired, current) {
-    const d = new Set(desired), c = new Set(current);
-    return { install: desired.filter(id => !c.has(id)), uninstall: current.filter(id => !d.has(id)) };
+/**
+ * Find plugins installed at DIFFERENT versions across profiles.
+ *
+ * Why this exists: profiles are separate config dirs, but some plugins keep global singleton state
+ * outside them and are therefore shared by every profile at once. claude-mem is the motivating case
+ * — all profiles share one `~/.claude-mem/` worker, and its hooks compare their own plugin version
+ * against the running worker's. When two profiles sit at different versions, each session decides
+ * the other's worker is stale, kills it and respawns its own, forever. On 2026-07-16 that loop
+ * orphaned 1,246 chroma-mcp processes and exhausted 40GB of swap. Presence parity (which this tool
+ * already enforced) is not enough; version parity is the real invariant.
+ *
+ * A profile missing the plugin entirely is NOT drift — that's planPluginReconcile's job. Only ids
+ * present at 2+ distinct known versions are reported.
+ */
+export function planPluginVersionDrift(profiles) {
+    const byId = new Map();
+    for (const p of profiles) {
+        for (const [id, version] of Object.entries(p.versions)) {
+            if (!byId.has(id))
+                byId.set(id, {});
+            byId.get(id)[p.name] = version;
+        }
+    }
+    const out = [];
+    for (const [id, byProfile] of byId) {
+        if (new Set(Object.values(byProfile)).size > 1)
+            out.push({ id, byProfile });
+    }
+    return out.sort((a, b) => a.id.localeCompare(b.id));
+}
+export function planPluginReconcile(desired, current, 
+/** ids to re-level to the marketplace's latest (from planPluginVersionDrift); ignored unless the
+ *  id is both desired and already installed — installing/uninstalling takes precedence. */
+updateIds = []) {
+    const d = new Set(desired), c = new Set(current), u = new Set(updateIds);
+    return {
+        install: desired.filter(id => !c.has(id)),
+        uninstall: current.filter(id => !d.has(id)),
+        update: desired.filter(id => c.has(id) && u.has(id)),
+    };
 }
 export async function reconcileProfilePlugins(opts) {
     const log = [];
-    const { install, uninstall } = planPluginReconcile(opts.desired, opts.current);
+    const { install, uninstall, update } = planPluginReconcile(opts.desired, opts.current, opts.updateIds);
     for (const id of uninstall) {
         await opts.runner.uninstall(opts.configDir, id);
         log.push(`uninstall ${id}`);
@@ -29,6 +66,10 @@ export async function reconcileProfilePlugins(opts) {
         await opts.runner.install(opts.configDir, id);
         log.push(`install ${id}`);
     }
+    for (const id of update) {
+        await opts.runner.update(opts.configDir, id);
+        log.push(`update ${id}`);
+    }
     return log;
 }
 /** If a profile's plugins/ is a legacy symlink into the old shared pool, restore it to a real dir. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccprofiles-core",
-  "version": "0.7.3",
+  "version": "0.8.1",
   "description": "Core library for ccprofiles — discovery, manifest, secrets, apply, and LAN sync for Claude Code multi-account setups",
   "type": "module",
   "main": "./dist/index.js",