@jaimevalasek/aioson 1.28.1 → 1.30.0

package/src/commands/hooks-install.js

@@ -17,8 +17,10 @@
 const path = require('node:path');
 const fs = require('node:fs/promises');
 const os = require('node:os');
+const { getAgentDefinition, normalizeAgentName } = require('../agents');
 
 const HOME = os.homedir();
+const HOOK_AGENT_NAME_RE = /^[a-z][a-z0-9-]*$/;
 
 // ─── Config file paths ────────────────────────────────────────────────────────
 
@@ -30,22 +32,63 @@ const CONFIG_PATHS = {
 
 // ─── Hook command templates ───────────────────────────────────────────────────
 
+function normalizeHookAgentName(input = 'dev') {
+  const raw = normalizeAgentName(input || 'dev').replace(/^\//, '');
+  const definition = getAgentDefinition(raw);
+  const agentName = definition ? definition.id : raw;
+
+  if (!HOOK_AGENT_NAME_RE.test(agentName)) {
+    throw new Error(
+      `invalid agent name "${String(input)}"; use a known agent id or kebab-case identifier`
+    );
+  }
+
+  return agentName;
+}
+
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
 function makeEmitCommand(agentName, source) {
   // $PWD is the project directory at hook execution time
-  return `aioson hooks:emit "$PWD" --agent=${agentName} --source=${source} 2>/dev/null || true`;
+  return `aioson hooks:emit "$PWD" --agent=${shellQuote(agentName)} --source=${shellQuote(source)} 2>/dev/null || true`;
 }
 
 function makeDoneCommand(agentName) {
-  return `aioson agent:done "$PWD" --agent=${agentName} --summary="Session ended via ${agentName} hook" 2>/dev/null || true`;
+  return `aioson agent:done "$PWD" --agent=${shellQuote(agentName)} --summary=${shellQuote(`Session ended via ${agentName} hook`)} 2>/dev/null || true`;
+}
+
+function makeGuardCommand(agentName) {
+  // PreToolUse: the harness pipes the pending edit event (JSON on stdin); the
+  // guard derives a query from the artifact itself, runs context:brief, and
+  // injects salient project-rule constraints before the write lands. Advisory —
+  // always exits 0, never blocks the tool.
+  return `aioson context:guard "$PWD" --tool=claude --agent=${shellQuote(agentName)} --json 2>/dev/null || true`;
 }
 
 // ─── Claude Code ─────────────────────────────────────────────────────────────
 
-function buildClaudeHooks(agentName) {
-  const emitCmd = makeEmitCommand(agentName, 'claude');
-  const doneCmd = makeDoneCommand(agentName);
+// True for any hook entry AIOSON owns, so reinstall/uninstall can scrub them
+// without disturbing user-authored hooks.
+const AIOSON_HOOK_SIGNATURES = [
+  'aioson hooks:emit',
+  'aioson agent:done',
+  'aioson context:guard',
+  'aioson live:start'
+];
+
+function isAiosonHookEntry(entry) {
+  const cmd = entry?.hooks?.[0]?.command || entry?.command || '';
+  return AIOSON_HOOK_SIGNATURES.some((sig) => cmd.includes(sig));
+}
 
-  return {
+function buildClaudeHooks(agentName, includeGuard = true) {
+  const safeAgentName = normalizeHookAgentName(agentName);
+  const emitCmd = makeEmitCommand(safeAgentName, 'claude');
+  const doneCmd = makeDoneCommand(safeAgentName);
+
+  const hooks = {
     PostToolUse: [
       {
         matcher: 'Write|Edit|MultiEdit',
@@ -66,9 +109,20 @@ function buildClaudeHooks(agentName) {
       }
     ]
   };
+
+  if (includeGuard) {
+    hooks.PreToolUse = [
+      {
+        matcher: 'Write|Edit|MultiEdit|NotebookEdit',
+        hooks: [{ type: 'command', command: makeGuardCommand(safeAgentName) }]
+      }
+    ];
+  }
+
+  return hooks;
 }
 
-async function installClaudeHooks(agentName, dryRun, logger) {
+async function installClaudeHooks(agentName, dryRun, logger, includeGuard = true) {
   const configPath = CONFIG_PATHS.claude;
   await fs.mkdir(path.dirname(configPath), { recursive: true });
 
@@ -77,21 +131,26 @@ async function installClaudeHooks(agentName, dryRun, logger) {
     existing = JSON.parse(await fs.readFile(configPath, 'utf8'));
   } catch { /* file doesn't exist yet */ }
 
-  const newHooks = buildClaudeHooks(agentName);
+  const newHooks = buildClaudeHooks(agentName, includeGuard);
 
   // Merge: add AIOSON hooks without removing existing ones
   const merged = { ...existing };
   if (!merged.hooks) merged.hooks = {};
 
+  // When the guard is opted out, still scrub any previously-installed guard hook
+  // so a reinstall with --no-guard actually removes it.
+  for (const event of Object.keys(merged.hooks)) {
+    if (newHooks[event]) continue;
+    merged.hooks[event] = (merged.hooks[event] || []).filter((entry) => !isAiosonHookEntry(entry));
+    if (merged.hooks[event].length === 0) delete merged.hooks[event];
+  }
+
   for (const [event, hookList] of Object.entries(newHooks)) {
     if (!merged.hooks[event]) {
       merged.hooks[event] = hookList;
     } else {
       // Remove any existing AIOSON hooks (to avoid duplicates on reinstall)
-      const filtered = merged.hooks[event].filter((entry) => {
-        const cmd = entry.hooks?.[0]?.command || '';
-        return !cmd.includes('aioson hooks:emit') && !cmd.includes('aioson agent:done');
-      });
+      const filtered = merged.hooks[event].filter((entry) => !isAiosonHookEntry(entry));
       merged.hooks[event] = [...filtered, ...hookList];
     }
   }
@@ -102,6 +161,9 @@ async function installClaudeHooks(agentName, dryRun, logger) {
   } else {
     logger.log(`  [dry-run] Would write: ${configPath}`);
     logger.log(`  Hooks to add:`);
+    if (includeGuard) {
+      logger.log(`    PreToolUse (Write|Edit|MultiEdit|NotebookEdit) → context:guard`);
+    }
     logger.log(`    PostToolUse (Write|Edit|MultiEdit|Bash|Task|TodoWrite) → hooks:emit`);
     logger.log(`    Stop → agent:done`);
   }
@@ -112,9 +174,10 @@ async function installClaudeHooks(agentName, dryRun, logger) {
 // ─── Antigravity ─────────────────────────────────────────────────────────────
 
 function buildAntigravityHooks(agentName) {
-  const emitCmd = makeEmitCommand(agentName, 'antigravity');
-  const doneCmd = makeDoneCommand(agentName);
-  const startCmd = `aioson live:start "$PWD" --agent=${agentName} --tool=antigravity --no-launch 2>/dev/null || true`;
+  const safeAgentName = normalizeHookAgentName(agentName);
+  const emitCmd = makeEmitCommand(safeAgentName, 'antigravity');
+  const doneCmd = makeDoneCommand(safeAgentName);
+  const startCmd = `aioson live:start "$PWD" --agent=${shellQuote(safeAgentName)} --tool=antigravity --no-launch 2>/dev/null || true`;
 
   return {
     SessionStart: [{ type: 'command', command: startCmd }],
@@ -178,9 +241,39 @@ function mergeAntigravityHooks(existing, newHooks) {
   return merged;
 }
 
+// Scrub AIOSON entries from one Antigravity hooks file, mirroring the
+// `cmd.includes('aioson')` policy the merge uses on install.
+async function scrubAntigravityHookFile(filePath, dryRun, logger, label) {
+  let existing;
+  try {
+    existing = JSON.parse(await fs.readFile(filePath, 'utf8'));
+  } catch {
+    logger.log(`  ${label} not found — nothing to remove`);
+    return { tool: 'antigravity', path: filePath, removed: false };
+  }
+  if (existing.hooks) {
+    for (const event of Object.keys(existing.hooks)) {
+      existing.hooks[event] = (existing.hooks[event] || []).filter((entry) => {
+        const cmd = entry.command || entry.hooks?.[0]?.command || '';
+        return !cmd.includes('aioson');
+      });
+      if (existing.hooks[event].length === 0) delete existing.hooks[event];
+    }
+    if (Object.keys(existing.hooks).length === 0) delete existing.hooks;
+  }
+  if (!dryRun) {
+    await fs.writeFile(filePath, JSON.stringify(existing, null, 2), 'utf8');
+    logger.log(`  ✓ ${label} hooks removed — ${filePath}`);
+  } else {
+    logger.log(`  [dry-run] Would remove AIOSON hooks from: ${filePath}`);
+  }
+  return { tool: 'antigravity', path: filePath, removed: true };
+}
+
 // ─── Codex (OpenAI) ───────────────────────────────────────────────────────────
 
 async function installCodexHooks(agentName, dryRun, logger) {
+  const safeAgentName = normalizeHookAgentName(agentName);
   // Codex CLI does not have a native hook system as of 2026.
   // The workaround: add a shell alias that wraps `codex` and calls live:start before / agent:done after.
   const configPath = path.join(HOME, '.codex', 'config.yaml');
@@ -188,12 +281,12 @@ async function installCodexHooks(agentName, dryRun, logger) {
 
   const wrapperScript = `#!/bin/bash
 # AIOSON session wrapper for Codex CLI
-# Generated by: aioson hooks:install --tool=codex --agent=${agentName}
+# Generated by: aioson hooks:install --tool=codex --agent=${safeAgentName}
 # Usage: replace \`codex\` calls with \`codex-aioson\` OR add to .bashrc:
 #   alias codex='${wrapperPath}'
 
 PROJECT_DIR="\${1:-$PWD}"
-AGENT="${agentName}"
+AGENT=${shellQuote(safeAgentName)}
 
 # Start live session before Codex runs
 aioson live:start "$PROJECT_DIR" --agent="$AGENT" --tool=codex --no-launch 2>/dev/null || true
@@ -248,8 +341,15 @@ async function detectInstalledTools() {
 
 async function runHooksInstall({ args, options = {}, logger }) {
   const projectDir = path.resolve(process.cwd(), args[0] || '.');
-  const agentName = options.agent ? String(options.agent).replace(/^@/, '') : 'dev';
+  let agentName;
+  try {
+    agentName = normalizeHookAgentName(options.agent || 'dev');
+  } catch (err) {
+    logger.log(`Invalid agent name: ${err.message}`);
+    return { ok: false, reason: 'invalid_agent_name', error: err.message };
+  }
   const dryRun = options['dry-run'] || options.dryRun || false;
+  const includeGuard = !(options['no-guard'] || options.noGuard);
   let tool = options.tool ? String(options.tool).trim().toLowerCase() : 'all';
 
   if (tool === 'all') {
@@ -271,7 +371,7 @@ async function runHooksInstall({ args, options = {}, logger }) {
   for (const t of tools) {
     try {
       if (t === 'claude') {
-        results.push(await installClaudeHooks(agentName, dryRun, logger));
+        results.push(await installClaudeHooks(agentName, dryRun, logger, includeGuard));
       } else if (t === 'antigravity') {
         results.push(await installAntigravityHooks(agentName, projectDir, dryRun, logger));
       } else if (t === 'codex') {
@@ -290,6 +390,9 @@ async function runHooksInstall({ args, options = {}, logger }) {
   if (!dryRun) {
     logger.log('');
     logger.log('Hooks installed. From now on:');
+    if (includeGuard && tools.includes('claude')) {
+      logger.log('  • Before each file write/edit → context:guard injects salient project-rule constraints');
+    }
     logger.log('  • Every file write/edit → logged as artifact event');
     logger.log('  • Every bash command → logged as step_done event');
     logger.log('  • Session end → logged as agent:done');
@@ -306,7 +409,14 @@ async function runHooksInstall({ args, options = {}, logger }) {
 }
 
 async function runHooksUninstall({ args, options = {}, logger }) {
-  const agentName = options.agent ? String(options.agent).replace(/^@/, '') : 'dev';
+  let agentName;
+  try {
+    agentName = normalizeHookAgentName(options.agent || 'dev');
+  } catch (err) {
+    logger.log(`Invalid agent name: ${err.message}`);
+    return { ok: false, reason: 'invalid_agent_name', error: err.message };
+  }
+  const projectDir = path.resolve(process.cwd(), args && args[0] ? args[0] : '.');
   const dryRun = options['dry-run'] || options.dryRun || false;
   const tool = options.tool ? String(options.tool).trim().toLowerCase() : 'claude';
   const tools = tool.split(',').map((t) => t.trim()).filter(Boolean);
@@ -314,6 +424,8 @@ async function runHooksUninstall({ args, options = {}, logger }) {
   logger.log(`Hooks Uninstall — agent: @${agentName}${dryRun ? ' [dry-run]' : ''}`);
   logger.log('─'.repeat(50));
 
+  const results = [];
+
   for (const t of tools) {
     if (t === 'claude') {
       try {
@@ -321,10 +433,7 @@ async function runHooksUninstall({ args, options = {}, logger }) {
         const existing = JSON.parse(await fs.readFile(configPath, 'utf8'));
         if (existing.hooks) {
           for (const event of Object.keys(existing.hooks)) {
-            existing.hooks[event] = (existing.hooks[event] || []).filter((entry) => {
-              const cmd = entry.hooks?.[0]?.command || entry.command || '';
-              return !cmd.includes('aioson hooks:emit') && !cmd.includes('aioson agent:done') && !cmd.includes('aioson live:start');
-            });
+            existing.hooks[event] = (existing.hooks[event] || []).filter((entry) => !isAiosonHookEntry(entry));
             if (existing.hooks[event].length === 0) delete existing.hooks[event];
           }
           if (Object.keys(existing.hooks).length === 0) delete existing.hooks;
@@ -335,13 +444,47 @@ async function runHooksUninstall({ args, options = {}, logger }) {
         } else {
           logger.log(`  [dry-run] Would remove AIOSON hooks from: ${configPath}`);
         }
+        results.push({ tool: 'claude', path: configPath, removed: true });
       } catch {
         logger.log(`  Claude Code settings not found — nothing to remove`);
+        results.push({ tool: 'claude', removed: false });
       }
+    } else if (t === 'antigravity') {
+      // Install writes both a global and a workspace hooks file — scrub both.
+      results.push(await scrubAntigravityHookFile(CONFIG_PATHS.antigravity, dryRun, logger, 'Antigravity global'));
+      results.push(await scrubAntigravityHookFile(
+        path.join(projectDir, CONFIG_PATHS.antigravity_workspace), dryRun, logger, 'Antigravity workspace'
+      ));
+    } else if (t === 'codex') {
+      const wrapperPath = path.join(HOME, '.codex', 'aioson-wrapper.sh');
+      try {
+        if (!dryRun) {
+          await fs.unlink(wrapperPath);
+          logger.log(`  ✓ Codex wrapper removed — ${wrapperPath}`);
+          logger.log(`  ⚠ Also remove the alias from your shell rc if you added it: alias codex='${wrapperPath}'`);
+        } else {
+          logger.log(`  [dry-run] Would remove: ${wrapperPath}`);
+        }
+        results.push({ tool: 'codex', path: wrapperPath, removed: true });
+      } catch {
+        logger.log(`  Codex wrapper not found — nothing to remove`);
+        results.push({ tool: 'codex', removed: false });
+      }
+    } else {
+      logger.log(`  ⚠ Unknown tool: ${t} — supported: claude, antigravity, codex`);
+      results.push({ tool: t, removed: false, reason: 'unsupported' });
     }
   }
 
-  return { ok: true };
+  return { ok: true, results };
 }
 
-module.exports = { runHooksInstall, runHooksUninstall };
+module.exports = {
+  runHooksInstall,
+  runHooksUninstall,
+  buildClaudeHooks,
+  buildAntigravityHooks,
+  scrubAntigravityHookFile,
+  normalizeHookAgentName,
+  isAiosonHookEntry
+};