@cg3/equip 0.2.15 → 0.2.17

package/README.md

@@ -44,9 +44,9 @@ Some platforms support **lifecycle hooks** — scripts that run automatically at
 | Claude Code | ✅ | `PostToolUseFailure`, `Stop`, `PreToolUse`, `PostToolUse` |
 | All others | ❌ | — |
 
-When hooks are supported, equip installs lightweight Node.js scripts to `~/.prior/hooks/` and registers them in the platform's settings. Hooks are a **silent enhancement** — if the platform doesn't support them, equip installs only MCP + rules without any error or warning.
+When hooks are supported, equip writes the consumer-provided scripts to a configurable directory (default: `~/.${name}/hooks/`) and registers them in the platform's settings. Hooks are a **silent enhancement** — if the platform doesn't support them, equip installs only MCP + rules without any error or warning.
 
-Hooks are opt-in per platform via the capabilities model. As more platforms add hook support, equip can enable them without consumer code changes.
+Hook scripts and event bindings are defined by the consumer (your package), not by equip. Equip provides only the installation infrastructure — capabilities detection, file writing, settings registration, and cleanup. As more platforms add hook support, equip can enable them without consumer code changes.
 
 ## Quick Start
 

package/index.js

@@ -3,10 +3,13 @@
 
 "use strict";
 
+const path = require("path");
+const os = require("os");
+
 const { detectPlatforms, whichSync, dirExists, fileExists } = require("./lib/detect");
 const { readMcpEntry, buildHttpConfig, buildHttpConfigWithAuth, buildStdioConfig, installMcp, installMcpJson, installMcpToml, uninstallMcp, updateMcpKey, parseTomlServerEntry, parseTomlSubTables, buildTomlEntry, removeTomlEntry } = require("./lib/mcp");
 const { parseRulesVersion, installRules, uninstallRules, markerPatterns } = require("./lib/rules");
-const { getHookCapabilities, installHooks, uninstallHooks, hasHooks, buildHooksConfig, getHookScripts } = require("./lib/hooks");
+const { getHookCapabilities, installHooks, uninstallHooks, hasHooks, buildHooksConfig } = require("./lib/hooks");
 const { createManualPlatform, platformName, KNOWN_PLATFORMS } = require("./lib/platforms");
 const cli = require("./lib/cli");
 
