ccprofiles-core 0.7.3 → 0.8.0

package/dist/discovery.d.ts

@@ -14,9 +14,35 @@ 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.
+ *
+ * Real-world shapes to survive (all four seen on one machine):
+ *  - the value is an ARRAY of install records (one per scope: user/project/local), not an object
+ *  - a released plugin has a real `version` ('13.11.0') alongside a `gitCommitSha`; the two move
+ *    together, so either identifies the code — but the version reads better in a warning
+ *  - a plugin pinned by git sha rather than a release has no real version, and Claude Code spells
+ *    that inconsistently: the literal 'unknown' in some releases, the SHORT sha in others, for the
+ *    very same commit ('unknown' vs 'e14e8fe2c1fc', both with sha 'e14e8fe2c1fca591…')
+ *  - so a short-sha `version` must not be compared against a full `gitCommitSha` either — same
+ *    commit, different string
+ *
+ * Hence: use `version` only when it is a real version, i.e. not missing, not 'unknown', and not
+ * merely a prefix of the entry's own sha. Otherwise use the full `gitCommitSha`, which is the one
+ * canonical spelling every profile agrees on.
+ *
+ * ponytail: takes the first scope's version when a plugin is installed at several scopes at once.
+ * Per-scope drift is a different (rarer) bug than the cross-profile drift this exists to catch;
+ * widen to Record<id, Record<scope, version>> if that ever bites.
+ */
+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';
+/**
+ * Pull a comparable installed version out of each entry of installed_plugins.json's `plugins` map.
+ *
+ * Real-world shapes to survive (all four seen on one machine):
+ *  - the value is an ARRAY of install records (one per scope: user/project/local), not an object
+ *  - a released plugin has a real `version` ('13.11.0') alongside a `gitCommitSha`; the two move
+ *    together, so either identifies the code — but the version reads better in a warning
+ *  - a plugin pinned by git sha rather than a release has no real version, and Claude Code spells
+ *    that inconsistently: the literal 'unknown' in some releases, the SHORT sha in others, for the
+ *    very same commit ('unknown' vs 'e14e8fe2c1fc', both with sha 'e14e8fe2c1fca591…')
+ *  - so a short-sha `version` must not be compared against a full `gitCommitSha` either — same
+ *    commit, different string
+ *
+ * Hence: use `version` only when it is a real version, i.e. not missing, not 'unknown', and not
+ * merely a prefix of the entry's own sha. Otherwise use the full `gitCommitSha`, which is the one
+ * canonical spelling every profile agrees on.
+ *
+ * ponytail: takes the first scope's version when a plugin is installed at several scopes at once.
+ * Per-scope drift is a different (rarer) bug than the cross-profile drift this exists to catch;
+ * widen to Record<id, Record<scope, version>> if that ever bites.
+ */
+export function readInstalledPluginVersions(plugins) {
+    const out = {};
+    for (const [id, entries] of Object.entries(plugins)) {
+        for (const e of Array.isArray(entries) ? entries : [entries]) {
+            const { version, gitCommitSha } = (e ?? {});
+            const sha = typeof gitCommitSha === 'string' && gitCommitSha ? gitCommitSha : null;
+            const ver = typeof version === 'string' && version && version !== 'unknown' ? version : null;
+            const isShaSpelling = !!ver && !!sha && sha.startsWith(ver);
+            const v = ver && !isShaSpelling ? ver : sha ?? ver;
+            if (v) {
+                out[id] = v;
+                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)
+                if (ip && typeof ip.plugins === 'object' && ip.plugins !== null) {
                     installedPlugins.push(...Object.keys(ip.plugins));
+                    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.0",
   "description": "Core library for ccprofiles — discovery, manifest, secrets, apply, and LAN sync for Claude Code multi-account setups",
   "type": "module",
   "main": "./dist/index.js",