vibeusage 0.3.4 → 0.4.0

package/README.md

@@ -5,7 +5,7 @@
 # VibeUsage
 
 **Track token usage across AI coding CLIs.**  
-Local parsing, minimal data collection, and a shareable dashboard for Codex CLI, Claude Code, Gemini CLI, OpenCode, OpenClaw, and more.
+Local parsing, minimal data collection, and a shareable dashboard for Codex CLI, Claude Code, Gemini CLI, OpenCode, Hermes, OpenClaw, and more.
 
 [![npm version](https://img.shields.io/npm/v/vibeusage.svg)](https://www.npmjs.com/package/vibeusage)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
@@ -32,7 +32,7 @@ Give the install guide to ChatGPT, Claude, Codex, or your preferred agent — it
 
 VibeUsage is a **token usage tracker for AI agent CLIs**. It installs lightweight local hooks/plugins, reads usage from local logs or local databases, aggregates usage into time buckets on your machine, and syncs only the data needed to power a dashboard, cost breakdowns, project usage views, public profiles, and leaderboards.
 
-It is currently **macOS-first**, with support focused on real developer workflows around **Codex CLI, Every Code, Claude Code, Gemini CLI, OpenCode, and OpenClaw**.
+It is currently **macOS-first**, with support focused on real developer workflows around **Codex CLI, Every Code, Claude Code, Gemini CLI, OpenCode, Hermes, and OpenClaw**.
 
 ## Why VibeUsage
 
@@ -86,9 +86,20 @@ This is useful when you want to copy an install command from the dashboard or le
 | **Every Code** | Auto-detected | `notify` hook | `~/.code/sessions/**/rollout-*.jsonl` |
 | **Claude Code** | Auto-detected | `Stop` + `SessionEnd` hooks | local hook output |
 | **Gemini CLI** | Auto-detected | `SessionEnd` hook | `~/.gemini/tmp/**/chats/session-*.json` |
-| **OpenCode** | Auto-detected | plugin + local parsing | `~/.local/share/opencode/opencode.db` (legacy message files are fallback only) |
+| **OpenCode** | Auto-detected | plugin + local parsing | `~/.local/share/opencode/opencode.db` (SQLite is the only supported local accounting source) |
+| **Hermes** | Auto-detected when installed | plugin + local parsing | `~/.vibeusage/tracker/hermes.usage.jsonl` |
 | **OpenClaw** | Auto-detected when installed | session plugin | local sanitized usage ledger |
 
+### Hermes note
+
+Hermes uses a dedicated plugin-ledger path:
+
+**`vibeusage init` installs Hermes plugin → Hermes lifecycle hooks append `~/.vibeusage/tracker/hermes.usage.jsonl` → `vibeusage sync` parses only that ledger**
+
+- no prompt / response content upload
+- no fallback parsing of `~/.hermes/state.db`, `~/.hermes/sessions/`, or trajectory files
+- plugin hooks collect locally only; upload still happens in `vibeusage sync`
+
 ### OpenClaw note
 
 OpenClaw uses a dedicated privacy-preserving path:
@@ -140,12 +151,13 @@ graph LR
     C[Claude Code] --> G
     D[Gemini CLI] --> G
     E[OpenCode] --> G
-    F[OpenClaw] --> G
-    G --> H[Local aggregation into 30-min UTC buckets]
-    H --> I[VibeUsage backend]
-    I --> J[Dashboard]
-    I --> K[Project usage]
-    I --> L[Public profile / leaderboard]
+    F[Hermes] --> G
+    H[OpenClaw] --> G
+    G --> I[Local aggregation into 30-min UTC buckets]
+    I --> J[VibeUsage backend]
+    J --> K[Dashboard]
+    J --> L[Project usage]
+    J --> M[Public profile / leaderboard]
 ```
 
 At a high level:
@@ -261,7 +273,7 @@ npx vibeusage status
 npx vibeusage doctor
 ```
 
-If OpenCode support is incomplete, the most common issue is missing `sqlite3` on `PATH`, or a local SQLite query failure.
+VibeUsage reads OpenCode usage only from `opencode.db`, so the most common issues are missing `sqlite3` on `PATH`, a missing database file, or a local SQLite query failure.
 
 ### My OpenClaw usage is not showing up. What should I check?
 

package/README.zh-CN.md

@@ -86,7 +86,7 @@ npx --yes vibeusage init --link-code <code>
 | **Every Code** | 自动检测 | `notify` hook | `~/.code/sessions/**/rollout-*.jsonl` |
 | **Claude Code** | 自动检测 | `Stop` + `SessionEnd` hooks | 本地 hook 输出 |
 | **Gemini CLI** | 自动检测 | `SessionEnd` hook | `~/.gemini/tmp/**/chats/session-*.json` |
-| **OpenCode** | 自动检测 | plugin + 本地解析 | `~/.local/share/opencode/opencode.db`（旧 message 文件仅作 fallback） |
+| **OpenCode** | 自动检测 | plugin + 本地解析 | `~/.local/share/opencode/opencode.db`（SQLite 是唯一受支持的本地 accounting source） |
 | **OpenClaw** | 安装后自动检测 | session plugin | 本地 sanitized usage ledger |
 
 ### OpenClaw 说明

package/package.json

@@ -1,8 +1,16 @@
 {
   "name": "vibeusage",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "Codex CLI token usage tracker (macOS-first, notify-driven).",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/victorGPT/vibeusage.git"
+  },
+  "bugs": {
+    "url": "https://github.com/victorGPT/vibeusage/issues"
+  },
+  "homepage": "https://github.com/victorGPT/vibeusage#readme",
   "bin": {
     "tracker": "bin/tracker.js",
     "vibeusage": "bin/tracker.js",

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, Kimi, Opencode, Hermes, OpenClaw)",
       "  - Set up lightweight hooks to track your flow state",
       "  - Link your device to your VibeScore account",
       "",
@@ -486,7 +486,7 @@ try {
   const originalPath =
     source === 'every-code'
       ? codeOriginalPath
-      : source === 'claude' || source === 'opencode' || source === 'gemini'
+      : source === 'claude' || source === 'opencode' || source === 'gemini' || source === 'kimi'
         ? null
         : codexOriginalPath;
   if (originalPath) {

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(
     [
@@ -111,6 +124,9 @@ async function cmdStatus(argv = []) {
       `- 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

@@ -8,10 +8,11 @@ const {
   listRolloutFiles,
   listClaudeProjectFiles,
   listGeminiSessionFiles,
-  listOpencodeMessageFiles,
+  listKimiSessionFiles,
   parseRolloutIncremental,
   parseClaudeIncremental,
   parseGeminiIncremental,
+  parseKimiIncremental,
   parseOpencodeIncremental,
   normalizeHourlyState,
   getHourlyBucket,
@@ -22,6 +23,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");
@@ -71,9 +73,10 @@ async function cmdSync(argv) {
     const claudeProjectsDir = path.join(home, ".claude", "projects");
     const geminiHome = process.env.GEMINI_HOME || path.join(home, ".gemini");
     const geminiTmpDir = path.join(geminiHome, "tmp");
+    const kimiHome = process.env.KIMI_HOME || path.join(home, ".kimi");
+    const kimiSessionsDir = path.join(kimiHome, "sessions");
     const xdgDataHome = process.env.XDG_DATA_HOME || path.join(home, ".local", "share");
     const opencodeHome = process.env.OPENCODE_HOME || path.join(xdgDataHome, "opencode");
-    const opencodeStorageDir = path.join(opencodeHome, "storage");
     const opencodeDbPath = path.join(opencodeHome, "opencode.db");
 
     const sources = [
@@ -114,6 +117,12 @@ async function cmdSync(argv) {
       },
     });
 
+    const hermesResult = await parseHermesUsageLedger({
+      trackerDir,
+      cursors,
+      queuePath,
+    });
+
     const openclawResult = opts.fromOpenclaw
       ? await parseOpenclawSanitizedLedger({
           trackerDir,
@@ -174,28 +183,38 @@ async function cmdSync(argv) {
       });
     }
 
-    const opencodeFiles = await listOpencodeMessageFiles(opencodeStorageDir);
-    let opencodeResult = { filesProcessed: 0, eventsAggregated: 0, bucketsQueued: 0 };
-    if (progress?.enabled && opencodeFiles.length > 0) {
-      progress.start(
-        `Parsing Opencode ${renderBar(0)} 0/${formatNumber(opencodeFiles.length)} files | buckets 0`,
-      );
+    const kimiFiles = await listKimiSessionFiles(kimiSessionsDir);
+    let kimiResult = { filesProcessed: 0, eventsAggregated: 0, bucketsQueued: 0 };
+    if (kimiFiles.length > 0) {
+      if (progress?.enabled) {
+        progress.start(
+          `Parsing Kimi ${renderBar(0)} 0/${formatNumber(kimiFiles.length)} files | buckets 0`,
+        );
+      }
+      kimiResult = await parseKimiIncremental({
+        sessionFiles: kimiFiles,
+        cursors,
+        queuePath,
+        projectQueuePath,
+        onProgress: (p) => {
+          if (!progress?.enabled) return;
+          const pct = p.total > 0 ? p.index / p.total : 1;
+          progress.update(
+            `Parsing Kimi ${renderBar(pct)} ${formatNumber(p.index)}/${formatNumber(p.total)} files | buckets ${formatNumber(
+              p.bucketsQueued,
+            )}`,
+          );
+        },
+        source: "kimi",
+      });
     }
+
+    let opencodeResult = { filesProcessed: 0, eventsAggregated: 0, bucketsQueued: 0 };
     opencodeResult = await parseOpencodeIncremental({
-      messageFiles: opencodeFiles,
       opencodeDbPath,
       cursors,
       queuePath,
       projectQueuePath,
-      onProgress: (p) => {
-        if (!progress?.enabled) return;
-        const pct = p.total > 0 ? p.index / p.total : 1;
-        progress.update(
-          `Parsing Opencode ${renderBar(pct)} ${formatNumber(p.index)}/${formatNumber(
-            p.total,
-          )} files | buckets ${formatNumber(p.bucketsQueued)}`,
-        );
-      },
       source: "opencode",
     });
 
@@ -369,15 +388,19 @@ async function cmdSync(argv) {
     if (!opts.auto) {
       const totalParsed =
         parseResult.filesProcessed +
+        hermesResult.filesProcessed +
         openclawResult.filesProcessed +
         claudeResult.filesProcessed +
         geminiResult.filesProcessed +
+        kimiResult.filesProcessed +
         opencodeResult.filesProcessed;
       const totalBuckets =
         parseResult.bucketsQueued +
+        hermesResult.bucketsQueued +
         openclawResult.bucketsQueued +
         claudeResult.bucketsQueued +
         geminiResult.bucketsQueued +
+        kimiResult.bucketsQueued +
         opencodeResult.bucketsQueued;
       process.stdout.write(
         [
@@ -436,6 +459,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

@@ -21,6 +21,7 @@ async function cmdUninstall(argv) {
   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]));
 
@@ -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"),

package/src/lib/diagnostics.js

@@ -3,6 +3,7 @@ const path = require("node:path");
 const fs = require("node:fs/promises");
 
 const { readJson } = require("./fs");
+const { readLastHermesUsageEvent, resolveHermesUsageLedgerPaths } = require("./hermes-usage-ledger");
 const { normalizeState: normalizeUploadState } = require("./upload-throttle");
 const { createIntegrationContext, probeIntegrations } = require("./integrations");
 
@@ -25,6 +26,7 @@ async function collectTrackerDiagnostics({
   });
   const trackerDir = integrationContext.trackerPaths.trackerDir;
   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");
@@ -45,7 +47,10 @@ async function collectTrackerDiagnostics({
   const probeByName = new Map(probes.map((probe) => [probe.name, probe]));
   const opencodeSqliteCursor =
     cursors?.opencodeSqlite && typeof cursors.opencodeSqlite === "object" ? cursors.opencodeSqlite : {};
+  const hermesLedgerCursor =
+    cursors?.hermesLedger && typeof cursors.hermesLedger === "object" ? cursors.hermesLedger : {};
   const opencodeDbStat = await safeStat(opencodeDbPath);
+  const hermesLedgerStat = await safeStat(hermesLedgerPath);
 
   const queueSize = await safeStatSize(queuePath);
   const offsetBytes = Number(queueState.offset || 0);
@@ -60,6 +65,7 @@ async function collectTrackerDiagnostics({
   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 codexNotify = Array.isArray(codexProbe?.currentNotify)
@@ -73,6 +79,7 @@ async function collectTrackerDiagnostics({
     ? new Date(uploadThrottle.lastSuccessMs).toISOString()
     : null;
   const autoRetryAt = parseEpochMsToIso(autoRetry?.retryAtMs);
+  const hermesLastLedgerEvent = await readLastHermesUsageEvent({ trackerDir });
 
   return {
     ok: true,
@@ -92,6 +99,9 @@ async function collectTrackerDiagnostics({
       claude_config: redactValue(integrationContext.claude.settingsPath, home),
       gemini_config: redactValue(integrationContext.gemini.settingsPath, home),
       opencode_config: redactValue(integrationContext.opencode.configDir, home),
+      hermes_home: redactValue(integrationContext.hermes.hermesHome, home),
+      hermes_plugin_dir: redactValue(integrationContext.hermes.pluginDir, home),
+      hermes_ledger: redactValue(hermesLedgerPath, home),
     },
     config: {
       base_url: typeof config?.baseUrl === "string" ? config.baseUrl : null,
@@ -131,6 +141,22 @@ async function collectTrackerDiagnostics({
           ? opencodeSqliteCursor.lastErrorCode
           : null,
     },
+    hermes: {
+      ledger_present: Boolean(hermesLedgerStat?.isFile?.()),
+      ledger_size_bytes: hermesLedgerStat?.isFile?.() ? Number(hermesLedgerStat.size || 0) : 0,
+      ledger_offset:
+        Number.isFinite(Number(hermesLedgerCursor.offset)) ? Math.max(0, Number(hermesLedgerCursor.offset)) : 0,
+      ledger_updated_at:
+        typeof hermesLedgerCursor.updatedAt === "string" ? hermesLedgerCursor.updatedAt : null,
+      last_event_at:
+        typeof hermesLastLedgerEvent?.emitted_at === "string"
+          ? hermesLastLedgerEvent.emitted_at
+          : typeof hermesLedgerCursor.lastEventAt === "string"
+            ? hermesLedgerCursor.lastEventAt
+            : null,
+      last_event_type:
+        typeof hermesLastLedgerEvent?.type === "string" ? hermesLastLedgerEvent.type : null,
+    },
     notify: {
       last_notify: lastNotify,
       last_openclaw_triggered_sync: lastOpenclawSync,
@@ -147,6 +173,8 @@ async function collectTrackerDiagnostics({
       gemini_hook_configured: Boolean(geminiProbe?.configured),
       opencode_plugin_status: opencodeProbe?.status || "unknown",
       opencode_plugin_configured: Boolean(opencodeProbe?.configured),
+      hermes_plugin_status: hermesProbe?.status || "unknown",
+      hermes_plugin_configured: Boolean(hermesProbe?.configured),
       openclaw_session_plugin_status: openclawSessionProbe?.status || "unknown",
       openclaw_session_plugin_configured: Boolean(openclawSessionProbe?.configured),
       openclaw_session_plugin_linked: Boolean(openclawSessionProbe?.linked),

package/src/lib/hermes-config.js

@@ -0,0 +1,172 @@
+const os = require("node:os");
+const path = require("node:path");
+const fs = require("node:fs/promises");
+const fssync = require("node:fs");
+
+const { ensureDir, writeFileAtomic } = require("./fs");
+
+const HERMES_PLUGIN_ID = "vibeusage";
+const HERMES_PLUGIN_MARKER = "VIBEUSAGE_HERMES_PLUGIN";
+const HERMES_PLUGIN_TEMPLATE_VERSION = 1;
+
+function resolveHermesHome({ home = os.homedir(), env = process.env } = {}) {
+  const explicit = typeof env.HERMES_HOME === "string" ? env.HERMES_HOME.trim() : "";
+  if (explicit) return path.resolve(explicit);
+  return path.join(home, ".hermes");
+}
+
+function resolveHermesPluginPaths({ home = os.homedir(), env = process.env, trackerDir } = {}) {
+  if (!trackerDir) throw new Error("trackerDir is required");
+
+  const hermesHome = resolveHermesHome({ home, env });
+  const pluginDir = path.join(hermesHome, "plugins", HERMES_PLUGIN_ID);
+  return {
+    hermesHome,
+    pluginId: HERMES_PLUGIN_ID,
+    pluginDir,
+    pluginYamlPath: path.join(pluginDir, "plugin.yaml"),
+    pluginInitPath: path.join(pluginDir, "__init__.py"),
+    ledgerPath: path.join(trackerDir, "hermes.usage.jsonl"),
+  };
+}
+
+async function probeHermesPlugin({ home = os.homedir(), env = process.env, trackerDir } = {}) {
+  const paths = resolveHermesPluginPaths({ home, env, trackerDir });
+  const expectedYaml = buildHermesPluginYaml();
+  const expectedInit = buildHermesPluginInit({ ledgerPath: paths.ledgerPath });
+  const hermesHomeExists = await pathExists(paths.hermesHome);
+
+  if (!hermesHomeExists) {
+    return {
+      configured: false,
+      status: "not_installed",
+      detail: "Hermes home not found",
+      initPreviewStatus: "updated",
+      initPreviewDetail: "Will install plugin",
+      ...paths,
+    };
+  }
+
+  const pluginDirExists = await pathExists(paths.pluginDir);
+  if (!pluginDirExists) {
+    return {
+      configured: false,
+      status: "not_installed",
+      detail: "Plugin not installed",
+      initPreviewStatus: "updated",
+      initPreviewDetail: "Will install plugin",
+      ...paths,
+    };
+  }
+
+  const yamlState = await readTextStrict(paths.pluginYamlPath);
+  const initState = await readTextStrict(paths.pluginInitPath);
+  if (yamlState.status === "error" || initState.status === "error") {
+    return {
+      configured: false,
+      status: "unreadable",
+      detail: yamlState.error || initState.error || "Plugin unreadable",
+      ...paths,
+    };
+  }
+  if (yamlState.status === "missing" || initState.status === "missing") {
+    return {
+      configured: false,
+      status: "drifted",
+      detail: "Run vibeusage init to reconcile plugin",
+      ...paths,
+    };
+  }
+
+  const configured = yamlState.value === expectedYaml && initState.value === expectedInit;
+  return {
+    configured,
+    status: configured ? "ready" : "drifted",
+    detail: configured ? "Plugin installed" : "Run vibeusage init to reconcile plugin",
+    ...paths,
+  };
+}
+
+async function installHermesPlugin({ home = os.homedir(), env = process.env, trackerDir } = {}) {
+  const paths = resolveHermesPluginPaths({ home, env, trackerDir });
+  const nextYaml = buildHermesPluginYaml();
+  const nextInit = buildHermesPluginInit({ ledgerPath: paths.ledgerPath });
+  const currentYaml = await fs.readFile(paths.pluginYamlPath, "utf8").catch(() => null);
+  const currentInit = await fs.readFile(paths.pluginInitPath, "utf8").catch(() => null);
+  const changed = currentYaml !== nextYaml || currentInit !== nextInit;
+
+  await ensureDir(paths.pluginDir);
+  await writeFileAtomic(paths.pluginYamlPath, nextYaml);
+  await writeFileAtomic(paths.pluginInitPath, nextInit);
+  return { configured: true, changed, ...paths };
+}
+
+async function removeHermesPlugin({ home = os.homedir(), env = process.env, trackerDir } = {}) {
+  const paths = resolveHermesPluginPaths({ home, env, trackerDir });
+  const hadPluginDir = await pathExists(paths.pluginDir);
+  if (!hadPluginDir) {
+    return { removed: false, skippedReason: "plugin-missing", ...paths };
+  }
+
+  const yamlText = await fs.readFile(paths.pluginYamlPath, "utf8").catch(() => null);
+  const initText = await fs.readFile(paths.pluginInitPath, "utf8").catch(() => null);
+  const markerPresent = hasHermesPluginMarker(yamlText) && hasHermesPluginMarker(initText);
+  if (!markerPresent) {
+    return { removed: false, skippedReason: "unexpected-content", ...paths };
+  }
+
+  await fs.rm(paths.pluginDir, { recursive: true, force: true }).catch(() => {});
+  return { removed: true, ...paths };
+}
+
+function buildHermesPluginYaml() {
+  return readTemplateFile("plugin.yaml");
+}
+
+function buildHermesPluginInit({ ledgerPath }) {
+  const safeLedgerPath = typeof ledgerPath === "string" ? ledgerPath : "";
+  return readTemplateFile("__init__.py").replace("__LEDGER_PATH__", safeLedgerPath);
+}
+
+function hasHermesPluginMarker(text) {
+  return typeof text === "string" && text.includes(HERMES_PLUGIN_MARKER);
+}
+
+async function readTextStrict(filePath) {
+  try {
+    return { status: "ok", value: await fs.readFile(filePath, "utf8"), error: null };
+  } catch (err) {
+    if (err?.code === "ENOENT" || err?.code === "ENOTDIR") {
+      return { status: "missing", value: null, error: null };
+    }
+    return { status: "error", value: null, error: err?.message || String(err) };
+  }
+}
+
+async function pathExists(targetPath) {
+  try {
+    await fs.stat(targetPath);
+    return true;
+  } catch (_err) {
+    return false;
+  }
+}
+
+function readTemplateFile(name) {
+  const templatePath = path.join(__dirname, "..", "templates", "hermes-vibeusage-plugin", name);
+  return fssync.readFileSync(templatePath, "utf8");
+}
+
+module.exports = {
+  HERMES_PLUGIN_ID,
+  HERMES_PLUGIN_MARKER,
+  HERMES_PLUGIN_TEMPLATE_VERSION,
+  resolveHermesHome,
+  resolveHermesPluginPaths,
+  probeHermesPlugin,
+  installHermesPlugin,
+  removeHermesPlugin,
+  buildHermesPluginYaml,
+  buildHermesPluginInit,
+  hasHermesPluginMarker,
+};