thumbgate 1.4.1 → 1.4.3

package/scripts/auto-wire-hooks.js

@@ -94,6 +94,64 @@ function hookAlreadyPresent(hookArray, command) {
   );
 }
 
+/**
+ * pruneStaleFileHooks — Remove hook entries whose command references a shell
+ * script path that no longer exists on disk.
+ *
+ * Only paths that look like file references (contain a `/` or `\`, or end with
+ * `.sh`) are checked.  Pure command strings (node calls, npx invocations, etc.)
+ * are left untouched.
+ *
+ * @param {Array}  hookArray  - The array of hook-entry objects for one lifecycle.
+ * @param {string} [baseDir]  - Directory used to resolve relative paths
+ *                              (defaults to process.cwd()).
+ * @returns {{ hooks: Array, removedPaths: string[] }}
+ */
+function pruneStaleFileHooks(hookArray, baseDir) {
+  if (!Array.isArray(hookArray)) {
+    return { hooks: [], removedPaths: [] };
+  }
+
+  const resolveBase = baseDir || process.cwd();
+  const removedPaths = [];
+
+  const hooks = hookArray.filter((entry) => {
+    const entryHooks = Array.isArray(entry && entry.hooks) ? entry.hooks : [];
+    let shouldRemove = false;
+
+    for (const hook of entryHooks) {
+      const command = hook && typeof hook.command === 'string' ? hook.command : '';
+      if (!command) continue;
+
+      // Extract the first token as the potential script path.
+      const firstToken = command.split(/\s+/)[0];
+
+      // Only treat it as a file reference if it looks like a path.
+      const looksLikePath =
+        firstToken.includes('/') ||
+        firstToken.includes('\\') ||
+        firstToken.endsWith('.sh');
+
+      if (!looksLikePath) continue;
+
+      // Resolve the path (absolute or relative to baseDir).
+      const resolved = path.isAbsolute(firstToken)
+        ? firstToken
+        : path.resolve(resolveBase, firstToken);
+
+      if (!fs.existsSync(resolved)) {
+        removedPaths.push(firstToken);
+        shouldRemove = true;
+        break;
+      }
+    }
+
+    return !shouldRemove;
+  });
+
+  return { hooks, removedPaths };
+}
+
 function pruneLegacyHookEntries(hookArray, expectedCommand, legacyPattern) {
   if (!Array.isArray(hookArray)) {
     return { hooks: [], removed: false };
@@ -131,12 +189,78 @@ function syncClaudeStatusLine(settingsPath, desiredStatusLine, dryRun) {
   return true;
 }
 
+/**
+ * claudeProjectSettingsPath — returns the project-level .claude/settings.json
+ * path relative to the given base directory (defaults to CWD).
+ */
+function claudeProjectSettingsPath(baseDir) {
+  return path.join(baseDir || process.cwd(), '.claude', 'settings.json');
+}
+
+/**
+ * pruneStaleHooksInFile — reads a settings file, removes any hook entries that
+ * reference missing shell script files, and writes the file back if changed.
+ *
+ * @param {string}  filePath - Absolute path to the settings JSON file.
+ * @param {string}  baseDir  - Base directory for resolving relative script paths.
+ * @param {boolean} dryRun   - When true, changes are computed but not persisted.
+ * @returns {{ changed: boolean, removedPaths: string[] }}
+ */
+function pruneStaleHooksInFile(filePath, baseDir, dryRun) {
+  const settings = loadJsonFile(filePath);
+  if (!settings || !settings.hooks || typeof settings.hooks !== 'object') {
+    return { changed: false, removedPaths: [] };
+  }
+
+  const allRemovedPaths = [];
+  let changed = false;
+
+  for (const lifecycle of Object.keys(settings.hooks)) {
+    const { hooks, removedPaths } = pruneStaleFileHooks(settings.hooks[lifecycle], baseDir);
+    if (removedPaths.length > 0) {
+      settings.hooks[lifecycle] = hooks;
+      allRemovedPaths.push(...removedPaths);
+      changed = true;
+    }
+  }
+
+  if (changed && !dryRun) {
+    fs.writeFileSync(filePath, JSON.stringify(settings, null, 2) + '\n');
+  }
+
+  return { changed, removedPaths: allRemovedPaths };
+}
+
 function wireClaudeHooks(options) {
   const settingsPath = options.settingsPath || claudeSettingsPath();
   const sharedSettingsPath = options.sharedSettingsPath || claudeSharedSettingsPath();
+  const projectSettingsPath =
+    options.projectSettingsPath || claudeProjectSettingsPath(options.projectDir);
   const dryRun = options.dryRun || false;
+  const projectDir = options.projectDir || process.cwd();
   const desiredStatusLine = statuslineCommand();
 
+  // --- Step 0: clean up stale hooks from BOTH settings locations ---
+  const staleWarnings = [];
+
+  // User-level: ~/.claude/settings.local.json
+  const userStale = pruneStaleHooksInFile(settingsPath, projectDir, dryRun);
+  for (const p of userStale.removedPaths) {
+    const msg = `Removed stale hook referencing missing file: ${p}`;
+    console.warn(msg);
+    staleWarnings.push({ file: settingsPath, path: p });
+  }
+
+  // Project-level: $CWD/.claude/settings.json (takes precedence for some events)
+  if (fs.existsSync(projectSettingsPath)) {
+    const projStale = pruneStaleHooksInFile(projectSettingsPath, projectDir, dryRun);
+    for (const p of projStale.removedPaths) {
+      const msg = `Removed stale hook referencing missing file: ${p}`;
+      console.warn(msg);
+      staleWarnings.push({ file: projectSettingsPath, path: p });
+    }
+  }
+
   let settings = loadJsonFile(settingsPath) || {};
   settings.hooks = settings.hooks || {};
 
@@ -426,10 +550,13 @@ module.exports = {
   parseFlags,
   claudeSettingsPath,
   claudeSharedSettingsPath,
+  claudeProjectSettingsPath,
   codexConfigPath,
   geminiSettingsPath,
   syncClaudeStatusLine,
   forgeConfigPath,
+  pruneStaleFileHooks,
+  pruneStaleHooksInFile,
   CLAUDE_HOOKS,
   preToolHookCommand,
   userPromptHookCommand,

package/scripts/cli-demo.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * cli-demo.js — simulated walkthrough of the ThumbGate value prop.
+ *
+ * Shows in ~10 seconds:
+ *   1. A mock bad action (force-push)
+ *   2. Giving it a thumbs-down
+ *   3. Lesson created
+ *   4. Next session: gate fires, action blocked
+ *
+ * No actual data is written — this is a pure simulation for onboarding.
+ */
+
+const BD = '\x1b[1m';
+const RST = '\x1b[0m';
+const G = '\x1b[32m';
+const R = '\x1b[31m';
+const C = '\x1b[36m';
+const Y = '\x1b[33m';
+const D = '\x1b[90m';
+
+function sleep(ms) {
+  const end = Date.now() + ms;
+  while (Date.now() < end) { /* spin — no async needed for short delays */ }
+}
+
+function runDemo(options = {}) {
+  const json = options.json || false;
+
+  if (json) {
+    const steps = [
+      { step: 1, event: 'bad_action', description: 'Agent runs: git push --force origin main', result: 'executed', badge: 'ALLOWED' },
+      { step: 2, event: 'thumbs_down', description: 'User gives thumbs-down feedback', signal: 'down', context: 'force-pushed to main, overwrote teammate\'s work' },
+      { step: 3, event: 'lesson_created', description: 'ThumbGate creates a lesson from the feedback', lesson: { id: 'demo-lesson-001', signal: 'negative', context: 'force-pushed to main', whatWentWrong: 'Overwrote teammate\'s commits on main branch', whatToChange: 'Never force-push to protected branches' } },
+      { step: 4, event: 'gate_promoted', description: 'Pattern detected: 2+ failures on force-push → auto-promoted to blocking gate', gate: { id: 'auto-block-force-push', pattern: 'git push --force.*main', action: 'block', occurrences: 2 } },
+      { step: 5, event: 'gate_fires', description: 'Next session: agent tries git push --force origin main', result: 'BLOCKED', reason: 'Auto-promoted gate: force-push to main detected' },
+    ];
+    return { demo: true, steps };
+  }
+
+  const lines = [];
+  const w = (s) => lines.push(s);
+
+  w('');
+  w(`${BD}${C}thumbgate demo${RST} — see ThumbGate in action (simulated)`);
+  w('═'.repeat(60));
+  w('');
+
+  // Step 1: Bad action
+  w(`${BD}Session 1: Agent runs a risky command${RST}`);
+  w(`${D}─────────────────────────────────────${RST}`);
+  w(`  ${D}Agent>${RST} ${BD}git push --force origin main${RST}`);
+  w(`  ${G}[ALLOWED]${RST} — No gates configured yet, action proceeds.`);
+  w(`  ${R}💥 Result: teammate's commits overwritten on main${RST}`);
+  w('');
+
+  // Step 2: Thumbs down
+  w(`${BD}You give feedback:${RST}`);
+  w(`  ${R}👎 thumbs-down${RST} — "force-pushed to main, overwrote teammate's work"`);
+  w('');
+
+  // Step 3: Lesson
+  w(`${BD}ThumbGate captures a lesson:${RST}`);
+  w(`${D}─────────────────────────────────────${RST}`);
+  w(`  ${Y}[LEARNING]${RST} Lesson created`);
+  w(`  Signal      : ${R}negative${RST}`);
+  w(`  Context     : force-pushed to main`);
+  w(`  Root cause  : Overwrote teammate's commits on main branch`);
+  w(`  Corrective  : Never force-push to protected branches`);
+  w(`  Tags        : git, deployment, data-loss`);
+  w('');
+
+  // Step 4: Gate promotion
+  w(`${BD}Pattern detected (2+ similar failures):${RST}`);
+  w(`  ${Y}→${RST} Auto-promoted to ${R}blocking gate${RST}`);
+  w(`  Gate ID     : auto-block-force-push`);
+  w(`  Pattern     : git push --force.*main`);
+  w(`  Action      : ${R}block${RST}`);
+  w('');
+
+  // Step 5: Next session — blocked
+  w(`${BD}Session 2: Agent tries the same command${RST}`);
+  w(`${D}─────────────────────────────────────${RST}`);
+  w(`  ${D}Agent>${RST} ${BD}git push --force origin main${RST}`);
+  w(`  ${R}[BLOCKED]${RST} Gate fired: force-push to main detected`);
+  w(`  ${G}✅ Mistake prevented. Teammate's work is safe.${RST}`);
+  w('');
+
+  w('═'.repeat(60));
+  w(`${BD}That's ThumbGate:${RST} one thumbs-down → permanent protection.`);
+  w('');
+  w(`  Get started: ${C}npx thumbgate init${RST}`);
+  w(`  Capture:     ${C}npx thumbgate capture --feedback=down --context="what failed"${RST}`);
+  w(`  Check gates: ${C}npx thumbgate gate-stats --json${RST}`);
+  w('');
+
+  return lines.join('\n');
+}
+
+module.exports = { runDemo };

package/scripts/cli-schema.js

@@ -0,0 +1,285 @@
+'use strict';
+
+/**
+ * cli-schema.js — single source of truth for thumbgate CLI commands.
+ *
+ * Inspired by Cloudflare's schema-first CLI architecture: one definition
+ * drives both the CLI help text and the explore TUI command browser.
+ * MCP tool bindings are listed via `mcpTool` so the two surfaces stay in sync.
+ *
+ * Groups: capture | discovery | gates | export | ops | advanced
+ */
+
+const CLI_COMMANDS = [
+  // -------------------------------------------------------------------------
+  // Capture
+  // -------------------------------------------------------------------------
+  {
+    name: 'capture',
+    aliases: ['feedback'],
+    description: 'Capture an up/down signal — turns feedback into a stored lesson',
+    group: 'capture',
+    mcpTool: 'capture_feedback',
+    flags: [
+      { name: 'feedback',        type: 'string',  required: true,  description: 'Signal: up or down' },
+      { name: 'context',         type: 'string',  description: 'One-line reason' },
+      { name: 'what-went-wrong', type: 'string',  description: 'Root cause (negative feedback)' },
+      { name: 'what-to-change',  type: 'string',  description: 'Specific fix required' },
+      { name: 'what-worked',     type: 'string',  description: 'What succeeded (positive feedback)' },
+      { name: 'tags',            type: 'string',  description: 'Comma-separated tags' },
+      { name: 'json',            type: 'boolean', description: 'Output as JSON' },
+    ],
+  },
+
+  // -------------------------------------------------------------------------
+  // Discovery
+  // -------------------------------------------------------------------------
+  {
+    name: 'explore',
+    description: 'Interactive TUI — browse lessons, gates, stats, and rules keyboard-first',
+    group: 'discovery',
+    flags: [
+      { name: 'json', type: 'boolean', description: 'Output as JSON (non-interactive)' },
+      { name: 'limit', type: 'number', description: 'Max items (default 20)' },
+    ],
+  },
+  {
+    name: 'lessons',
+    aliases: ['search-lessons'],
+    description: 'Search promoted lessons and show linked corrective actions',
+    group: 'discovery',
+    mcpTool: 'search_lessons',
+    flags: [
+      { name: 'query',    type: 'string',  description: 'Search query (positional arg also works)' },
+      { name: 'limit',    type: 'number',  description: 'Max results (default 10)' },
+      { name: 'tags',     type: 'string',  description: 'Comma-separated tag filter' },
+      { name: 'category', type: 'string',  description: 'error | learning | preference' },
+      { name: 'json',     type: 'boolean', description: 'Output as JSON' },
+      { name: 'local',    type: 'boolean', description: 'Use local storage (default)' },
+      { name: 'remote',   type: 'boolean', description: 'Fetch from hosted Railway instance' },
+    ],
+  },
+  {
+    name: 'stats',
+    description: 'Feedback analytics — approval rate, Revenue-at-Risk, recent trend',
+    group: 'discovery',
+    mcpTool: 'feedback_stats',
+    flags: [
+      { name: 'json',   type: 'boolean', description: 'Output as JSON' },
+      { name: 'remote', type: 'boolean', description: 'Fetch from hosted Railway instance' },
+    ],
+  },
+  {
+    name: 'gate-stats',
+    description: 'Gate engine statistics — active gates, blocks, warns, time saved',
+    group: 'discovery',
+    flags: [
+      { name: 'json', type: 'boolean', description: 'Output as JSON' },
+    ],
+  },
+  {
+    name: 'summary',
+    description: 'Human-readable feedback summary',
+    group: 'discovery',
+    mcpTool: 'feedback_summary',
+    flags: [
+      { name: 'recent', type: 'number', description: 'Number of recent entries (default 20)' },
+      { name: 'json',   type: 'boolean', description: 'Output as JSON' },
+    ],
+  },
+  {
+    name: 'doctor',
+    description: 'Audit runtime isolation, bootstrap context, and permission tier',
+    group: 'discovery',
+    flags: [
+      { name: 'json', type: 'boolean', description: 'Output as JSON' },
+    ],
+  },
+  {
+    name: 'lesson-health',
+    aliases: ['stale'],
+    description: 'Report on stale lessons (>60d inactive) with optional auto-archive',
+    group: 'discovery',
+    flags: [
+      { name: 'archive', type: 'boolean', description: 'Auto-archive lessons >90d inactive' },
+      { name: 'json',    type: 'boolean', description: 'Output as JSON' },
+    ],
+  },
+
+  // -------------------------------------------------------------------------
+  // Gates
+  // -------------------------------------------------------------------------
+  {
+    name: 'gate-check',
+    description: 'PreToolUse hook: pipe tool JSON via stdin, get ALLOW/BLOCK verdict',
+    group: 'gates',
+    flags: [],
+  },
+  {
+    name: 'force-gate',
+    description: 'Immediately create a blocking gate from a pattern string',
+    group: 'gates',
+    flags: [
+      { name: 'pattern', type: 'string', description: 'Pattern to block (positional)' },
+    ],
+  },
+  {
+    name: 'rules',
+    description: 'Generate prevention rules from repeated failure patterns',
+    group: 'gates',
+    mcpTool: 'prevention_rules',
+    flags: [
+      { name: 'json', type: 'boolean', description: 'Output as JSON' },
+    ],
+  },
+
+  // -------------------------------------------------------------------------
+  // Export
+  // -------------------------------------------------------------------------
+  {
+    name: 'export-dpo',
+    aliases: ['dpo'],
+    description: 'Export DPO training pairs (prompt/chosen/rejected JSONL)',
+    group: 'export',
+    flags: [
+      { name: 'output', type: 'string', description: 'Output file path' },
+    ],
+  },
+  {
+    name: 'export-databricks',
+    aliases: ['databricks'],
+    description: 'Export feedback + proof artifacts as a Databricks-ready analytics bundle',
+    group: 'export',
+    flags: [],
+  },
+  {
+    name: 'obsidian-export',
+    description: 'Export all feedback as interlinked Obsidian markdown notes',
+    group: 'export',
+    flags: [
+      { name: 'vault-path',  type: 'string', description: 'Obsidian vault path' },
+      { name: 'output-dir',  type: 'string', description: 'Output subdirectory (default: AI-Memories/thumbgate)' },
+    ],
+  },
+
+  // -------------------------------------------------------------------------
+  // Ops
+  // -------------------------------------------------------------------------
+  {
+    name: 'status',
+    description: 'Agent-friendly health check — gates, lessons, feedback, enforcement',
+    group: 'discovery',
+    flags: [
+      { name: 'json', type: 'boolean', description: 'Output as JSON' },
+    ],
+  },
+  {
+    name: 'demo',
+    description: 'Simulated walkthrough — see ThumbGate block a bad action in 10 seconds',
+    group: 'ops',
+    flags: [
+      { name: 'json', type: 'boolean', description: 'Output as JSON' },
+    ],
+  },
+  {
+    name: 'init',
+    description: 'Scaffold .thumbgate/ config and wire agent hooks',
+    group: 'ops',
+    flags: [
+      { name: 'agent',      type: 'string',  description: 'Target agent: claude-code | cursor | codex | gemini | amp' },
+      { name: 'wire-hooks', type: 'boolean', description: 'Wire hooks only (skip scaffold)' },
+      { name: 'json',       type: 'boolean', description: 'Output as JSON' },
+    ],
+  },
+  {
+    name: 'serve',
+    description: 'Start MCP server on stdio — connect any MCP-compatible agent',
+    group: 'ops',
+    flags: [],
+  },
+  {
+    name: 'dashboard',
+    description: 'Full ThumbGate dashboard — approval rate, gate stats, prevention impact',
+    group: 'ops',
+    flags: [],
+  },
+  {
+    name: 'self-heal',
+    description: 'Run self-healing check and auto-fix known issues',
+    group: 'ops',
+    flags: [
+      { name: 'check', type: 'boolean', description: 'Check only, no fixes' },
+    ],
+  },
+  {
+    name: 'import-doc',
+    aliases: ['import-document'],
+    description: 'Import a local policy/runbook and propose reviewable gate candidates',
+    group: 'ops',
+    flags: [
+      { name: 'file', type: 'string', description: 'Path to document' },
+    ],
+  },
+  {
+    name: 'meta-agent',
+    description: 'Run meta-agent loop: generate, evaluate, and promote prevention rules',
+    group: 'advanced',
+    flags: [
+      { name: 'dry-run', type: 'boolean', description: 'Preview rules without writing' },
+      { name: 'status',  type: 'boolean', description: 'Show last run summary' },
+    ],
+  },
+  {
+    name: 'pro',
+    description: `Solo dashboard + exports side lane (${'19'}/mo · ${'149'}/yr)`,
+    group: 'ops',
+    flags: [
+      { name: 'upgrade', type: 'boolean', description: 'Install Pro configs into .thumbgate/' },
+      { name: 'info',    type: 'boolean', description: 'Show Pro feature list' },
+    ],
+  },
+];
+
+/**
+ * Return the command definition for a given name or alias.
+ */
+function findCommand(name) {
+  return CLI_COMMANDS.find(
+    (cmd) => cmd.name === name || (cmd.aliases || []).includes(name),
+  );
+}
+
+/**
+ * Return commands grouped by their group field.
+ */
+function groupedCommands() {
+  const groups = {};
+  for (const cmd of CLI_COMMANDS) {
+    const g = cmd.group || 'other';
+    if (!groups[g]) groups[g] = [];
+    groups[g].push(cmd);
+  }
+  return groups;
+}
+
+/**
+ * Generate a compact help string for a single command.
+ * Format:  name [aliases]   description   [--flag ...]
+ */
+function commandHelpLine(cmd, opts = {}) {
+  const { showFlags = false } = opts;
+  const nameCol = 22;
+  const nameStr = [cmd.name, ...(cmd.aliases || []).slice(0, 1)].join(' | ');
+  const pad = ' '.repeat(Math.max(1, nameCol - nameStr.length));
+  let line = `  ${nameStr}${pad}${cmd.description}`;
+  if (cmd.mcpTool) line += ` [mcp:${cmd.mcpTool}]`;
+  if (showFlags && cmd.flags.length > 0) {
+    const flagStr = cmd.flags
+      .map((f) => `--${f.name}${f.required ? ' (required)' : ''}`)
+      .join('  ');
+    line += `\n    ${flagStr}`;
+  }
+  return line;
+}
+
+module.exports = { CLI_COMMANDS, findCommand, groupedCommands, commandHelpLine };