lakonai 0.6.1

package/src/hooks/version-check.js

@@ -0,0 +1,177 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const https = require('https');
+const http = require('http');
+
+const CHECK_TTL_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 1500;
+const REGISTRY_URL = 'https://registry.npmjs.org/lakon/latest';
+
+function lakonHome() {
+  /* c8 ignore next */
+  return process.env.LAKON_HOME || path.join(os.homedir(), '.lakon');
+}
+
+function cachePath() {
+  return path.join(lakonHome(), 'version.json');
+}
+
+function readCache() {
+  try {
+    return JSON.parse(fs.readFileSync(cachePath(), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(data) {
+  try {
+    fs.mkdirSync(lakonHome(), { recursive: true });
+    fs.writeFileSync(cachePath(), JSON.stringify(data));
+    /* c8 ignore next 3 */
+  } catch {
+    // never let cache write break anything
+  }
+}
+
+function installedVersionMarkerPath() {
+  return path.join(lakonHome(), 'installed-version.json');
+}
+
+function currentVersion() {
+  try {
+    return JSON.parse(fs.readFileSync(installedVersionMarkerPath(), 'utf8')).version;
+  } catch {
+    // ignore — fall through to package.json lookup
+  }
+  try {
+    return require('../../package.json').version;
+    /* c8 ignore next 3 */
+  } catch {
+    return null;
+  }
+}
+
+function writeInstalledVersionMarker(version) {
+  try {
+    fs.mkdirSync(lakonHome(), { recursive: true });
+    fs.writeFileSync(installedVersionMarkerPath(), JSON.stringify({ version }));
+    /* c8 ignore next 3 */
+  } catch {
+    // never let marker write break install
+  }
+}
+
+function semverCmp(a, b) {
+  const pa = String(a).split('.').map((x) => parseInt(x, 10) || 0);
+  const pb = String(b).split('.').map((x) => parseInt(x, 10) || 0);
+  for (let i = 0; i < 3; i++) {
+    const da = pa[i] || 0;
+    const db = pb[i] || 0;
+    if (da !== db) return da - db;
+  }
+  return 0;
+}
+
+/* c8 ignore next */
+function fetchLatest(url = process.env.LAKON_REGISTRY_URL || REGISTRY_URL, timeout = FETCH_TIMEOUT_MS) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (v) => {
+      if (!settled) {
+        settled = true;
+        resolve(v);
+      }
+    };
+    try {
+      /* c8 ignore next */
+      const client = url.startsWith('http://') ? http : https;
+      const req = client.get(url, { timeout }, (res) => {
+        if (res.statusCode !== 200) {
+          res.resume();
+          finish(null);
+          return;
+        }
+        let body = '';
+        res.on('data', (c) => (body += c));
+        res.on('end', () => {
+          try {
+            /* c8 ignore next */
+            finish(JSON.parse(body).version || null);
+          } catch {
+            finish(null);
+          }
+        });
+      });
+      req.on('error', () => finish(null));
+      req.on('timeout', () => {
+        try { req.destroy(); /* c8 ignore next */ } catch {}
+        finish(null);
+      });
+      /* c8 ignore next 3 */
+    } catch {
+      finish(null);
+    }
+  });
+}
+
+function isDisabled() {
+  return process.env.LAKON_NO_UPDATE_CHECK === '1';
+}
+
+async function checkForUpdate({ force = false } = {}) {
+  if (isDisabled()) return null;
+  const current = currentVersion();
+  /* c8 ignore next */
+  if (!current) return null;
+
+  const cache = readCache();
+  const now = Date.now();
+  const fresh = cache && typeof cache.t === 'number' && now - cache.t < CHECK_TTL_MS;
+
+  if (!force && fresh) {
+    if (cache.latest && semverCmp(cache.latest, current) > 0) {
+      return { current, latest: cache.latest, available: true };
+    }
+    return null;
+  }
+
+  const latest = await fetchLatest();
+  if (latest) writeCache({ t: now, latest });
+  if (latest && semverCmp(latest, current) > 0) {
+    return { current, latest, available: true };
+  }
+  return null;
+}
+
+function getCachedUpdate() {
+  if (isDisabled()) return null;
+  const current = currentVersion();
+  /* c8 ignore next */
+  if (!current) return null;
+  const cache = readCache();
+  if (!cache || !cache.latest) return null;
+  if (semverCmp(cache.latest, current) > 0) {
+    return { current, latest: cache.latest, available: true };
+  }
+  return null;
+}
+
+function formatNotice(info) {
+  return `lakon ${info.latest} available (you have ${info.current}). Update: npm i -g lakon@latest`;
+}
+
+module.exports = {
+  checkForUpdate,
+  getCachedUpdate,
+  formatNotice,
+  semverCmp,
+  currentVersion,
+  cachePath,
+  fetchLatest,
+  writeInstalledVersionMarker,
+  installedVersionMarkerPath,
+};

package/src/install/backup.js

@@ -0,0 +1,70 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+function backupRoot() {
+  const base = process.env.LAKON_HOME || path.join(os.homedir(), '.lakon');
+  return path.join(base, 'backups');
+}
+
+function platformDir(platformId) {
+  return path.join(backupRoot(), platformId);
+}
+
+function manifestPath(platformId) {
+  return path.join(platformDir(platformId), 'manifest.json');
+}
+
+function listBackups(platformId) {
+  try { return JSON.parse(fs.readFileSync(manifestPath(platformId), 'utf8')); }
+  catch { return []; }
+}
+
+function hasBackupFor(platformId, filePath) {
+  return listBackups(platformId).some((e) => e.source === filePath);
+}
+
+function backupFile(platformId, filePath, { skipIfExists = true } = {}) {
+  if (!fs.existsSync(filePath)) return null;
+  if (skipIfExists && hasBackupFor(platformId, filePath)) return null;
+
+  const dir = platformDir(platformId);
+  fs.mkdirSync(dir, { recursive: true });
+  const ts = Date.now();
+  const dest = path.join(dir, `${path.basename(filePath)}.${ts}.bak`);
+  fs.copyFileSync(filePath, dest);
+
+  const entries = listBackups(platformId);
+  entries.push({ ts, source: filePath, backup: dest });
+  fs.writeFileSync(manifestPath(platformId), JSON.stringify(entries, null, 2));
+  return dest;
+}
+
+function latestPerSource(platformId) {
+  const entries = listBackups(platformId);
+  const bySource = new Map();
+  for (const e of entries) bySource.set(e.source, e);
+  return [...bySource.values()];
+}
+
+function restoreAllBackups(platformId) {
+  const entries = latestPerSource(platformId);
+  const restored = [];
+  for (const entry of entries) {
+    if (!fs.existsSync(entry.backup)) continue;
+    fs.mkdirSync(path.dirname(entry.source), { recursive: true });
+    fs.copyFileSync(entry.backup, entry.source);
+    restored.push(entry);
+  }
+  return restored;
+}
+
+module.exports = {
+  backupFile,
+  listBackups,
+  hasBackupFor,
+  restoreAllBackups,
+  backupRoot,
+};

package/src/install/claude-commands.js

@@ -0,0 +1,71 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { claudeConfigDir } = require('./paths');
+
+const COMMANDS = [
+  {
+    name: 'gain',
+    body: `---
+description: Show lakon token savings (raw vs filtered, per window and top commands).
+allowed-tools: Bash(lakon gain:*), Bash(lak gain:*)
+---
+
+Run \`lakon gain\` and show the output verbatim. Do not summarize — the table is the answer.
+`,
+  },
+  {
+    name: 'reset',
+    body: `---
+description: Wipe the lakon savings log.
+allowed-tools: Bash(lakon reset:*)
+---
+
+Run \`lakon reset\` and show the output. Confirm with the user before running if they didn't explicitly ask to clear.
+`,
+  },
+  {
+    name: 'inspect',
+    body: `---
+description: Run a command once through lakon and compare raw vs filtered token counts.
+argument-hint: <command> [args...]
+allowed-tools: Bash(lakon inspect:*)
+---
+
+Run \`lakon inspect $ARGUMENTS\` and show the output verbatim.
+`,
+  },
+];
+
+function commandsDir(home) {
+  return path.join(claudeConfigDir(home), 'commands', 'lakon');
+}
+
+function installCommands(home) {
+  const dir = commandsDir(home);
+  fs.mkdirSync(dir, { recursive: true });
+  const written = [];
+  for (const c of COMMANDS) {
+    const p = path.join(dir, `${c.name}.md`);
+    fs.writeFileSync(p, c.body, 'utf8');
+    written.push(`/lakon:${c.name}`);
+  }
+  return written;
+}
+
+function uninstallCommands(home) {
+  const dir = commandsDir(home);
+  const removed = [];
+  for (const c of COMMANDS) {
+    const p = path.join(dir, `${c.name}.md`);
+    try { fs.unlinkSync(p); removed.push(p); } catch {}
+  }
+  try {
+    const left = fs.readdirSync(dir);
+    if (!left.length) fs.rmdirSync(dir);
+  } catch {}
+  return removed;
+}
+
+module.exports = { installCommands, uninstallCommands, commandsDir };

package/src/install/claude-hook.js

@@ -0,0 +1,177 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { backupFile } = require('./backup');
+const { claudeConfigDir } = require('./paths');
+
+const HOOKS = [
+  {
+    basename: 'lakon-bash-rewrite.js',
+    src: path.join(__dirname, '..', 'hooks', 'bash-rewrite.js'),
+    event: 'PreToolUse',
+    matcher: 'Bash',
+  },
+  {
+    basename: 'lakon-read-guard.js',
+    src: path.join(__dirname, '..', 'hooks', 'read-guard.js'),
+    event: 'PreToolUse',
+    matcher: 'Read',
+  },
+  {
+    basename: 'lakon-grep-guard.js',
+    src: path.join(__dirname, '..', 'hooks', 'grep-guard.js'),
+    event: 'PreToolUse',
+    matcher: 'Grep',
+  },
+  {
+    basename: 'lakon-stop-hook.js',
+    src: path.join(__dirname, '..', 'hooks', 'stop-hook.js'),
+    event: 'Stop',
+    matcher: null,
+  },
+  {
+    basename: 'lakon-session-start.js',
+    src: path.join(__dirname, '..', 'hooks', 'session-start.js'),
+    event: 'SessionStart',
+    matcher: null,
+  },
+];
+
+const SUPPORT_FILES = [
+  { basename: 'throttle.js', src: path.join(__dirname, '..', 'hooks', 'throttle.js') },
+  { basename: 'version-check.js', src: path.join(__dirname, '..', 'hooks', 'version-check.js') },
+];
+
+const ALL_BASENAMES = [...HOOKS.map((h) => h.basename), ...SUPPORT_FILES.map((s) => s.basename)];
+
+function hookDest(home, basename) {
+  return path.join(claudeConfigDir(home), 'hooks', basename);
+}
+
+function settingsPath(home) {
+  return path.join(claudeConfigDir(home), 'settings.json');
+}
+
+function readSettings(home) {
+  const p = settingsPath(home);
+  if (!fs.existsSync(p)) return { ok: true, data: {} };
+  try {
+    return { ok: true, data: JSON.parse(fs.readFileSync(p, 'utf8')) };
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+}
+
+function writeSettings(home, data) {
+  fs.writeFileSync(settingsPath(home), JSON.stringify(data, null, 2) + '\n', 'utf8');
+}
+
+function entryHasHook(entry, basename) {
+  /* c8 ignore next */
+  if (!entry || !Array.isArray(entry.hooks)) return false;
+  return entry.hooks.some((h) => h && typeof h.command === 'string' && h.command.includes(basename));
+}
+
+function mergeHook(data, hookDef, dest) {
+  /* c8 ignore next */
+  const eventKey = hookDef.event || 'PreToolUse';
+  data.hooks = data.hooks || {};
+  data.hooks[eventKey] = data.hooks[eventKey] || [];
+
+  if (hookDef.matcher) {
+    const existing = data.hooks[eventKey].find((e) => e.matcher === hookDef.matcher);
+    if (existing) {
+      if (!entryHasHook(existing, hookDef.basename)) {
+        /* c8 ignore next */
+        existing.hooks = existing.hooks || [];
+        existing.hooks.push({ type: 'command', command: dest });
+      }
+    } else {
+      data.hooks[eventKey].push({
+        matcher: hookDef.matcher,
+        hooks: [{ type: 'command', command: dest }],
+      });
+    }
+  } else {
+    const existing = data.hooks[eventKey].find(
+      (e) => !e.matcher && entryHasHook(e, hookDef.basename)
+    );
+    if (!existing) {
+      data.hooks[eventKey].push({
+        hooks: [{ type: 'command', command: dest }],
+      });
+    }
+  }
+}
+
+function installHook(home) {
+  const sp = settingsPath(home);
+  if (fs.existsSync(sp)) backupFile('claude-code', sp);
+
+  const { ok, data, error } = readSettings(home);
+  if (!ok) {
+    return { hookFile: null, settingsMerged: false, note: `settings.json could not be parsed (${error}). Add hook entries manually — see README.` };
+  }
+
+  const installed = [];
+  for (const s of SUPPORT_FILES) {
+    const dest = hookDest(home, s.basename);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(s.src, dest);
+    fs.chmodSync(dest, 0o644);
+  }
+  for (const h of HOOKS) {
+    const dest = hookDest(home, h.basename);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(h.src, dest);
+    fs.chmodSync(dest, 0o755);
+    mergeHook(data, h, dest);
+    installed.push(dest);
+  }
+
+  writeSettings(home, data);
+
+  try {
+    const { writeInstalledVersionMarker } = require('../hooks/version-check');
+    writeInstalledVersionMarker(require('../../package.json').version);
+    /* c8 ignore next 3 */
+  } catch {
+    // never let marker write break install
+  }
+
+  return { hookFile: installed.join(', '), settingsMerged: true };
+}
+
+function uninstallHook(home) {
+  const { ok, data } = readSettings(home);
+  if (ok && data.hooks && typeof data.hooks === 'object') {
+    for (const eventKey of Object.keys(data.hooks)) {
+      /* c8 ignore next */
+      if (!Array.isArray(data.hooks[eventKey])) continue;
+      data.hooks[eventKey] = data.hooks[eventKey]
+        .map((entry) => {
+          /* c8 ignore next */
+          if (!Array.isArray(entry.hooks)) return entry;
+          const remaining = entry.hooks.filter(
+            (h) => !(h.command && ALL_BASENAMES.some((b) => h.command.includes(b)))
+          );
+          if (remaining.length === 0) return null;
+          return { ...entry, hooks: remaining };
+        })
+        .filter(Boolean);
+      if (data.hooks[eventKey].length === 0) delete data.hooks[eventKey];
+    }
+    if (Object.keys(data.hooks).length === 0) delete data.hooks;
+    if (fs.existsSync(settingsPath(home))) writeSettings(home, data);
+  }
+
+  for (const h of [...HOOKS, ...SUPPORT_FILES]) {
+    const dest = hookDest(home, h.basename);
+    if (fs.existsSync(dest)) {
+      try { fs.unlinkSync(dest); /* c8 ignore next */ } catch {}
+    }
+  }
+}
+
+module.exports = { installHook, uninstallHook, hookDest, HOOK_BASENAMES: ALL_BASENAMES };

package/src/install/index.js

@@ -0,0 +1,159 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const platforms = require('./platforms');
+const { listBackups } = require('./backup');
+
+const RULE_PATH = path.join(__dirname, '..', 'rules', 'caveman.md');
+
+const OK = '✅';
+const FAIL = '❌';
+const ARROW = '→';
+const BULLET = '•';
+
+function readRule() {
+  return fs.readFileSync(RULE_PATH, 'utf8');
+}
+
+function shortenPath(p) {
+  /* c8 ignore next */
+  if (!p) return p;
+  const home = os.homedir();
+  if (p.startsWith(home)) return '~' + p.slice(home.length);
+  return p;
+}
+
+function padLabel(label, width = 26) {
+  /* c8 ignore next */
+  return label.length >= width ? label : label + ' '.repeat(width - label.length);
+}
+
+function detectPlatforms() {
+  const home = os.homedir();
+  return platforms.list().filter((p) => p.detect(home));
+}
+
+async function install({ only, here = false } = {}) {
+  const rule = readRule();
+  const home = os.homedir();
+  const all = platforms.list();
+
+  let targets;
+  if (only) {
+    targets = all.filter((p) => p.id === only);
+  } else {
+    targets = detectPlatforms().filter((p) => p.scope === 'global');
+    if (here) {
+      targets = targets.concat(all.filter((p) => p.scope === 'project'));
+    }
+  }
+
+  if (!targets.length) {
+    if (only) {
+      process.stdout.write(`${FAIL} unknown platform "${only}". Run \`lakon list\` to see options.\n`);
+    } else {
+      process.stdout.write(`${FAIL} no supported global platforms detected. Install Claude Code, Codex, or Gemini CLI first — or run \`lakon install --here\` to write per-project rules (Cursor/Windsurf/Cline) in the current directory.\n`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  process.stdout.write('\nlakon install\n');
+  process.stdout.write('─────────────\n');
+
+  for (const p of targets) {
+    try {
+      const result = p.install({ home, rule, id: p.id });
+      process.stdout.write(`${OK} ${padLabel(p.label)} ${ARROW} ${shortenPath(result)}\n`);
+    } catch (err) {
+      process.stdout.write(`${FAIL} ${padLabel(p.label)} ${ARROW} ${err.message}\n`);
+      process.exitCode = 1;
+    }
+  }
+
+  process.stdout.write('\n');
+  if (!only && !here) {
+    process.stdout.write(`  ${BULLET} Per-project rules (Cursor/Windsurf/Cline) were skipped.\n`);
+    process.stdout.write(`    Inside a repo? Run \`lakon install --here\` to add them in the current directory.\n`);
+  }
+  process.stdout.write(`  ${BULLET} \`lakon uninstall\` removes only the lakon block (keeps your other content).\n`);
+  process.stdout.write(`  ${BULLET} \`lakon revert\`    restores files to pre-install state from backup.\n`);
+  process.stdout.write(`  ${BULLET} \`lakon gain\`      shows how many tokens you've saved.\n`);
+  process.stdout.write('\nRestart your AI agent (or open a new session) for the rule to take effect.\n');
+}
+
+async function uninstall() {
+  const home = os.homedir();
+  process.stdout.write('\nlakon uninstall\n');
+  process.stdout.write('───────────────\n');
+  let any = false;
+  for (const p of platforms.list()) {
+    try {
+      const result = p.uninstall({ home });
+      if (result) {
+        process.stdout.write(`${OK} ${padLabel(p.label)} ${ARROW} removed from ${shortenPath(result)}\n`);
+        any = true;
+      }
+    } catch (err) {
+      process.stdout.write(`${FAIL} ${padLabel(p.label)} ${ARROW} ${err.message}\n`);
+    }
+  }
+  if (!any) process.stdout.write('  (nothing installed)\n');
+}
+
+async function revert({ only } = {}) {
+  const targets = only
+    ? platforms.list().filter((p) => p.id === only)
+    : platforms.list();
+
+  process.stdout.write('\nlakon revert\n');
+  process.stdout.write('────────────\n');
+
+  let any = false;
+  for (const p of targets) {
+    const entries = platforms.revertPlatform(p.id);
+    if (entries && entries.length) {
+      for (const entry of entries) {
+        const when = new Date(entry.ts).toISOString().replace('T', ' ').slice(0, 19);
+        process.stdout.write(`${OK} ${padLabel(p.label)} ${ARROW} ${shortenPath(entry.source)}\n`);
+        process.stdout.write(`   ${' '.repeat(25)} (restored from backup taken ${when})\n`);
+      }
+      any = true;
+    }
+  }
+  if (!any) {
+    process.stdout.write(`${FAIL} no backups found. (Backups only exist for files that already had content before install.)\n`);
+  }
+}
+
+function backupsReport() {
+  const lines = ['', 'lakon — backup history', '──────────────────────'];
+  let any = false;
+  for (const p of platforms.list()) {
+    const entries = listBackups(p.id);
+    if (!entries.length) continue;
+    any = true;
+    lines.push('');
+    lines.push(`${p.label} (${p.id}):`);
+    for (const e of entries) {
+      const when = new Date(e.ts).toISOString().replace('T', ' ').slice(0, 19);
+      lines.push(`  ${when}  ${shortenPath(e.source)}`);
+      lines.push(`      ${ARROW} ${shortenPath(e.backup)}`);
+    }
+  }
+  if (!any) lines.push('\n  (no backups yet)');
+  return lines.join('\n') + '\n';
+}
+
+function listPlatforms() {
+  return platforms.list().map((p) => {
+    const detected = p.detect(os.homedir());
+    const mark = detected ? OK : ' ';
+    const scope = p.scope === 'project' ? '[project]' : '[global] ';
+    return `${mark}  ${p.id.padEnd(14)} ${scope} ${p.label}`;
+  });
+}
+
+module.exports = { install, uninstall, revert, listPlatforms, backupsReport };

package/src/install/paths.js

@@ -0,0 +1,9 @@
+'use strict';
+
+const path = require('path');
+
+function claudeConfigDir(home) {
+  return process.env.CLAUDE_CONFIG_DIR || path.join(home, '.claude');
+}
+
+module.exports = { claudeConfigDir };