vibeusage 0.2.18 → 0.2.19

package/package.json

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

package/src/cli.js

@@ -57,6 +57,7 @@ function printHelp() {
       '  - --dry-run previews changes without writing files.',
       '  - optional: --link-code <code> skips browser login when provided by Dashboard.',
       '  - Every Code notify installs when ~/.code/config.toml exists.',
+      '  - OpenClaw hook auto-links when OpenClaw is installed (requires gateway restart).',
       '  - auto sync waits for a device token.',
       '  - optional: VIBEUSAGE_DASHBOARD_URL or --dashboard-url for hosted landing.',
       '  - sync parses ~/.codex/sessions/**/rollout-*.jsonl and ~/.code/sessions/**/rollout-*.jsonl, then uploads token deltas.',

package/src/commands/init.js

@@ -22,6 +22,7 @@ const {
   isGeminiHookConfigured
 } = require('../lib/gemini-config');
 const { resolveOpencodeConfigDir, upsertOpencodePlugin, isOpencodePluginInstalled } = require('../lib/opencode-config');
+const { installOpenclawHook, probeOpenclawHookState } = require('../lib/openclaw-hook');
 const { beginBrowserAuth, openInBrowser } = require('../lib/browser-auth');
 const {
   issueDeviceTokenWithPassword,
@@ -185,7 +186,7 @@ function renderWelcome() {
       DIVIDER,
       '',
       'This tool will:',
-      '  - Analyze your local AI CLI configurations (Codex, Every Code, Claude, Gemini, Opencode)',
+      '  - Analyze your local AI CLI configurations (Codex, Every Code, Claude, Gemini, Opencode, OpenClaw)',
       '  - Set up lightweight hooks to track your flow state',
       '  - Link your device to your VibeScore account',
       '',
@@ -336,6 +337,7 @@ function buildIntegrationTargets({ home, trackerDir, notifyPath }) {
   const opencodeConfigDir = resolveOpencodeConfigDir({ home, env: process.env });
 
   return {
+    trackerDir,
     codexConfigPath,
     codeConfigPath,
     notifyOriginalPath,
@@ -406,6 +408,34 @@ async function applyIntegrationSetup({ home, trackerDir, notifyPath, notifyOrigi
     summary.push({ label: 'Opencode Plugin', status: opencodeResult?.changed ? 'installed' : 'set', detail: 'Plugin installed' });
   }
 
+  const openclawBefore = await probeOpenclawHookState({ home, trackerDir, env: process.env });
+  const openclawInstall = await installOpenclawHook({ home, trackerDir, packageName: 'vibeusage', env: process.env });
+  if (openclawInstall?.skippedReason === 'openclaw-cli-missing') {
+    summary.push({ label: 'OpenClaw Hook', status: 'skipped', detail: 'OpenClaw CLI not found' });
+  } else if (openclawInstall?.skippedReason === 'openclaw-hooks-install-failed') {
+    summary.push({
+      label: 'OpenClaw Hook',
+      status: 'skipped',
+      detail: `Install failed${openclawInstall.error ? `: ${openclawInstall.error}` : ''}`
+    });
+  } else if (openclawInstall?.skippedReason === 'openclaw-config-unreadable') {
+    summary.push({
+      label: 'OpenClaw Hook',
+      status: 'skipped',
+      detail: openclawInstall.error ? `OpenClaw config unreadable: ${openclawInstall.error}` : 'OpenClaw config unreadable'
+    });
+  } else if (openclawInstall?.configured) {
+    summary.push({
+      label: 'OpenClaw Hook',
+      status: openclawBefore?.configured ? 'set' : 'installed',
+      detail: openclawBefore?.configured
+        ? 'Hook already linked'
+        : 'Hook linked (restart OpenClaw gateway to activate)'
+    });
+  } else {
+    summary.push({ label: 'OpenClaw Hook', status: 'skipped', detail: 'OpenClaw hook unavailable' });
+  }
+
   const codeProbe = await probeFile(context.codeConfigPath);
   if (codeProbe.exists) {
     const result = await upsertEveryCodeNotify({
@@ -427,6 +457,7 @@ async function applyIntegrationSetup({ home, trackerDir, notifyPath, notifyOrigi
 
 async function previewIntegrations({ context }) {
   const summary = [];
+  const home = os.homedir();
 
   const codexProbe = await probeFile(context.codexConfigPath);
   if (codexProbe.exists) {
@@ -484,6 +515,25 @@ async function previewIntegrations({ context }) {
     detail: opencodeDetail
   });
 
+  const openclawState = await probeOpenclawHookState({ home, trackerDir: context.trackerDir, env: process.env });
+  if (openclawState?.skippedReason === 'openclaw-config-missing') {
+    summary.push({ label: 'OpenClaw Hook', status: 'skipped', detail: 'OpenClaw config not found' });
+  } else if (openclawState?.skippedReason === 'openclaw-config-unreadable') {
+    summary.push({
+      label: 'OpenClaw Hook',
+      status: 'skipped',
+      detail: openclawState.error ? `OpenClaw config unreadable: ${openclawState.error}` : 'OpenClaw config unreadable'
+    });
+  } else {
+    summary.push({
+      label: 'OpenClaw Hook',
+      status: openclawState?.configured ? 'set' : 'installed',
+      detail: openclawState?.configured
+        ? 'Hook already linked'
+        : 'Will link hook (restart OpenClaw gateway to activate)'
+    });
+  }
+
   const codeProbe = await probeFile(context.codeConfigPath);
   if (codeProbe.exists) {
     const existing = await readEveryCodeNotify(context.codeConfigPath);

package/src/commands/status.js

@@ -15,6 +15,7 @@ const { resolveOpencodeConfigDir, isOpencodePluginInstalled } = require('../lib/
 const { collectLocalSubscriptions } = require('../lib/subscriptions');
 const { normalizeState: normalizeUploadState } = require('../lib/upload-throttle');
 const { collectTrackerDiagnostics } = require('../lib/diagnostics');
+const { probeOpenclawHookState } = require('../lib/openclaw-hook');
 const { resolveTrackerPaths } = require('../lib/tracker-paths');
 
 async function cmdStatus(argv = []) {
@@ -74,6 +75,7 @@ async function cmdStatus(argv = []) {
     hookCommand: geminiHookCommand
   });
   const opencodePluginConfigured = await isOpencodePluginInstalled({ configDir: opencodeConfigDir });
+  const openclawHookState = await probeOpenclawHookState({ home, trackerDir, env: process.env });
 
   const lastUpload = uploadThrottle.lastSuccessMs
     ? parseEpochMsToIso(uploadThrottle.lastSuccessMs)
@@ -123,6 +125,7 @@ async function cmdStatus(argv = []) {
       `- Claude hooks: ${claudeHookConfigured ? 'set' : 'unset'}`,
       `- Gemini hooks: ${geminiHookConfigured ? 'set' : 'unset'}`,
       `- Opencode plugin: ${opencodePluginConfigured ? 'set' : 'unset'}`,
+      `- OpenClaw hook: ${openclawHookState?.configured ? 'set' : 'unset'}`,
       ...subscriptionLines,
       ''
     ]

package/src/commands/uninstall.js

@@ -11,6 +11,7 @@ const {
   removeGeminiHook
 } = require('../lib/gemini-config');
 const { resolveOpencodeConfigDir, removeOpencodePlugin } = require('../lib/opencode-config');
+const { removeOpenclawHookConfig } = require('../lib/openclaw-hook');
 const { resolveTrackerPaths } = require('../lib/tracker-paths');
 
 async function cmdUninstall(argv) {
@@ -61,6 +62,7 @@ async function cmdUninstall(argv) {
   const opencodeRemove = opencodeConfigExists
     ? await removeOpencodePlugin({ configDir: opencodeConfigDir })
     : { removed: false, skippedReason: 'config-missing' };
+  const openclawHookRemove = await removeOpenclawHookConfig({ home, trackerDir, env: process.env });
 
   // Remove installed notify handler.
   await fs.unlink(notifyPath).catch(() => {});
@@ -112,6 +114,11 @@ async function cmdUninstall(argv) {
               ? '- Opencode plugin: skipped (unexpected content)'
               : '- Opencode plugin: skipped'
         : `- Opencode plugin: skipped (${opencodeConfigDir} not found)`,
+      openclawHookRemove?.removed
+        ? `- OpenClaw hook removed: ${openclawHookRemove.openclawConfigPath}`
+        : openclawHookRemove?.skippedReason === 'openclaw-config-missing'
+          ? '- OpenClaw hook: skipped (openclaw config not found)'
+          : '- OpenClaw hook: no change',
       opts.purge ? `- Purged: ${path.join(home, '.vibeusage')}` : '- Purge: skipped (use --purge)',
       ''
     ].join('\n')

package/src/lib/diagnostics.js

@@ -13,6 +13,7 @@ const {
 } = require('./gemini-config');
 const { resolveOpencodeConfigDir, isOpencodePluginInstalled } = require('./opencode-config');
 const { normalizeState: normalizeUploadState } = require('./upload-throttle');
+const { probeOpenclawHookState } = require('./openclaw-hook');
 const { resolveTrackerPaths } = require('./tracker-paths');
 
 async function collectTrackerDiagnostics({
@@ -68,6 +69,7 @@ async function collectTrackerDiagnostics({
     hookCommand: geminiHookCommand
   });
   const opencodePluginConfigured = await isOpencodePluginInstalled({ configDir: opencodeConfigDir });
+  const openclawHookState = await probeOpenclawHookState({ home, trackerDir, env: process.env });
 
   const lastSuccessAt = uploadThrottle.lastSuccessMs ? new Date(uploadThrottle.lastSuccessMs).toISOString() : null;
   const autoRetryAt = parseEpochMsToIso(autoRetry?.retryAtMs);
@@ -117,7 +119,10 @@ async function collectTrackerDiagnostics({
       every_code_notify: everyCodeNotify,
       claude_hook_configured: claudeHookConfigured,
       gemini_hook_configured: geminiHookConfigured,
-      opencode_plugin_configured: opencodePluginConfigured
+      opencode_plugin_configured: opencodePluginConfigured,
+      openclaw_hook_configured: Boolean(openclawHookState?.configured),
+      openclaw_hook_linked: Boolean(openclawHookState?.linked),
+      openclaw_hook_enabled: Boolean(openclawHookState?.enabled)
     },
     upload: {
       last_success_at: lastSuccessAt,

package/src/lib/doctor.js

@@ -305,7 +305,8 @@ function buildDiagnosticsChecks(diagnostics) {
       notify.every_code_notify_configured ||
       notify.claude_hook_configured ||
       notify.gemini_hook_configured ||
-      notify.opencode_plugin_configured
+      notify.opencode_plugin_configured ||
+      notify.openclaw_hook_configured
   );
 
   checks.push({

package/src/lib/openclaw-hook.js

@@ -0,0 +1,358 @@
+const os = require('node:os');
+const path = require('node:path');
+const fs = require('node:fs/promises');
+const fssync = require('node:fs');
+const cp = require('node:child_process');
+
+const OPENCLAW_HOOK_NAME = 'vibeusage-openclaw-sync';
+const OPENCLAW_HOOK_DIRNAME = 'openclaw-hook';
+
+function resolveOpenclawHookPaths({ home = os.homedir(), trackerDir, env = process.env } = {}) {
+  if (!trackerDir) throw new Error('trackerDir is required');
+
+  const openclawConfigPath =
+    normalizeString(env.OPENCLAW_CONFIG_PATH) || path.join(home, '.openclaw', 'openclaw.json');
+
+  const openclawHome =
+    normalizeString(env.VIBEUSAGE_OPENCLAW_HOME) ||
+    normalizeString(env.OPENCLAW_STATE_DIR) ||
+    path.join(home, '.openclaw');
+
+  const hookDir = path.join(trackerDir, OPENCLAW_HOOK_DIRNAME);
+  const hookEntryDir = path.join(hookDir, OPENCLAW_HOOK_NAME);
+
+  return {
+    hookName: OPENCLAW_HOOK_NAME,
+    hookDir,
+    hookEntryDir,
+    openclawConfigPath,
+    openclawHome
+  };
+}
+
+async function installOpenclawHook({ home = os.homedir(), trackerDir, packageName = 'vibeusage', env = process.env } = {}) {
+  const paths = resolveOpenclawHookPaths({ home, trackerDir, env });
+
+  await ensureOpenclawHookFiles({
+    hookDir: paths.hookDir,
+    trackerDir,
+    packageName,
+    openclawHome: paths.openclawHome
+  });
+
+  const installResult = runOpenclawCli(['hooks', 'install', '--link', paths.hookDir], env);
+  if (installResult.skippedReason) {
+    return { configured: false, ...paths, ...installResult };
+  }
+
+  const state = await probeOpenclawHookState({ home, trackerDir, env });
+  return {
+    configured: state.configured,
+    changed: /Linked hook path:/i.test(installResult.stdout || ''),
+    ...paths,
+    stdout: installResult.stdout,
+    stderr: installResult.stderr,
+    code: installResult.code
+  };
+}
+
+async function ensureOpenclawHookFiles({ hookDir, trackerDir, packageName = 'vibeusage', openclawHome } = {}) {
+  if (!hookDir || !trackerDir) throw new Error('hookDir and trackerDir are required');
+
+  const hookEntryDir = path.join(hookDir, OPENCLAW_HOOK_NAME);
+  await fs.mkdir(hookEntryDir, { recursive: true });
+
+  const hookMdPath = path.join(hookEntryDir, 'HOOK.md');
+  const handlerPath = path.join(hookEntryDir, 'handler.js');
+
+  await fs.writeFile(hookMdPath, buildHookMarkdown(), 'utf8');
+  await fs.writeFile(
+    handlerPath,
+    buildHookHandler({ trackerDir, packageName, openclawHome: openclawHome || path.join(os.homedir(), '.openclaw') }),
+    'utf8'
+  );
+}
+
+async function probeOpenclawHookState({ home = os.homedir(), trackerDir, env = process.env } = {}) {
+  const paths = resolveOpenclawHookPaths({ home, trackerDir, env });
+  const { openclawConfigPath, hookDir, hookEntryDir, hookName } = paths;
+
+  const hookFilesReady =
+    fssync.existsSync(path.join(hookEntryDir, 'HOOK.md')) && fssync.existsSync(path.join(hookEntryDir, 'handler.js'));
+
+  let cfg = null;
+  try {
+    const raw = await fs.readFile(openclawConfigPath, 'utf8');
+    cfg = JSON.parse(raw);
+  } catch (err) {
+    if (err?.code === 'ENOENT' || err?.code === 'ENOTDIR') {
+      return {
+        configured: false,
+        enabled: false,
+        linked: false,
+        hookFilesReady,
+        skippedReason: 'openclaw-config-missing',
+        ...paths
+      };
+    }
+    return {
+      configured: false,
+      enabled: false,
+      linked: false,
+      hookFilesReady,
+      skippedReason: 'openclaw-config-unreadable',
+      error: err?.message || String(err),
+      ...paths
+    };
+  }
+
+  const enabled = Boolean(cfg?.hooks?.internal?.entries?.[hookName]?.enabled);
+  const extraDirs = Array.isArray(cfg?.hooks?.internal?.load?.extraDirs) ? cfg.hooks.internal.load.extraDirs : [];
+  const normalizedHookDir = path.resolve(hookDir);
+  const linked = extraDirs.some((entry) => path.resolve(String(entry || '')) === normalizedHookDir);
+
+  return {
+    configured: enabled && linked,
+    enabled,
+    linked,
+    hookFilesReady,
+    ...paths
+  };
+}
+
+async function removeOpenclawHookConfig({ home = os.homedir(), trackerDir, env = process.env } = {}) {
+  const paths = resolveOpenclawHookPaths({ home, trackerDir, env });
+  const { openclawConfigPath, hookDir, hookName } = paths;
+
+  let cfg;
+  try {
+    cfg = JSON.parse(await fs.readFile(openclawConfigPath, 'utf8'));
+  } catch (err) {
+    if (err?.code === 'ENOENT' || err?.code === 'ENOTDIR') {
+      return { removed: false, skippedReason: 'openclaw-config-missing', ...paths };
+    }
+    return {
+      removed: false,
+      skippedReason: 'openclaw-config-unreadable',
+      error: err?.message || String(err),
+      ...paths
+    };
+  }
+
+  let changed = false;
+  const hooks = cfg?.hooks;
+  const internal = hooks?.internal;
+
+  if (internal?.entries && Object.prototype.hasOwnProperty.call(internal.entries, hookName)) {
+    delete internal.entries[hookName];
+    changed = true;
+    if (Object.keys(internal.entries).length === 0) delete internal.entries;
+  }
+
+  if (internal?.load && Array.isArray(internal.load.extraDirs)) {
+    const before = internal.load.extraDirs;
+    const target = path.resolve(hookDir);
+    const after = before.filter((entry) => path.resolve(String(entry || '')) !== target);
+    if (after.length !== before.length) {
+      internal.load.extraDirs = after;
+      changed = true;
+      if (after.length === 0) delete internal.load.extraDirs;
+      if (Object.keys(internal.load).length === 0) delete internal.load;
+    }
+  }
+
+  if (internal?.installs && typeof internal.installs === 'object') {
+    const installs = internal.installs;
+    if (Object.prototype.hasOwnProperty.call(installs, hookName)) {
+      delete installs[hookName];
+      changed = true;
+    }
+
+    const target = path.resolve(hookDir);
+    for (const [id, entry] of Object.entries(installs)) {
+      const sourcePath = normalizeString(entry?.sourcePath);
+      const installPath = normalizeString(entry?.installPath);
+      if (
+        (sourcePath && path.resolve(sourcePath) === target) ||
+        (installPath && path.resolve(installPath) === target)
+      ) {
+        delete installs[id];
+        changed = true;
+      }
+    }
+
+    if (Object.keys(installs).length === 0) delete internal.installs;
+  }
+
+  if (internal && Object.keys(internal).length === 0) {
+    delete hooks.internal;
+    changed = true;
+  }
+  if (hooks && Object.keys(hooks).length === 0) {
+    delete cfg.hooks;
+    changed = true;
+  }
+
+  if (changed) {
+    await fs.writeFile(openclawConfigPath, `${JSON.stringify(cfg, null, 2)}\n`, 'utf8');
+  }
+
+  await fs.rm(hookDir, { recursive: true, force: true }).catch(() => {});
+
+  return { removed: changed, ...paths };
+}
+
+function runOpenclawCli(args, env = process.env) {
+  let res;
+  try {
+    res = cp.spawnSync('openclaw', args, {
+      env,
+      encoding: 'utf8',
+      timeout: 30_000
+    });
+  } catch (err) {
+    return {
+      code: 1,
+      skippedReason: err?.code === 'ENOENT' ? 'openclaw-cli-missing' : 'openclaw-cli-error',
+      error: err?.message || String(err),
+      stdout: '',
+      stderr: ''
+    };
+  }
+
+  if (res.error?.code === 'ENOENT') {
+    return {
+      code: 1,
+      skippedReason: 'openclaw-cli-missing',
+      error: res.error.message,
+      stdout: res.stdout || '',
+      stderr: res.stderr || ''
+    };
+  }
+
+  if ((res.status || 0) !== 0) {
+    return {
+      code: Number(res.status || 1),
+      skippedReason: 'openclaw-hooks-install-failed',
+      error: (res.stderr || res.stdout || '').trim() || 'openclaw hooks install failed',
+      stdout: res.stdout || '',
+      stderr: res.stderr || ''
+    };
+  }
+
+  return {
+    code: 0,
+    stdout: res.stdout || '',
+    stderr: res.stderr || ''
+  };
+}
+
+function buildHookMarkdown() {
+  return `---
+name: ${OPENCLAW_HOOK_NAME}
+description: "Trigger vibeusage sync when OpenClaw sessions roll over"
+metadata:
+  { "openclaw": { "emoji": "📈", "events": ["command:new", "command:stop"], "requires": { "bins": ["node"] } } }
+---
+
+# VibeUsage OpenClaw Sync Hook
+
+Triggers non-blocking 'vibeusage sync --auto --from-openclaw' runs when OpenClaw command events indicate a session rollover/stop.
+`;
+}
+
+function buildHookHandler({ trackerDir, packageName = 'vibeusage', openclawHome }) {
+  const trackerBinPath = path.join(trackerDir, 'app', 'bin', 'tracker.js');
+  const fallbackPkg = packageName || 'vibeusage';
+  const safeOpenclawHome = openclawHome || path.join(os.homedir(), '.openclaw');
+
+  return `'use strict';\n` +
+    `const fs = require('node:fs');\n` +
+    `const path = require('node:path');\n` +
+    `const cp = require('node:child_process');\n` +
+    `const trackerDir = ${JSON.stringify(trackerDir)};\n` +
+    `const trackerBinPath = ${JSON.stringify(trackerBinPath)};\n` +
+    `const fallbackPkg = ${JSON.stringify(fallbackPkg)};\n` +
+    `const openclawHome = ${JSON.stringify(safeOpenclawHome)};\n` +
+    `const throttlePath = path.join(trackerDir, 'openclaw.sync.throttle');\n` +
+    `const depsMarkerPath = path.join(trackerDir, 'app', 'node_modules', '@insforge', 'sdk', 'package.json');\n` +
+    `const THROTTLE_MS = 15_000;\n` +
+    `\n` +
+    `module.exports = async function handler(event) {\n` +
+    `  try {\n` +
+    `    if (!event || event.type !== 'command') return;\n` +
+    `    if (event.action !== 'new' && event.action !== 'stop') return;\n` +
+    `\n` +
+    `    const sessionKey = normalize(event.sessionKey);\n` +
+    `    const agentId = parseAgentId(sessionKey);\n` +
+    `    if (!agentId) return;\n` +
+    `\n` +
+    `    const sessionId = resolveSessionId(event);\n` +
+    `    if (!sessionId) return;\n` +
+    `\n` +
+    `    const now = Date.now();\n` +
+    `    let last = 0;\n` +
+    `    try { last = Number(fs.readFileSync(throttlePath, 'utf8')) || 0; } catch (_) {}\n` +
+    `    if (now - last < THROTTLE_MS) return;\n` +
+    `    try {\n` +
+    `      fs.mkdirSync(trackerDir, { recursive: true });\n` +
+    `      fs.writeFileSync(throttlePath, String(now), 'utf8');\n` +
+    `    } catch (_) {}\n` +
+    `\n` +
+    `    const env = {\n` +
+    `      ...process.env,\n` +
+    `      VIBEUSAGE_OPENCLAW_AGENT_ID: agentId,\n` +
+    `      VIBEUSAGE_OPENCLAW_PREV_SESSION_ID: sessionId,\n` +
+    `      VIBEUSAGE_OPENCLAW_HOME: openclawHome\n` +
+    `    };\n` +
+    `\n` +
+    `    const hasLocalRuntime = fs.existsSync(trackerBinPath);\n` +
+    `    const hasLocalDeps = fs.existsSync(depsMarkerPath);\n` +
+    `    const cmd = hasLocalRuntime && hasLocalDeps\n` +
+    `      ? [process.execPath, trackerBinPath, 'sync', '--auto', '--from-openclaw']\n` +
+    `      : ['npx', '--yes', fallbackPkg, 'sync', '--auto', '--from-openclaw'];\n` +
+    `\n` +
+    `    const child = cp.spawn(cmd[0], cmd.slice(1), { detached: true, stdio: 'ignore', env });\n` +
+    `    child.unref();\n` +
+    `  } catch (_) {}\n` +
+    `};\n` +
+    `\n` +
+    `function normalize(v) {\n` +
+    `  if (typeof v !== 'string') return null;\n` +
+    `  const s = v.trim();\n` +
+    `  return s.length > 0 ? s : null;\n` +
+    `}\n` +
+    `\n` +
+    `function parseAgentId(sessionKey) {\n` +
+    `  const s = normalize(sessionKey);\n` +
+    `  if (!s || !s.startsWith('agent:')) return null;\n` +
+    `  const parts = s.split(':');\n` +
+    `  return parts.length >= 2 ? normalize(parts[1]) : null;\n` +
+    `}\n` +
+    `\n` +
+    `function resolveSessionId(event) {\n` +
+    `  const ctx = (event && event.context && typeof event.context === 'object') ? event.context : {};\n` +
+    `  return (\n` +
+    `    normalize(ctx.previousSessionEntry && ctx.previousSessionEntry.sessionId) ||\n` +
+    `    normalize(ctx.previousSessionId) ||\n` +
+    `    normalize(ctx.sessionEntry && ctx.sessionEntry.sessionId) ||\n` +
+    `    normalize(ctx.sessionId)\n` +
+    `  );\n` +
+    `}\n`;
+}
+
+function normalizeString(value) {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+module.exports = {
+  OPENCLAW_HOOK_NAME,
+  OPENCLAW_HOOK_DIRNAME,
+  resolveOpenclawHookPaths,
+  ensureOpenclawHookFiles,
+  installOpenclawHook,
+  probeOpenclawHookState,
+  removeOpenclawHookConfig
+};