@@ -37,6 +40,12 @@ class Equip {
    * @param {string} config.stdio.command - Command to run
    * @param {string[]} config.stdio.args - Command arguments
    * @param {string} config.stdio.envKey - Env var name for API key
+   * @param {Array} [config.hooks] - Lifecycle hook definitions
+   * @param {string} config.hooks[].event - Hook event name (e.g., "PostToolUseFailure")
+   * @param {string} [config.hooks[].matcher] - Regex matcher for event filtering (e.g., "Bash")
+   * @param {string} config.hooks[].script - Hook script content (Node.js)
+   * @param {string} config.hooks[].name - Script filename (without .js extension)
+   * @param {string} [config.hookDir] - Directory for hook scripts (default: ~/.${name}/hooks)
    */
   constructor(config) {
     if (!config.name) throw new Error("Equip: name is required");
@@ -46,6 +55,8 @@ class Equip {
     this.serverUrl = config.serverUrl;
     this.rules = config.rules || null;
     this.stdio = config.stdio || null;
+    this.hookDefs = config.hooks || null;
+    this.hookDir = config.hookDir || path.join(os.homedir(), `.${config.name}`, "hooks");
   }
 
   /**
@@ -151,13 +162,16 @@ class Equip {
 
   /**
    * Install lifecycle hooks on a platform (if supported).
-   * Hooks provide structural enforcement (e.g., search reminders on errors).
+   * Uses hook definitions from constructor config.
    * @param {object} platform - Platform object from detect()
    * @param {object} [options] - { hookDir, dryRun }
    * @returns {{ installed: boolean, scripts: string[], hookDir: string } | null}
    */
   installHooks(platform, options = {}) {
-    return installHooks(platform, options);
+    if (!this.hookDefs) return null;
+    const opts = { ...options };
+    if (this.hookDir && !opts.hookDir) opts.hookDir = this.hookDir;
+    return installHooks(platform, this.hookDefs, opts);
   }
 
   /**
@@ -167,7 +181,10 @@ class Equip {
    * @returns {boolean}
    */
   uninstallHooks(platform, options = {}) {
-    return uninstallHooks(platform, options);
+    if (!this.hookDefs) return false;
+    const opts = { ...options };
+    if (this.hookDir && !opts.hookDir) opts.hookDir = this.hookDir;
+    return uninstallHooks(platform, this.hookDefs, opts);
   }
 
   /**
@@ -177,16 +194,19 @@ class Equip {
    * @returns {boolean}
    */
   hasHooks(platform, options = {}) {
-    return hasHooks(platform, options);
+    if (!this.hookDefs) return false;
+    const opts = { ...options };
+    if (this.hookDir && !opts.hookDir) opts.hookDir = this.hookDir;
+    return hasHooks(platform, this.hookDefs, opts);
   }
 
   /**
-   * Check if a platform supports hooks.
+   * Check if a platform supports hooks and this instance has hook definitions.
    * @param {object} platform - Platform object
    * @returns {boolean}
    */
   supportsHooks(platform) {
-    return !!getHookCapabilities(platform.platform);
+    return !!this.hookDefs && this.hookDefs.length > 0 && !!getHookCapabilities(platform.platform);
   }
 }
 
@@ -220,6 +240,5 @@ module.exports = {
   uninstallHooks,
   hasHooks,
   buildHooksConfig,
-  getHookScripts,
   cli,
 };

package/lib/hooks.js

@@ -1,4 +1,5 @@
 // Hook installation for platforms that support lifecycle hooks.
+// Equip provides the infrastructure; consumers provide hook definitions.
 // Zero dependencies.
 
 "use strict";
@@ -17,7 +18,9 @@ function getHookCapabilities(platformId) {
   const caps = {
     "claude-code": {
       settingsPath: () => path.join(os.homedir(), ".claude", "settings.json"),
-      events: ["PreToolUse", "PostToolUse", "PostToolUseFailure", "Stop"],
+      events: ["PreToolUse", "PostToolUse", "PostToolUseFailure", "Stop",
+               "SessionStart", "SessionEnd", "UserPromptSubmit", "Notification",
+               "SubagentStart", "SubagentStop", "PreCompact", "TaskCompleted"],
       format: "claude-code",
     },
     // Future: cursor, etc.
@@ -25,118 +28,38 @@ function getHookCapabilities(platformId) {
   return caps[platformId] || null;
 }
 
-// ─── Hook Script Content ─────────────────────────────────────
-
-/**
- * Returns hook script content keyed by filename.
- * Scripts are platform-agnostic Node.js — they read JSON from stdin and write JSON to stdout.
- */
-function getHookScripts() {
-  return {
-    "prior-search-nudge.js": `#!/usr/bin/env node
-// Prior hook: Nudge agent to search Prior after a tool failure.
-// Fires on PostToolUseFailure for Bash commands.
-// Injects additionalContext reminding the agent to search.
-
-const chunks = [];
-process.stdin.on("data", c => chunks.push(c));
-process.stdin.on("end", () => {
-  try {
-    const input = JSON.parse(Buffer.concat(chunks).toString());
-    const toolName = input.tool_name || "";
-    const error = input.error || "";
-
-    // Only nudge on Bash failures (compile errors, runtime errors, etc.)
-    if (toolName !== "Bash") { process.exit(0); return; }
-
-    // Skip trivial failures (empty output, permission prompts)
-    if (!error || error.length < 20) { process.exit(0); return; }
-
-    // Inject search reminder as additional context
-    const output = {
-      hookSpecificOutput: {
-        hookEventName: "PostToolUseFailure",
-        additionalContext: "\\u26a0\\ufe0f Error detected. Per Prior protocol: search this error before attempting a fix. Use prior_search with the exact error text. Your user has credits for this — not searching wastes their investment."
-      }
-    };
-    process.stdout.write(JSON.stringify(output));
-  } catch {
-    // Never block on hook errors
-    process.exit(0);
-  }
-});
-`,
-
-    "prior-completion-check.js": `#!/usr/bin/env node
-// Prior hook: Remind agent about contribution offer at task completion.
-// Fires on Stop event.
-// Injects additionalContext if the agent didn't mention Prior contributions.
-
-const chunks = [];
-process.stdin.on("data", c => chunks.push(c));
-process.stdin.on("end", () => {
-  try {
-    const input = JSON.parse(Buffer.concat(chunks).toString());
-    const lastResponse = input.last_assistant_message || "";
-
-    // Check if the agent already mentioned contributions
-    const hasContribution = /contribute.*prior|prior.*contribut|No contribution needed/i.test(lastResponse);
-    if (hasContribution) { process.exit(0); return; }
-
-    // Check if this looks like a task completion (not just a question/answer)
-    const looksLikeTask = /fix|implement|build|debug|error|compil|test|deploy|configur|migrat|setup|install/i.test(lastResponse);
-    if (!looksLikeTask) { process.exit(0); return; }
-
-    const output = {
-      hookSpecificOutput: {
-        hookEventName: "Stop",
-        additionalContext: "Reminder: Your completion summary should end with either (a) an offer to contribute fixes to Prior, or (b) \\"No contribution needed: all fixes were first-attempt.\\""
-      }
-    };
-    process.stdout.write(JSON.stringify(output));
-  } catch {
-    process.exit(0);
-  }
-});
-`,
-  };
-}
-
 // ─── Hook Config Generation ─────────────────────────────────
 
 /**
- * Build hooks config object for a platform.
+ * Build platform-specific hooks config from consumer-defined hook definitions.
+ * @param {Array} hookDefs - Array of { event, matcher?, script, name }
  * @param {string} hookDir - Absolute path to directory containing hook scripts
  * @param {string} platformId - Platform id
- * @returns {object} Hooks config in the platform's format
+ * @returns {object|null} Hooks config in the platform's format
  */
-function buildHooksConfig(hookDir, platformId) {
+function buildHooksConfig(hookDefs, hookDir, platformId) {
   const caps = getHookCapabilities(platformId);
-  if (!caps) return null;
+  if (!caps || !hookDefs || hookDefs.length === 0) return null;
 
   if (caps.format === "claude-code") {
     const config = {};
 
-    if (caps.events.includes("PostToolUseFailure")) {
-      config.PostToolUseFailure = [{
-        matcher: "Bash",
-        hooks: [{
-          type: "command",
-          command: `node "${path.join(hookDir, "prior-search-nudge.js")}"`,
-        }],
-      }];
-    }
+    for (const def of hookDefs) {
+      if (!caps.events.includes(def.event)) continue;
 
-    if (caps.events.includes("Stop")) {
-      config.Stop = [{
+      const entry = {
         hooks: [{
           type: "command",
-          command: `node "${path.join(hookDir, "prior-completion-check.js")}"`,
+          command: `node "${path.join(hookDir, def.name + ".js")}"`,
         }],
-      }];
+      };
+      if (def.matcher) entry.matcher = def.matcher;
+
+      if (!config[def.event]) config[def.event] = [];
+      config[def.event].push(entry);
     }
 
-    return config;
+    return Object.keys(config).length > 0 ? config : null;
   }
 
   return null;
@@ -147,34 +70,38 @@ function buildHooksConfig(hookDir, platformId) {
 /**
  * Install hook scripts to disk and register them in platform settings.
  * @param {object} platform - Platform object from detect()
- * @param {object} [options] - { hookDir, dryRun }
+ * @param {Array} hookDefs - Array of { event, matcher?, script, name }
+ * @param {object} [options] - { hookDir, dryRun, marker }
  * @returns {{ installed: boolean, scripts: string[], hookDir: string } | null}
  */
-function installHooks(platform, options = {}) {
+function installHooks(platform, hookDefs, options = {}) {
   const caps = getHookCapabilities(platform.platform);
-  if (!caps) return null;
+  if (!caps || !hookDefs || hookDefs.length === 0) return null;
 
-  const hookDir = options.hookDir || path.join(os.homedir(), ".prior", "hooks");
+  if (!options.hookDir) throw new Error("hookDir is required");
+  const hookDir = options.hookDir;
   const dryRun = options.dryRun || false;
 
   // 1. Write hook scripts
-  const scripts = getHookScripts();
   const installedScripts = [];
 
   if (!dryRun) {
     fs.mkdirSync(hookDir, { recursive: true });
   }
 
-  for (const [filename, content] of Object.entries(scripts)) {
-    const filePath = path.join(hookDir, filename);
+  for (const def of hookDefs) {
+    if (!caps.events.includes(def.event)) continue;
+    const filePath = path.join(hookDir, def.name + ".js");
     if (!dryRun) {
-      fs.writeFileSync(filePath, content, { mode: 0o755 });
+      fs.writeFileSync(filePath, def.script, { mode: 0o755 });
     }
-    installedScripts.push(filename);
+    installedScripts.push(def.name + ".js");
   }
 
+  if (installedScripts.length === 0) return null;
+
   // 2. Register hooks in platform settings
-  const hooksConfig = buildHooksConfig(hookDir, platform.platform);
+  const hooksConfig = buildHooksConfig(hookDefs, hookDir, platform.platform);
   if (!hooksConfig) return null;
 
   if (!dryRun) {
@@ -184,16 +111,17 @@ function installHooks(platform, options = {}) {
       settings = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
     } catch { /* file doesn't exist yet */ }
 
-    // Merge hooks — preserve existing non-Prior hooks
+    // Merge hooks — preserve existing non-marker hooks
     if (!settings.hooks) settings.hooks = {};
 
     for (const [event, hookGroups] of Object.entries(hooksConfig)) {
       if (!settings.hooks[event]) {
         settings.hooks[event] = hookGroups;
       } else {
-        // Remove existing Prior hooks for this event, then add new ones
+        // Remove existing hooks from this marker, then add new ones
+        const hookDirNorm = hookDir.replace(/\\/g, "/");
         settings.hooks[event] = settings.hooks[event].filter(
-          group => !group.hooks?.some(h => h.command && h.command.includes(".prior"))
+          group => !group.hooks?.some(h => h.command && h.command.replace(/\\/g, "/").includes(hookDirNorm))
         );
         settings.hooks[event].push(...hookGroups);
       }
@@ -209,21 +137,22 @@ function installHooks(platform, options = {}) {
 /**
  * Uninstall hook scripts and remove from platform settings.
  * @param {object} platform - Platform object
+ * @param {Array} hookDefs - Array of { event, matcher?, script, name } (need names to know what to remove)
  * @param {object} [options] - { hookDir, dryRun }
  * @returns {boolean} Whether anything was removed
  */
-function uninstallHooks(platform, options = {}) {
+function uninstallHooks(platform, hookDefs, options = {}) {
   const caps = getHookCapabilities(platform.platform);
-  if (!caps) return false;
+  if (!caps || !hookDefs || hookDefs.length === 0) return false;
 
-  const hookDir = options.hookDir || path.join(os.homedir(), ".prior", "hooks");
+  if (!options.hookDir) throw new Error("hookDir is required");
+  const hookDir = options.hookDir;
   const dryRun = options.dryRun || false;
   let removed = false;
 
   // 1. Remove hook scripts
-  const scripts = getHookScripts();
-  for (const filename of Object.keys(scripts)) {
-    const filePath = path.join(hookDir, filename);
+  for (const def of hookDefs) {
+    const filePath = path.join(hookDir, def.name + ".js");
     try {
       if (fs.statSync(filePath).isFile()) {
         if (!dryRun) fs.unlinkSync(filePath);
@@ -244,10 +173,11 @@ function uninstallHooks(platform, options = {}) {
       const settings = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
       if (settings.hooks) {
         let changed = false;
+        const hookDirNorm = hookDir.replace(/\\/g, "/");
         for (const event of Object.keys(settings.hooks)) {
           const before = settings.hooks[event].length;
           settings.hooks[event] = settings.hooks[event].filter(
-            group => !group.hooks?.some(h => h.command && h.command.includes(".prior"))
+            group => !group.hooks?.some(h => h.command && h.command.replace(/\\/g, "/").includes(hookDirNorm))
           );
           if (settings.hooks[event].length === 0) {
             delete settings.hooks[event];
@@ -269,20 +199,21 @@ function uninstallHooks(platform, options = {}) {
 /**
  * Check if hooks are installed for a platform.
  * @param {object} platform - Platform object
+ * @param {Array} hookDefs - Array of { event, matcher?, script, name }
  * @param {object} [options] - { hookDir }
  * @returns {boolean}
  */
-function hasHooks(platform, options = {}) {
+function hasHooks(platform, hookDefs, options = {}) {
   const caps = getHookCapabilities(platform.platform);
-  if (!caps) return false;
+  if (!caps || !hookDefs || hookDefs.length === 0) return false;
 
-  const hookDir = options.hookDir || path.join(os.homedir(), ".prior", "hooks");
+  if (!options.hookDir) throw new Error("hookDir is required");
+  const hookDir = options.hookDir;
 
   // Check scripts exist
-  const scripts = getHookScripts();
-  for (const filename of Object.keys(scripts)) {
+  for (const def of hookDefs) {
     try {
-      if (!fs.statSync(path.join(hookDir, filename)).isFile()) return false;
+      if (!fs.statSync(path.join(hookDir, def.name + ".js")).isFile()) return false;
     } catch { return false; }
   }
 
@@ -290,16 +221,16 @@ function hasHooks(platform, options = {}) {
   try {
     const settings = JSON.parse(fs.readFileSync(caps.settingsPath(), "utf-8"));
     if (!settings.hooks) return false;
-    const hasPriorHook = Object.values(settings.hooks).some(groups =>
-      groups.some(g => g.hooks?.some(h => h.command && h.command.includes(".prior")))
+    const hookDirNorm = hookDir.replace(/\\/g, "/");
+    const hasRegistered = Object.values(settings.hooks).some(groups =>
+      groups.some(g => g.hooks?.some(h => h.command && h.command.replace(/\\/g, "/").includes(hookDirNorm)))
     );
-    return hasPriorHook;
+    return hasRegistered;
   } catch { return false; }
 }
 
 module.exports = {
   getHookCapabilities,
-  getHookScripts,
   buildHooksConfig,
   installHooks,
   uninstallHooks,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cg3/equip",
-  "version": "0.2.15",
+  "version": "0.2.17",
   "description": "Universal MCP + behavioral rules installer for AI coding agents",
   "main": "index.js",
   "bin": {