vibeusage 0.3.3 → 0.3.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibeusage",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Codex CLI token usage tracker (macOS-first, notify-driven).",
   "license": "MIT",
   "bin": {

package/src/commands/init.js

@@ -190,7 +190,7 @@ function renderWelcome() {
       DIVIDER,
       "",
       "This tool will:",
-      "  - Analyze your local AI CLI configurations (Codex, Every Code, Claude, Gemini, Opencode, OpenClaw)",
+      "  - Analyze your local AI CLI configurations (Codex, Every Code, Claude, Gemini, Opencode, Hermes, OpenClaw)",
       "  - Set up lightweight hooks to track your flow state",
       "  - Link your device to your VibeScore account",
       "",

package/src/commands/status.js

@@ -6,6 +6,7 @@ const { readJson } = require("../lib/fs");
 const { collectLocalSubscriptions } = require("../lib/subscriptions");
 const { normalizeState: normalizeUploadState } = require("../lib/upload-throttle");
 const { collectTrackerDiagnostics } = require("../lib/diagnostics");
+const { readLastHermesUsageEvent, resolveHermesUsageLedgerPaths } = require("../lib/hermes-usage-ledger");
 const { createIntegrationContext, listIntegrations, probeIntegrations } = require("../lib/integrations");
 const { resolveTrackerPaths } = require("../lib/tracker-paths");
 
@@ -20,6 +21,7 @@ async function cmdStatus(argv = []) {
   const home = os.homedir();
   const { trackerDir } = await resolveTrackerPaths({ home });
   const configPath = path.join(trackerDir, "config.json");
+  const { ledgerPath: hermesLedgerPath } = resolveHermesUsageLedgerPaths({ trackerDir });
   const queuePath = path.join(trackerDir, "queue.jsonl");
   const queueStatePath = path.join(trackerDir, "queue.state.json");
   const cursorsPath = path.join(trackerDir, "cursors.json");
@@ -80,8 +82,10 @@ async function cmdStatus(argv = []) {
   const claudeProbe = probeByName.get("claude");
   const geminiProbe = probeByName.get("gemini");
   const opencodeProbe = probeByName.get("opencode");
+  const hermesProbe = probeByName.get("hermes");
   const openclawSessionProbe = probeByName.get("openclaw-session");
   const opencodeDbPresent = Boolean((await safeStat(opencodeDbPath))?.isFile?.());
+  const hermesLedgerPresent = Boolean((await safeStat(hermesLedgerPath))?.isFile?.());
   const opencodeSqliteState =
     cursors?.opencodeSqlite && typeof cursors.opencodeSqlite === "object"
       ? cursors.opencodeSqlite
@@ -90,6 +94,15 @@ async function cmdStatus(argv = []) {
     typeof opencodeSqliteState.lastStatus === "string" && opencodeSqliteState.lastStatus.trim()
       ? opencodeSqliteState.lastStatus.trim()
       : "never_checked";
+  const hermesLedgerState =
+    cursors?.hermesLedger && typeof cursors.hermesLedger === "object" ? cursors.hermesLedger : {};
+  const hermesLastLedgerEvent = await readLastHermesUsageEvent({ trackerDir });
+  const hermesLastEventAt =
+    typeof hermesLastLedgerEvent?.emitted_at === "string"
+      ? hermesLastLedgerEvent.emitted_at
+      : typeof hermesLedgerState.lastEventAt === "string"
+        ? hermesLedgerState.lastEventAt
+        : "never";
 
   process.stdout.write(
     [
@@ -108,9 +121,12 @@ async function cmdStatus(argv = []) {
       autoRetryLine,
       `- Codex notify: ${renderIntegrationStatus(descriptors.get("codex"), codexProbe)}`,
       `- Every Code notify: ${renderIntegrationStatus(descriptors.get("every-code"), everyCodeProbe)}`,
-      `- Claude hooks: ${renderIntegrationStatus(descriptors.get("claude"), claudeProbe)}`,
+      `- Claude plugin: ${renderIntegrationStatus(descriptors.get("claude"), claudeProbe)}`,
       `- Gemini hooks: ${renderIntegrationStatus(descriptors.get("gemini"), geminiProbe)}`,
       `- Opencode plugin: ${renderIntegrationStatus(descriptors.get("opencode"), opencodeProbe)}`,
+      `- Hermes plugin: ${renderIntegrationStatus(descriptors.get("hermes"), hermesProbe)}`,
+      `- Hermes ledger: ${hermesLedgerPresent ? "present" : "missing"}`,
+      `- Hermes last ledger event: ${hermesLastEventAt}`,
       `- OpenCode SQLite DB: ${opencodeDbPresent ? "present" : "missing"}`,
       `- OpenCode SQLite reader: ${opencodeSqliteReader}`,
       `- OpenClaw session plugin: ${renderIntegrationStatus(

package/src/commands/sync.js

@@ -22,6 +22,7 @@ const {
 } = require("../lib/rollout");
 const { drainQueueToCloud } = require("../lib/uploader");
 const { readOpenclawUsageLedger } = require("../lib/openclaw-usage-ledger");
+const { readHermesUsageLedger } = require("../lib/hermes-usage-ledger");
 const { collectLocalSubscriptions } = require("../lib/subscriptions");
 const { createProgress, renderBar, formatNumber, formatBytes } = require("../lib/progress");
 const { syncHeartbeat } = require("../lib/vibeusage-api");
@@ -114,6 +115,12 @@ async function cmdSync(argv) {
       },
     });
 
+    const hermesResult = await parseHermesUsageLedger({
+      trackerDir,
+      cursors,
+      queuePath,
+    });
+
     const openclawResult = opts.fromOpenclaw
       ? await parseOpenclawSanitizedLedger({
           trackerDir,
@@ -369,12 +376,14 @@ async function cmdSync(argv) {
     if (!opts.auto) {
       const totalParsed =
         parseResult.filesProcessed +
+        hermesResult.filesProcessed +
         openclawResult.filesProcessed +
         claudeResult.filesProcessed +
         geminiResult.filesProcessed +
         opencodeResult.filesProcessed;
       const totalBuckets =
         parseResult.bucketsQueued +
+        hermesResult.bucketsQueued +
         openclawResult.bucketsQueued +
         claudeResult.bucketsQueued +
         geminiResult.bucketsQueued +
@@ -436,6 +445,78 @@ function parseArgs(argv) {
 
 module.exports = { cmdSync };
 
+async function parseHermesUsageLedger({ trackerDir, cursors, queuePath }) {
+  const ledgerCursor =
+    cursors?.hermesLedger && typeof cursors.hermesLedger === "object" ? cursors.hermesLedger : {};
+  const offset = Math.max(0, Number(ledgerCursor.offset || 0));
+  const { events, endOffset } = await readHermesUsageLedger({ trackerDir, offset });
+
+  const hourlyState = normalizeHourlyState(cursors?.hourly);
+  const touchedBuckets = new Set();
+  let eventsAggregated = 0;
+
+  for (const event of events) {
+    if (!event || typeof event !== "object") continue;
+    if (event.type !== "usage") continue;
+    const bucketStart = toUtcHalfHourStart(event.emitted_at);
+    if (!bucketStart) continue;
+
+    const model =
+      typeof event.model === "string" && event.model.trim() ? event.model.trim() : "unknown";
+    const source = "hermes";
+    const delta = {
+      input_tokens: Math.max(0, Number(event.input_tokens || 0)),
+      cached_input_tokens: Math.max(
+        0,
+        Number(event.cache_read_tokens || 0) + Number(event.cache_write_tokens || 0),
+      ),
+      output_tokens: Math.max(0, Number(event.output_tokens || 0)),
+      reasoning_output_tokens: Math.max(0, Number(event.reasoning_tokens || 0)),
+      total_tokens: Math.max(0, Number(event.total_tokens || 0)),
+    };
+
+    if (
+      delta.input_tokens === 0 &&
+      delta.cached_input_tokens === 0 &&
+      delta.output_tokens === 0 &&
+      delta.reasoning_output_tokens === 0 &&
+      delta.total_tokens === 0
+    ) {
+      continue;
+    }
+
+    const bucket = getHourlyBucket(hourlyState, source, model, bucketStart);
+    addTotals(bucket.totals, delta);
+    touchedBuckets.add(bucketKey(source, model, bucketStart));
+    eventsAggregated += 1;
+  }
+
+  const bucketsQueued = await enqueueTouchedBuckets({ queuePath, hourlyState, touchedBuckets });
+  const lastUsageEvent = [...events].reverse().find((event) => {
+    if (!event || event.type !== "usage") return false;
+    return Boolean(toUtcHalfHourStart(event.emitted_at));
+  });
+  hourlyState.updatedAt = new Date().toISOString();
+  cursors.hourly = hourlyState;
+  cursors.hermesLedger = {
+    version: 1,
+    offset: endOffset,
+    updatedAt: new Date().toISOString(),
+    lastEventAt:
+      typeof lastUsageEvent?.emitted_at === "string"
+        ? lastUsageEvent.emitted_at
+        : typeof ledgerCursor.lastEventAt === "string"
+          ? ledgerCursor.lastEventAt
+          : null,
+  };
+
+  return {
+    filesProcessed: endOffset > offset ? 1 : 0,
+    eventsAggregated,
+    bucketsQueued,
+  };
+}
+
 async function parseOpenclawSanitizedLedger({ trackerDir, cursors, queuePath }) {
   const ledgerCursor =
     cursors?.openclawLedger && typeof cursors.openclawLedger === "object"

package/src/commands/uninstall.js

@@ -18,9 +18,10 @@ async function cmdUninstall(argv) {
   });
   const codexConfigExists = await isFile(integrationContext.codex.configPath);
   const codeConfigExists = await isFile(integrationContext.everyCode.configPath);
-  const claudeConfigExists = await isFile(integrationContext.claude.settingsPath);
+  const claudeConfigExists = await isDir(integrationContext.claude.configDir);
   const geminiConfigExists = await isDir(integrationContext.gemini.configDir);
   const opencodeConfigExists = await isDir(integrationContext.opencode.configDir);
+  const hermesConfigExists = await isDir(integrationContext.hermes.hermesHome);
   const integrationResults = await uninstallIntegrations(integrationContext);
   const resultByName = new Map(integrationResults.map((result) => [result.name, result]));
 
@@ -58,11 +59,11 @@ async function cmdUninstall(argv) {
       renderHookLine({
         exists: claudeConfigExists,
         result: resultByName.get("claude"),
-        missingText: "- Claude hooks: skipped (settings.json not found)",
+        missingText: `- Claude plugin: skipped (${integrationContext.claude.configDir} not found)`,
         removedText: (result) =>
-          `- Claude hooks removed: ${result.detail || integrationContext.claude.settingsPath}`,
-        noChangeText: "- Claude hooks: no change",
-        skippedText: "- Claude hooks: skipped",
+          `- Claude plugin removed: ${result.detail || integrationContext.claude.settingsPath}`,
+        noChangeText: "- Claude plugin: no change",
+        skippedText: "- Claude plugin: skipped",
       }),
       renderHookLine({
         exists: geminiConfigExists,
@@ -82,6 +83,15 @@ async function cmdUninstall(argv) {
         noChangeText: "- Opencode plugin: no change",
         skippedText: "- Opencode plugin: skipped (unexpected content)",
       }),
+      renderHookLine({
+        exists: hermesConfigExists,
+        result: resultByName.get("hermes"),
+        missingText: `- Hermes plugin: skipped (${integrationContext.hermes.hermesHome} not found)`,
+        removedText: (result) =>
+          `- Hermes plugin removed: ${result.detail || integrationContext.hermes.pluginDir}`,
+        noChangeText: "- Hermes plugin: no change",
+        skippedText: "- Hermes plugin: skipped (unexpected content)",
+      }),
       renderHookLine({
         exists: true,
         result: resultByName.get("openclaw-session"),
@@ -120,6 +130,15 @@ async function isFile(p) {
   }
 }
 
+async function isDir(p) {
+  try {
+    const st = await fs.stat(p);
+    return st.isDirectory();
+  } catch (_e) {
+    return false;
+  }
+}
+
 function renderRestoreLine({ exists, result, missingText, restoredText, noChangeText, skippedText }) {
   if (!exists) return missingText;
   if (!result) return noChangeText;

package/src/lib/claude-plugin.js

@@ -0,0 +1,381 @@
+const os = require("node:os");
+const path = require("node:path");
+const fs = require("node:fs/promises");
+const cp = require("node:child_process");
+
+const { ensureDir, readJsonStrict, writeFileAtomic } = require("./fs");
+const { buildClaudeHookCommand } = require("./claude-config");
+
+const CLAUDE_PLUGIN_MARKETPLACE_NAME = "vibeusage-local";
+const CLAUDE_PLUGIN_ID = "vibeusage-claude-sync";
+const CLAUDE_PLUGIN_VERSION = "0.0.0";
+
+function resolveClaudePluginPaths({ home = os.homedir(), trackerDir } = {}) {
+  if (!trackerDir) throw new Error("trackerDir is required");
+
+  const claudeDir = path.join(home, ".claude");
+  const pluginsDir = path.join(claudeDir, "plugins");
+  const marketplaceDir = path.join(trackerDir, "claude-marketplace");
+  const pluginRootDir = path.join(marketplaceDir, "plugins", CLAUDE_PLUGIN_ID);
+  const pluginRef = `${CLAUDE_PLUGIN_ID}@${CLAUDE_PLUGIN_MARKETPLACE_NAME}`;
+
+  return {
+    claudeDir,
+    settingsPath: path.join(claudeDir, "settings.json"),
+    pluginsDir,
+    knownMarketplacesPath: path.join(pluginsDir, "known_marketplaces.json"),
+    installedPluginsPath: path.join(pluginsDir, "installed_plugins.json"),
+    marketplaceDir,
+    marketplaceManifestPath: path.join(marketplaceDir, ".claude-plugin", "marketplace.json"),
+    pluginRootDir,
+    pluginManifestPath: path.join(pluginRootDir, ".claude-plugin", "plugin.json"),
+    pluginHooksPath: path.join(pluginRootDir, "hooks", "hooks.json"),
+    pluginRef,
+  };
+}
+
+async function ensureClaudePluginFiles({ trackerDir, notifyPath } = {}) {
+  if (!trackerDir || !notifyPath) {
+    throw new Error("trackerDir and notifyPath are required");
+  }
+
+  const paths = resolveClaudePluginPaths({ trackerDir });
+
+  await ensureDir(path.dirname(paths.marketplaceManifestPath));
+  await ensureDir(path.dirname(paths.pluginManifestPath));
+  await ensureDir(path.dirname(paths.pluginHooksPath));
+
+  await writeFileAtomic(paths.marketplaceManifestPath, buildMarketplaceManifest());
+  await writeFileAtomic(paths.pluginManifestPath, buildPluginManifest());
+  await writeFileAtomic(paths.pluginHooksPath, buildPluginHooks({ notifyPath }));
+
+  return paths;
+}
+
+async function probeClaudePluginState({ home = os.homedir(), trackerDir } = {}) {
+  const paths = resolveClaudePluginPaths({ home, trackerDir });
+  const settings = await readJsonStrict(paths.settingsPath);
+  const known = await readJsonStrict(paths.knownMarketplacesPath);
+  const installed = await readJsonStrict(paths.installedPluginsPath);
+  const pluginFilesReady =
+    (await isFile(paths.marketplaceManifestPath)) &&
+    (await isFile(paths.pluginManifestPath)) &&
+    (await isFile(paths.pluginHooksPath));
+
+  if (settings.status === "invalid" || settings.status === "error") {
+    return unreadableState(paths, "Claude settings unreadable");
+  }
+  if (known.status === "invalid" || known.status === "error") {
+    return unreadableState(paths, "Claude marketplace registry unreadable");
+  }
+  if (installed.status === "invalid" || installed.status === "error") {
+    return unreadableState(paths, "Claude plugin registry unreadable");
+  }
+
+  const enabled = settings.value?.enabledPlugins?.[paths.pluginRef] === true;
+  const declaredMarketplace = marketplaceMatchesPath({
+    marketplaceEntry: known.value?.[CLAUDE_PLUGIN_MARKETPLACE_NAME],
+    marketplaceDir: paths.marketplaceDir,
+  });
+  const installedEntries = Array.isArray(installed.value?.plugins?.[paths.pluginRef])
+    ? installed.value.plugins[paths.pluginRef]
+    : [];
+  const installedUserEntry =
+    installedEntries.find((entry) => String(entry?.scope || "") === "user") || null;
+
+  return {
+    configured: Boolean(enabled && installedUserEntry && pluginFilesReady && declaredMarketplace),
+    enabled,
+    installed: Boolean(installedUserEntry),
+    marketplaceDeclared: declaredMarketplace,
+    pluginFilesReady,
+    pluginRef: paths.pluginRef,
+    unreadable: false,
+    detail: null,
+    ...paths,
+  };
+}
+
+async function installClaudePlugin({
+  home = os.homedir(),
+  trackerDir,
+  notifyPath,
+  env = process.env,
+} = {}) {
+  const paths = resolveClaudePluginPaths({ home, trackerDir });
+  await ensureClaudePluginFiles({ trackerDir, notifyPath });
+
+  const initialState = await probeClaudePluginState({ home, trackerDir });
+  if (initialState.unreadable) {
+    return { configured: false, skippedReason: "claude-config-unreadable", ...initialState };
+  }
+
+  const marketplaceCmd = initialState.marketplaceDeclared
+    ? ["plugin", "marketplace", "update", CLAUDE_PLUGIN_MARKETPLACE_NAME]
+    : ["plugin", "marketplace", "add", paths.marketplaceDir, "--scope", "user"];
+  const marketplaceResult = runClaudeCli(marketplaceCmd, env);
+  if (marketplaceResult.skippedReason) {
+    return { configured: false, ...paths, ...marketplaceResult };
+  }
+
+  let actionResult;
+  if (!initialState.installed) {
+    actionResult = runClaudeCli(["plugin", "install", paths.pluginRef, "--scope", "user"], env);
+  } else if (!initialState.enabled) {
+    actionResult = runClaudeCli(["plugin", "enable", paths.pluginRef, "--scope", "user"], env);
+  } else {
+    actionResult = runClaudeCli(["plugin", "update", paths.pluginRef, "--scope", "user"], env);
+  }
+  if (actionResult.skippedReason) {
+    return { configured: false, ...paths, ...actionResult };
+  }
+
+  const nextState = await probeClaudePluginState({ home, trackerDir });
+  return {
+    configured: nextState.configured,
+    changed: !initialState.configured || !initialState.enabled || !initialState.marketplaceDeclared,
+    stdout: `${marketplaceResult.stdout || ""}\n${actionResult.stdout || ""}`.trim(),
+    stderr: `${marketplaceResult.stderr || ""}\n${actionResult.stderr || ""}`.trim(),
+    ...nextState,
+  };
+}
+
+async function removeClaudePluginConfig({
+  home = os.homedir(),
+  trackerDir,
+  env = process.env,
+} = {}) {
+  const paths = resolveClaudePluginPaths({ home, trackerDir });
+  const initialState = await probeClaudePluginState({ home, trackerDir });
+  const hadMarketplaceDir = await isDir(paths.marketplaceDir);
+
+  let changed = false;
+  let skippedReason = null;
+  if (initialState.installed || initialState.enabled) {
+    const uninstallResult = runClaudeCli(["plugin", "uninstall", paths.pluginRef, "--scope", "user"], env);
+    if (uninstallResult.skippedReason) {
+      return { removed: false, ...paths, ...uninstallResult };
+    }
+    changed = true;
+  }
+
+  const siblingRefs = await listMarketplaceSiblingPluginRefs({
+    installedPluginsPath: paths.installedPluginsPath,
+    marketplaceName: CLAUDE_PLUGIN_MARKETPLACE_NAME,
+    excludePluginRef: paths.pluginRef,
+  });
+
+  const shouldRemoveMarketplace =
+    initialState.marketplaceDeclared && siblingRefs.unreadable !== true && siblingRefs.refs.length === 0;
+
+  if (shouldRemoveMarketplace) {
+    const removeMarketplaceResult = runClaudeCli(
+      ["plugin", "marketplace", "remove", CLAUDE_PLUGIN_MARKETPLACE_NAME],
+      env,
+    );
+    if (removeMarketplaceResult.skippedReason && removeMarketplaceResult.skippedReason !== "claude-cli-error") {
+      return { removed: changed, ...paths, ...removeMarketplaceResult };
+    }
+    changed = true;
+  } else if (!changed) {
+    skippedReason = "plugin-missing";
+  }
+
+  if (shouldRemoveMarketplace) {
+    await fs.rm(paths.marketplaceDir, { recursive: true, force: true }).catch(() => {});
+  }
+  return {
+    removed: changed || (hadMarketplaceDir && shouldRemoveMarketplace),
+    skippedReason,
+    siblingPluginRefs: siblingRefs.refs,
+    ...paths,
+  };
+}
+
+function runClaudeCli(args, env = process.env) {
+  let res;
+  try {
+    res = cp.spawnSync("claude", args, {
+      env,
+      encoding: "utf8",
+      timeout: 30_000,
+    });
+  } catch (err) {
+    return {
+      code: 1,
+      skippedReason: err?.code === "ENOENT" ? "claude-cli-missing" : "claude-cli-error",
+      error: err?.message || String(err),
+      stdout: "",
+      stderr: "",
+    };
+  }
+
+  if (res.error?.code === "ENOENT") {
+    return {
+      code: 1,
+      skippedReason: "claude-cli-missing",
+      error: res.error.message,
+      stdout: res.stdout || "",
+      stderr: res.stderr || "",
+    };
+  }
+
+  if ((res.status || 0) !== 0) {
+    return {
+      code: Number(res.status || 1),
+      skippedReason: "claude-cli-error",
+      error: (res.stderr || res.stdout || "").trim() || "claude plugin command failed",
+      stdout: res.stdout || "",
+      stderr: res.stderr || "",
+    };
+  }
+
+  return {
+    code: 0,
+    stdout: res.stdout || "",
+    stderr: res.stderr || "",
+  };
+}
+
+function buildMarketplaceManifest() {
+  return `${JSON.stringify(
+    {
+      $schema: "https://anthropic.com/claude-code/marketplace.schema.json",
+      name: CLAUDE_PLUGIN_MARKETPLACE_NAME,
+      description: "Local VibeUsage Claude plugin marketplace.",
+      owner: {
+        name: "VibeUsage",
+        email: "support@vibeusage.cc",
+      },
+      version: CLAUDE_PLUGIN_VERSION,
+      plugins: [
+        {
+          name: CLAUDE_PLUGIN_ID,
+          source: `./plugins/${CLAUDE_PLUGIN_ID}`,
+          description: "Trigger VibeUsage Claude notify bridge on Claude session lifecycle events.",
+          version: CLAUDE_PLUGIN_VERSION,
+          strict: false,
+        },
+      ],
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+function buildPluginManifest() {
+  return `${JSON.stringify(
+    {
+      name: CLAUDE_PLUGIN_ID,
+      description: "Trigger VibeUsage Claude notify bridge on Claude session lifecycle events.",
+      version: CLAUDE_PLUGIN_VERSION,
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+function buildPluginHooks({ notifyPath }) {
+  const hookCommand = buildClaudeHookCommand(notifyPath);
+  return `${JSON.stringify(
+    {
+      description: "Run VibeUsage Claude notify bridge on Stop and SessionEnd events.",
+      hooks: {
+        Stop: [
+          {
+            hooks: [{ type: "command", command: hookCommand }],
+          },
+        ],
+        SessionEnd: [
+          {
+            hooks: [{ type: "command", command: hookCommand }],
+          },
+        ],
+      },
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+function unreadableState(paths, detail) {
+  return {
+    configured: false,
+    enabled: false,
+    installed: false,
+    marketplaceDeclared: false,
+    pluginFilesReady: false,
+    pluginRef: paths.pluginRef,
+    unreadable: true,
+    detail,
+    ...paths,
+  };
+}
+
+function marketplaceMatchesPath({ marketplaceEntry, marketplaceDir } = {}) {
+  if (!marketplaceEntry || typeof marketplaceEntry !== "object") return false;
+
+  const source = marketplaceEntry.source;
+  if (!source || typeof source !== "object") return false;
+  if (source.source !== "path") return false;
+  if (typeof source.path !== "string" || source.path.length === 0) return false;
+
+  return path.resolve(source.path) === path.resolve(marketplaceDir);
+}
+
+async function listMarketplaceSiblingPluginRefs({
+  installedPluginsPath,
+  marketplaceName,
+  excludePluginRef,
+} = {}) {
+  const installed = await readJsonStrict(installedPluginsPath);
+  if (installed.status === "invalid") {
+    return { unreadable: true, refs: [] };
+  }
+
+  const plugins =
+    installed.value?.plugins && typeof installed.value.plugins === "object"
+      ? installed.value.plugins
+      : {};
+  const refs = Object.entries(plugins)
+    .filter(([ref, entries]) => {
+      if (ref === excludePluginRef) return false;
+      if (!ref.endsWith(`@${marketplaceName}`)) return false;
+      return Array.isArray(entries) && entries.length > 0;
+    })
+    .map(([ref]) => ref);
+
+  return { unreadable: false, refs };
+}
+
+function isNonEmptyObject(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+async function isFile(targetPath) {
+  try {
+    const stat = await fs.stat(targetPath);
+    return stat.isFile();
+  } catch (_err) {
+    return false;
+  }
+}
+
+async function isDir(targetPath) {
+  try {
+    const stat = await fs.stat(targetPath);
+    return stat.isDirectory();
+  } catch (_err) {
+    return false;
+  }
+}
+
+module.exports = {
+  CLAUDE_PLUGIN_MARKETPLACE_NAME,
+  CLAUDE_PLUGIN_ID,
+  resolveClaudePluginPaths,
+  ensureClaudePluginFiles,
+  probeClaudePluginState,
+  installClaudePlugin,
+  removeClaudePluginConfig,
+};