@mnemahq/cli 0.12.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemahq/cli",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Mnema CLI — connect a repo to your Mnema workspace: install session capture, sweep past sessions, and search from the terminal.",
   "type": "module",
   "bin": {

package/src/binding-stats.mjs

@@ -0,0 +1,93 @@
+/**
+ * Dev Mode Phase 5b — the miss-rate report.
+ *
+ * ⭐ ASSERT 5's FIRST BOX: "warn mode logs a real miss-rate over 7 days — paste
+ * the number." The PreToolUse hook accumulates counts into
+ * `~/.claude/hooks/state/<sessionId>.binding.json` — a local file append, never a
+ * request, because it runs before EVERY tool call. This reads them back.
+ *
+ * ⚠️ IT REPORTS ZERO AS ZERO, WITH A REASON. "0% miss rate" and "the hook never
+ * ran" produce the same number and mean opposite things, so a run with no files
+ * says so instead of printing a flattering percentage.
+ */
+
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+
+export function stateDir() { return join(homedir(), '.claude', 'hooks', 'state'); }
+
+/**
+ * Aggregate the per-session counters.
+ *
+ * @param sinceDays only files modified within this window (0 = all)
+ */
+export function collectBindingStats(sinceDays = 7, dir = stateDir()) {
+  const out = {
+    sessions: 0, hits: 0, misses: 0, branches: [],
+    missRate: null, windowDays: sinceDays, reason: null,
+  };
+  let names = [];
+  try { names = readdirSync(dir).filter((f) => f.endsWith('.binding.json')); } catch {
+    out.reason = 'no hook state directory — the PreToolUse hook has never run on this machine';
+    return out;
+  }
+  if (names.length === 0) {
+    out.reason = 'no binding counters — PreToolUse is not installed, or no tool call has run since it was';
+    return out;
+  }
+
+  const cutoff = sinceDays > 0 ? Date.now() - sinceDays * 86400000 : 0;
+  const branches = new Set();
+  for (const n of names) {
+    const p = join(dir, n);
+    try {
+      if (cutoff && statSync(p).mtimeMs < cutoff) continue;
+      const s = JSON.parse(readFileSync(p, 'utf8'));
+      out.sessions += 1;
+      out.hits += Number(s.hits) || 0;
+      out.misses += Number(s.misses) || 0;
+      for (const b of s.branches || []) branches.add(b);
+    } catch { /* a partially-written counter is skipped, not fatal */ }
+  }
+  out.branches = [...branches].sort();
+
+  const total = out.hits + out.misses;
+  if (total === 0) {
+    out.reason = `${out.sessions} counter file(s) in the window, but no tool calls recorded in them`;
+    return out;
+  }
+  out.missRate = out.misses / total;
+  return out;
+}
+
+export function formatBindingStats(s) {
+  const lines = [];
+  lines.push('');
+  lines.push(`  Task-binding miss rate — last ${s.windowDays || 'all'} day(s)`);
+  lines.push('');
+  if (s.missRate === null) {
+    // ⚠️ Never a percentage here. There is no number, and inventing 0% would
+    // read as "everything is bound" when it means "nothing was measured".
+    lines.push(`  NO DATA — ${s.reason}`);
+    lines.push('');
+    return lines.join('\n');
+  }
+  const pct = (s.missRate * 100).toFixed(1);
+  lines.push(`  sessions measured   ${s.sessions}`);
+  lines.push(`  tool calls on a task ${s.hits}`);
+  lines.push(`  tool calls with none ${s.misses}`);
+  lines.push(`  MISS RATE            ${pct}%`);
+  if (s.branches.length) {
+    lines.push('');
+    lines.push('  branches with no task:');
+    for (const b of s.branches.slice(0, 15)) lines.push(`    ${b}`);
+    if (s.branches.length > 15) lines.push(`    … ${s.branches.length - 15} more`);
+  }
+  lines.push('');
+  lines.push(s.missRate > 0.5
+    ? '  ⚠️ Above 50%. Do NOT flip enforce=block yet — it would stop most sessions.'
+    : '  Below 50%. Flipping enforce=block is defensible; do it on one install first.');
+  lines.push('');
+  return lines.join('\n');
+}

package/src/cli.mjs

@@ -30,6 +30,8 @@ import { getSecret, setSecret, deleteSecrets, backendName, usingFallback } from
 import {
   installHook, uninstallHook, hookInstalled, hookConfigPath, defaultDeveloperId, sweepScriptPath,
 } from './hook-install.mjs';
+import { installGitHooks, uninstallGitHooks } from './git-hooks.mjs';
+import { collectBindingStats, formatBindingStats } from './binding-stats.mjs';
 import { applyContext, scaffold } from './artifacts.mjs';
 import { execFileSync } from 'node:child_process';
 
@@ -196,6 +198,17 @@ async function cmdInit(flags) {
   try {
     await installHook({ origin, workspaceId, hookToken, developerId: defaultDeveloperId() });
     console.log(c.green('done'));
+
+    // Phase 5f — the portable layer. These fire for Cursor, Codex, a human, a
+    // script; the Claude hook only fires inside an agent that supports hooks.
+    // ⚠️ Repo-local and non-blocking. An existing foreign hook is never
+    // overwritten — it is reported and left alone.
+    const g = installGitHooks();
+    if (g.ok && g.installed.length) console.log(`  git hooks: ${g.installed.join(', ')} (warn only)`);
+    if (g.ok && g.skipped.length) {
+      for (const s2 of g.skipped) console.log(c.yellow(`  git hook ${s2.name} SKIPPED — ${s2.reason}`));
+    }
+    if (!g.ok) console.log(c.dim(`  git hooks: skipped — ${g.reason}`));
   } catch (e) {
     console.log(c.red('failed'));
     console.error(`  ${e.message}`);
@@ -479,6 +492,9 @@ async function cmdDoctor(flags) {
 async function cmdUninstall(flags) {
   const { root, workspaceId } = resolveContext(flags);
   uninstallHook();
+  // Only removes hooks carrying our marker — a foreign pre-push is left alone.
+  const gone = uninstallGitHooks();
+  if (gone.removed.length) console.log(`  git hooks removed: ${gone.removed.join(', ')}`);
   if (workspaceId) deleteSecrets(workspaceId);
   let purge = flags.purge === true;
   if (!purge && process.stdin.isTTY) {
@@ -647,6 +663,17 @@ export async function run(argv) {
   // That is this repo's characteristic bug aimed at its own test suite.
   if (flags.help || flags.h) { help(); return; }
   const cmd = rest.shift();
+/**
+ * Phase 5b — print the measured task-binding miss rate.
+ *
+ * ⭐ This is ASSERT 5's first box. It exists so the decision to flip
+ * enforce=block is made against a number rather than a hunch.
+ */
+function cmdBinding(flags) {
+  const days = flags.limit ? Number(flags.limit) : 7;
+  console.log(formatBindingStats(collectBindingStats(Number.isFinite(days) ? days : 7)));
+}
+
   switch (cmd) {
     case 'login':     return cmdLogin(flags);
     case 'logout':    return cmdLogout();
@@ -657,6 +684,7 @@ export async function run(argv) {
     case 'pull':      return cmdPull(flags);
     case 'search':    return cmdSearch(flags, rest);
     case 'doctor':    return cmdDoctor(flags);
+    case 'binding':   return cmdBinding(flags);
     case 'uninstall': return cmdUninstall(flags);
 
     // Reads. Each resolves context once and hands the SDK client to a wrapper;

package/src/git-hooks.mjs

@@ -0,0 +1,174 @@
+/**
+ * Dev Mode Phase 5f — the portable git-hook layer.
+ *
+ * ⭐ WHY GIT HOOKS AS WELL AS CLAUDE HOOKS. The PreToolUse warning only fires
+ * inside an agent that supports hooks. These two fire for ANYONE committing in
+ * the repo — Cursor, Codex, a human, a script — which is what makes task binding
+ * a property of the repository rather than of one tool. Audit C5: no husky, no
+ * lefthook, no pre-commit, so this is a clean install with nothing to merge.
+ *
+ * ⚠️ REPO-LOCAL, NEVER GLOBAL. `core.hooksPath` is not touched: setting it would
+ * silently redirect hooks for every repo on the machine, and someone would spend
+ * a day finding out why. These are written into THIS repo's .git/hooks.
+ *
+ * ⚠️ NEITHER HOOK BLOCKS ON DAY ONE. `prepare-commit-msg` only ADDS a trailer;
+ * `pre-push` warns to stderr and exits 0. 80% of branches carry no task (audit
+ * B3), so blocking would stop nearly every push. `pre-push` reads
+ * MNEMA_ENFORCE=block to become blocking, the same switch 5c uses.
+ *
+ * ⚠️ `--no-verify` BYPASSES BOTH, AND THAT IS FINE — it is git's own escape
+ * hatch and pretending otherwise invites someone to disable the hooks entirely.
+ * The bypass is documented in the hook body so it is discoverable rather than
+ * folklore.
+ */
+
+import { join } from 'node:path';
+import { writeFileSync, existsSync, readFileSync, chmodSync, rmSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+
+const MARKER = '# mnema-task-binding';
+
+/** The repo root, or null when not inside a git work tree. */
+export function repoRoot(cwd = process.cwd()) {
+  try {
+    return execFileSync('git', ['rev-parse', '--show-toplevel'], {
+      cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim() || null;
+  } catch { return null; }
+}
+
+export function gitHooksDir(cwd = process.cwd()) {
+  const root = repoRoot(cwd);
+  return root ? join(root, '.git', 'hooks') : null;
+}
+
+/**
+ * Injects `Task: t-<n>` as a trailer when the branch names a task and the message
+ * does not already carry one.
+ *
+ * ⚠️ Same token-boundary rule as everywhere else: `revert-t-5-fix` names nothing.
+ * A trailer is additive — it never rewrites what the author wrote.
+ */
+export const PREPARE_COMMIT_MSG = `#!/bin/sh
+${MARKER}
+# Adds a "Task: t-<n>" trailer when the branch names a task. Never blocks.
+# Bypass: git commit --no-verify
+msg_file="$1"
+src="$2"
+[ "$src" = "merge" ] && exit 0
+[ "$src" = "squash" ] && exit 0
+
+# ⚠️ symbolic-ref, NOT rev-parse. Before the first commit, rev-parse
+# --abbrev-ref HEAD FAILS and prints the literal "HEAD", which the exempt
+# list below then swallows — so the hook silently did nothing on the very
+# first commit in a repo. symbolic-ref answers correctly with no commits, and
+# fails cleanly (empty) in detached HEAD, which is what we want to skip.
+branch=$(git symbolic-ref --short -q HEAD 2>/dev/null || true)
+case "$branch" in
+  main|master|HEAD|"") exit 0 ;;
+esac
+
+# t-<n> must sit on a token boundary: start, or after / _ .
+# ⚠️ grep -Eo, NOT sed. The first version used \`sed -n 's/...\\|.../'\` and returned
+# EMPTY FOR EVERY BRANCH: \`\\|\` alternation is a GNU extension BSD sed does not have,
+# and \`^\` inside a group is not an anchor. It was found by RUNNING it, not reading it.
+task=$(printf '%s' "$branch" | grep -Eo '(^|[/_.])t-[0-9]+([-/_.]|$)' | head -1 | grep -Eo 't-[0-9]+' | head -1)
+[ -z "$task" ] && exit 0
+
+grep -qi "^Task: " "$msg_file" && exit 0
+printf '\\nTask: %s\\n' "$task" >> "$msg_file"
+exit 0
+`;
+
+/**
+ * Warns (or blocks, under MNEMA_ENFORCE=block) when pushing a branch that names
+ * no task.
+ *
+ * ⚠️ Never fires on main/master — pushing the default branch is not task-bound
+ * work, and warning there teaches people to ignore the warning.
+ */
+export const PRE_PUSH = `#!/bin/sh
+${MARKER}
+# Warns when the branch names no task. Blocks only when MNEMA_ENFORCE=block.
+# Bypass: git push --no-verify
+# ⚠️ symbolic-ref, NOT rev-parse. Before the first commit, rev-parse
+# --abbrev-ref HEAD FAILS and prints the literal "HEAD", which the exempt
+# list below then swallows — so the hook silently did nothing on the very
+# first commit in a repo. symbolic-ref answers correctly with no commits, and
+# fails cleanly (empty) in detached HEAD, which is what we want to skip.
+branch=$(git symbolic-ref --short -q HEAD 2>/dev/null || true)
+case "$branch" in
+  main|master|HEAD|"") exit 0 ;;
+esac
+
+# ⚠️ grep -Eo, NOT sed. The first version used \`sed -n 's/...\\|.../'\` and returned
+# EMPTY FOR EVERY BRANCH: \`\\|\` alternation is a GNU extension BSD sed does not have,
+# and \`^\` inside a group is not an anchor. It was found by RUNNING it, not reading it.
+task=$(printf '%s' "$branch" | grep -Eo '(^|[/_.])t-[0-9]+([-/_.]|$)' | head -1 | grep -Eo 't-[0-9]+' | head -1)
+[ -n "$task" ] && exit 0
+
+printf '\\n  [mnema] Pushing a branch that names no task: %s\\n' "$branch" >&2
+printf '  Nothing on the board will link to this work.\\n' >&2
+if [ "$MNEMA_ENFORCE" = "block" ]; then
+  printf '  Enforcement is set to block. Rename the branch, or push with --no-verify.\\n\\n' >&2
+  exit 1
+fi
+printf '  Not blocked. Rename it t-<n>-<slug> to link it.\\n\\n' >&2
+exit 0
+`;
+
+const HOOKS = [
+  ['prepare-commit-msg', PREPARE_COMMIT_MSG],
+  ['pre-push', PRE_PUSH],
+];
+
+/**
+ * Install both hooks into this repo.
+ *
+ * ⚠️ AN EXISTING HOOK THAT IS NOT OURS IS NEVER OVERWRITTEN. It is reported and
+ * skipped — silently clobbering someone's pre-push is the kind of "helpful"
+ * install that loses trust permanently. Ours carries a marker line, so re-running
+ * upgrades our own and only our own.
+ */
+export function installGitHooks(cwd = process.cwd()) {
+  const dir = gitHooksDir(cwd);
+  if (!dir) return { ok: false, reason: 'not a git repository', installed: [], skipped: [] };
+
+  const installed = [];
+  const skipped = [];
+  for (const [name, body] of HOOKS) {
+    const p = join(dir, name);
+    if (existsSync(p)) {
+      let existing = '';
+      try { existing = readFileSync(p, 'utf8'); } catch { /* unreadable */ }
+      if (!existing.includes(MARKER)) { skipped.push({ name, reason: 'a different hook is already installed' }); continue; }
+    }
+    try {
+      writeFileSync(p, body, { mode: 0o755 });
+      chmodSync(p, 0o755);
+      installed.push(name);
+    } catch (e) {
+      skipped.push({ name, reason: String(e && e.message ? e.message : e) });
+    }
+  }
+  return { ok: true, reason: null, installed, skipped };
+}
+
+/** Remove only the hooks we wrote — identified by the marker, never by name. */
+export function uninstallGitHooks(cwd = process.cwd()) {
+  const dir = gitHooksDir(cwd);
+  if (!dir) return { removed: [], kept: [] };
+  const removed = [];
+  const kept = [];
+  for (const [name] of HOOKS) {
+    const p = join(dir, name);
+    if (!existsSync(p)) continue;
+    let body = '';
+    try { body = readFileSync(p, 'utf8'); } catch { /* ignore */ }
+    if (!body.includes(MARKER)) { kept.push(name); continue; }
+    try { rmSync(p); removed.push(name); } catch { kept.push(name); }
+  }
+  return { removed, kept };
+}
+
+export { MARKER as GIT_HOOK_MARKER };

package/src/hook-install.mjs

@@ -8,7 +8,11 @@ import { homedir, userInfo, hostname } from 'node:os';
 import { join, dirname } from 'node:path';
 import { mkdirSync, writeFileSync, existsSync, readFileSync, rmSync, chmodSync } from 'node:fs';
 
-const HOOK_EVENTS = ['SessionStart', 'SessionEnd', 'Stop', 'PostToolUse', 'PostToolUseFailure'];
+// ⚠️ PreToolUse (Phase 5a) is the ONLY event that runs before a tool, so it is the
+// only one whose cost is felt. It is local-only — a git call and a file append,
+// no API round-trip — and it exits 0 always. The installer merges idempotently,
+// so adding it here upgrades existing installs on the next `mnema hook install`.
+const HOOK_EVENTS = ['SessionStart', 'SessionEnd', 'Stop', 'PostToolUse', 'PostToolUseFailure', 'PreToolUse'];
 
 export function claudeDir() { return join(homedir(), '.claude'); }
 export function hooksDir() { return join(claudeDir(), 'hooks'); }