@hasna/hooks 0.0.4 → 0.0.6

package/bin/index.js

@@ -3519,6 +3519,8 @@ var {
 
 // src/cli/index.tsx
 import chalk2 from "chalk";
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { join as join2 } from "path";
 
 // src/cli/components/App.tsx
 import { useState as useState7 } from "react";
@@ -4519,67 +4521,57 @@ function Spinner({ type = "dots" }) {
 var build_default2 = Spinner;
 
 // src/lib/installer.ts
-import { existsSync, cpSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { join, dirname } from "path";
 import { homedir } from "os";
 import { fileURLToPath } from "url";
 var __dirname2 = dirname(fileURLToPath(import.meta.url));
 var HOOKS_DIR = existsSync(join(__dirname2, "..", "..", "hooks", "hook-gitguard")) ? join(__dirname2, "..", "..", "hooks") : join(__dirname2, "..", "hooks");
-var SETTINGS_PATH = join(homedir(), ".claude", "settings.json");
+function getSettingsPath(scope = "global") {
+  if (scope === "project") {
+    return join(process.cwd(), ".claude", "settings.json");
+  }
+  return join(homedir(), ".claude", "settings.json");
+}
 function getHookPath(name) {
   const hookName = name.startsWith("hook-") ? name : `hook-${name}`;
   return join(HOOKS_DIR, hookName);
 }
-function readSettings() {
+function hookExists(name) {
+  return existsSync(getHookPath(name));
+}
+function readSettings(scope = "global") {
+  const path = getSettingsPath(scope);
   try {
-    if (existsSync(SETTINGS_PATH)) {
-      return JSON.parse(readFileSync(SETTINGS_PATH, "utf-8"));
+    if (existsSync(path)) {
+      return JSON.parse(readFileSync(path, "utf-8"));
     }
   } catch {}
   return {};
 }
-function writeSettings(settings) {
-  const dir = dirname(SETTINGS_PATH);
+function writeSettings(settings, scope = "global") {
+  const path = getSettingsPath(scope);
+  const dir = dirname(path);
   if (!existsSync(dir)) {
     mkdirSync(dir, { recursive: true });
   }
-  writeFileSync(SETTINGS_PATH, JSON.stringify(settings, null, 2) + `
+  writeFileSync(path, JSON.stringify(settings, null, 2) + `
 `);
 }
 function installHook(name, options = {}) {
-  const { targetDir = process.cwd(), overwrite = false } = options;
+  const { scope = "global", overwrite = false } = options;
   const hookName = name.startsWith("hook-") ? name : `hook-${name}`;
   const shortName = hookName.replace("hook-", "");
-  const sourcePath = getHookPath(name);
-  const destDir = join(targetDir, ".hooks");
-  const destPath = join(destDir, hookName);
-  if (!existsSync(sourcePath)) {
-    return {
-      hook: shortName,
-      success: false,
-      error: `Hook '${shortName}' not found`
-    };
+  if (!hookExists(shortName)) {
+    return { hook: shortName, success: false, error: `Hook '${shortName}' not found` };
   }
-  if (existsSync(destPath) && !overwrite) {
-    return {
-      hook: shortName,
-      success: false,
-      error: `Already installed. Use --overwrite to replace.`,
-      path: destPath
-    };
+  const registered = getRegisteredHooks(scope);
+  if (registered.includes(shortName) && !overwrite) {
+    return { hook: shortName, success: false, error: "Already installed. Use --overwrite to replace.", scope };
   }
   try {
-    if (!existsSync(destDir)) {
-      mkdirSync(destDir, { recursive: true });
-    }
-    cpSync(sourcePath, destPath, { recursive: true });
-    registerHookInSettings(shortName);
-    updateHooksIndex(destDir);
-    return {
-      hook: shortName,
-      success: true,
-      path: destPath
-    };
+    registerHook(shortName, scope);
+    return { hook: shortName, success: true, scope };
   } catch (error) {
     return {
       hook: shortName,
@@ -4588,20 +4580,18 @@ function installHook(name, options = {}) {
     };
   }
 }
-function registerHookInSettings(name) {
+function registerHook(name, scope = "global") {
   const meta = getHook(name);
   if (!meta)
     return;
-  const settings = readSettings();
+  const settings = readSettings(scope);
   if (!settings.hooks)
     settings.hooks = {};
   const eventKey = meta.event;
   if (!settings.hooks[eventKey])
     settings.hooks[eventKey] = [];
-  const hookCommand = `hook-${name}`;
-  const existing = settings.hooks[eventKey].find((entry2) => entry2.hooks?.some((h) => h.command?.includes(hookCommand)));
-  if (existing)
-    return;
+  const hookCommand = `hooks run ${name}`;
+  settings.hooks[eventKey] = settings.hooks[eventKey].filter((entry2) => !entry2.hooks?.some((h) => h.command === hookCommand));
   const entry = {
     hooks: [{ type: "command", command: hookCommand }]
   };
@@ -4609,66 +4599,39 @@ function registerHookInSettings(name) {
     entry.matcher = meta.matcher;
   }
   settings.hooks[eventKey].push(entry);
-  writeSettings(settings);
+  writeSettings(settings, scope);
 }
-function unregisterHookFromSettings(name) {
+function unregisterHook(name, scope = "global") {
   const meta = getHook(name);
   if (!meta)
     return;
-  const settings = readSettings();
+  const settings = readSettings(scope);
   if (!settings.hooks)
     return;
   const eventKey = meta.event;
   if (!settings.hooks[eventKey])
     return;
-  const hookCommand = `hook-${name}`;
-  settings.hooks[eventKey] = settings.hooks[eventKey].filter((entry) => !entry.hooks?.some((h) => h.command?.includes(hookCommand)));
+  const hookCommand = `hooks run ${name}`;
+  settings.hooks[eventKey] = settings.hooks[eventKey].filter((entry) => !entry.hooks?.some((h) => h.command === hookCommand));
   if (settings.hooks[eventKey].length === 0) {
     delete settings.hooks[eventKey];
   }
   if (Object.keys(settings.hooks).length === 0) {
     delete settings.hooks;
   }
-  writeSettings(settings);
-}
-function updateHooksIndex(hooksDir) {
-  const indexPath = join(hooksDir, "index.ts");
-  const { readdirSync } = __require("fs");
-  const hooks = readdirSync(hooksDir).filter((f) => f.startsWith("hook-") && !f.includes("."));
-  const exports = hooks.map((h) => {
-    const name = h.replace("hook-", "");
-    return `export * as ${name} from './${h}/src/index.js';`;
-  }).join(`
-`);
-  const content = `/**
- * Auto-generated index of installed hooks
- * Do not edit manually - run 'hooks install' to update
- */
-
-${exports}
-`;
-  writeFileSync(indexPath, content);
+  writeSettings(settings, scope);
 }
-function getInstalledHooks(targetDir = process.cwd()) {
-  const hooksDir = join(targetDir, ".hooks");
-  if (!existsSync(hooksDir)) {
-    return [];
-  }
-  const { readdirSync, statSync } = __require("fs");
-  return readdirSync(hooksDir).filter((f) => {
-    const fullPath = join(hooksDir, f);
-    return f.startsWith("hook-") && statSync(fullPath).isDirectory();
-  }).map((f) => f.replace("hook-", ""));
-}
-function getRegisteredHooks() {
-  const settings = readSettings();
+function getRegisteredHooks(scope = "global") {
+  const settings = readSettings(scope);
   if (!settings.hooks)
     return [];
   const registered = [];
   for (const eventKey of Object.keys(settings.hooks)) {
     for (const entry of settings.hooks[eventKey]) {
       for (const hook of entry.hooks || []) {
-        const match = hook.command?.match(/hook-(\w+)/);
+        const newMatch = hook.command?.match(/^hooks run (\w+)$/);
+        const oldMatch = hook.command?.match(/^hook-(\w+)$/);
+        const match = newMatch || oldMatch;
         if (match) {
           registered.push(match[1]);
         }
@@ -4677,18 +4640,17 @@ function getRegisteredHooks() {
   }
   return [...new Set(registered)];
 }
-function removeHook(name, targetDir = process.cwd()) {
-  const { rmSync } = __require("fs");
+function getInstalledHooks(scope = "global") {
+  return getRegisteredHooks(scope);
+}
+function removeHook(name, scope = "global") {
   const hookName = name.startsWith("hook-") ? name : `hook-${name}`;
   const shortName = hookName.replace("hook-", "");
-  const hooksDir = join(targetDir, ".hooks");
-  const hookPath = join(hooksDir, hookName);
-  if (!existsSync(hookPath)) {
+  const registered = getRegisteredHooks(scope);
+  if (!registered.includes(shortName)) {
     return false;
   }
-  rmSync(hookPath, { recursive: true });
-  unregisterHookFromSettings(shortName);
-  updateHooksIndex(hooksDir);
+  unregisterHook(shortName, scope);
   return true;
 }
 
@@ -5028,42 +4990,115 @@ function App({ initialHooks, overwrite = false }) {
 // src/cli/index.tsx
 import { jsxDEV as jsxDEV8 } from "react/jsx-dev-runtime";
 var program2 = new Command;
-program2.name("hooks").description("Install Claude Code hooks for your project").version("0.0.1");
+function resolveScope(options) {
+  if (options.project)
+    return "project";
+  return "global";
+}
+program2.name("hooks").description("Install Claude Code hooks for your project").version("0.0.6");
 program2.command("interactive", { isDefault: true }).alias("i").description("Interactive hook browser").action(() => {
   render(/* @__PURE__ */ jsxDEV8(App, {}, undefined, false, undefined, this));
 });
-program2.command("install").alias("add").argument("[hooks...]", "Hooks to install").option("-o, --overwrite", "Overwrite existing hooks", false).description("Install one or more hooks").action((hooks, options) => {
-  if (hooks.length === 0) {
+program2.command("run").argument("<hook>", "Hook to run").description("Execute a hook (called by Claude Code)").action(async (hook) => {
+  const meta = getHook(hook);
+  if (!meta) {
+    console.error(JSON.stringify({ error: `Hook '${hook}' not found` }));
+    process.exit(1);
+  }
+  const hookDir = getHookPath(hook);
+  const hookScript = join2(hookDir, "src", "hook.ts");
+  if (!existsSync2(hookScript)) {
+    console.error(JSON.stringify({ error: `Hook script not found: ${hookScript}` }));
+    process.exit(1);
+  }
+  const stdin = await new Response(Bun.stdin.stream()).text();
+  const proc = Bun.spawn(["bun", "run", hookScript], {
+    stdin: new Response(stdin),
+    stdout: "pipe",
+    stderr: "pipe",
+    env: process.env
+  });
+  const stdout = await new Response(proc.stdout).text();
+  const stderr = await new Response(proc.stderr).text();
+  const exitCode = await proc.exited;
+  if (stdout)
+    process.stdout.write(stdout);
+  if (stderr)
+    process.stderr.write(stderr);
+  process.exit(exitCode);
+});
+program2.command("install").alias("add").argument("[hooks...]", "Hooks to install").option("-o, --overwrite", "Overwrite existing hooks", false).option("-a, --all", "Install all available hooks", false).option("-c, --category <category>", "Install all hooks in a category").option("-g, --global", "Install globally (~/.claude/settings.json)", false).option("-p, --project", "Install for current project (.claude/settings.json)", false).option("-j, --json", "Output as JSON", false).description("Install one or more hooks").action((hooks, options) => {
+  const scope = resolveScope(options);
+  let toInstall = hooks;
+  if (options.all) {
+    toInstall = HOOKS.map((h) => h.name);
+  } else if (options.category) {
+    const category = CATEGORIES.find((c) => c.toLowerCase() === options.category.toLowerCase());
+    if (!category) {
+      if (options.json) {
+        console.log(JSON.stringify({ error: `Unknown category: ${options.category}`, available: [...CATEGORIES] }));
+      } else {
+        console.log(chalk2.red(`Unknown category: ${options.category}`));
+        console.log(chalk2.dim(`Available: ${CATEGORIES.join(", ")}`));
+      }
+      return;
+    }
+    toInstall = getHooksByCategory(category).map((h) => h.name);
+  }
+  if (toInstall.length === 0) {
     render(/* @__PURE__ */ jsxDEV8(App, {}, undefined, false, undefined, this));
     return;
   }
+  const results = [];
+  for (const name of toInstall) {
+    const result = installHook(name, { scope, overwrite: options.overwrite });
+    results.push(result);
+  }
+  if (options.json) {
+    console.log(JSON.stringify({
+      installed: results.filter((r) => r.success).map((r) => r.hook),
+      failed: results.filter((r) => !r.success).map((r) => ({ hook: r.hook, error: r.error })),
+      total: results.length,
+      success: results.filter((r) => r.success).length,
+      scope
+    }));
+    return;
+  }
+  const settingsFile = scope === "project" ? ".claude/settings.json" : "~/.claude/settings.json";
   console.log(chalk2.bold(`
-Installing hooks...
+Installing hooks (${scope})...
 `));
-  for (const name of hooks) {
-    const result = installHook(name, { overwrite: options.overwrite });
+  for (const result of results) {
     if (result.success) {
-      const meta = getHook(name);
-      console.log(chalk2.green(`\u2713 ${name}`));
+      const meta = getHook(result.hook);
+      console.log(chalk2.green(`\u2713 ${result.hook}`));
       if (meta) {
-        console.log(chalk2.dim(`  ${meta.event}${meta.matcher ? ` [${meta.matcher}]` : ""} \u2192 hook-${name}`));
+        console.log(chalk2.dim(`  ${meta.event}${meta.matcher ? ` [${meta.matcher}]` : ""} \u2192 hooks run ${result.hook}`));
       }
     } else {
-      console.log(chalk2.red(`\u2717 ${name}: ${result.error}`));
+      console.log(chalk2.red(`\u2717 ${result.hook}: ${result.error}`));
     }
   }
   console.log(chalk2.dim(`
-Hooks installed to .hooks/ and registered in ~/.claude/settings.json`));
+Registered in ${settingsFile}`));
 });
-program2.command("list").alias("ls").option("-c, --category <category>", "Filter by category").option("-a, --all", "Show all available hooks", false).option("-i, --installed", "Show only installed hooks", false).option("-r, --registered", "Show hooks registered in Claude settings", false).description("List available or installed hooks").action((options) => {
-  if (options.registered) {
-    const registered = getRegisteredHooks();
+program2.command("list").alias("ls").option("-c, --category <category>", "Filter by category").option("-a, --all", "Show all available hooks", false).option("-i, --installed", "Show only installed hooks", false).option("-r, --registered", "Show hooks registered in Claude settings", false).option("-g, --global", "Check global settings", false).option("-p, --project", "Check project settings", false).option("-j, --json", "Output as JSON", false).description("List available or installed hooks").action((options) => {
+  const scope = resolveScope(options);
+  if (options.registered || options.installed) {
+    const registered = getRegisteredHooks(scope);
+    if (options.json) {
+      console.log(JSON.stringify(registered.map((name) => {
+        const meta = getHook(name);
+        return { name, event: meta?.event, version: meta?.version, description: meta?.description, scope };
+      })));
+      return;
+    }
     if (registered.length === 0) {
-      console.log(chalk2.dim("No hooks registered in Claude settings"));
+      console.log(chalk2.dim(`No hooks registered (${scope})`));
       return;
     }
     console.log(chalk2.bold(`
-Registered hooks (${registered.length}):
+Registered hooks \u2014 ${scope} (${registered.length}):
 `));
     for (const name of registered) {
       const meta = getHook(name);
@@ -5071,28 +5106,22 @@ Registered hooks (${registered.length}):
     }
     return;
   }
-  if (options.installed) {
-    const installed = getInstalledHooks();
-    if (installed.length === 0) {
-      console.log(chalk2.dim("No hooks installed"));
-      return;
-    }
-    console.log(chalk2.bold(`
-Installed hooks (${installed.length}):
-`));
-    for (const name of installed) {
-      console.log(`  ${name}`);
-    }
-    return;
-  }
   if (options.category) {
     const category = CATEGORIES.find((c) => c.toLowerCase() === options.category.toLowerCase());
     if (!category) {
-      console.log(chalk2.red(`Unknown category: ${options.category}`));
-      console.log(chalk2.dim(`Available: ${CATEGORIES.join(", ")}`));
+      if (options.json) {
+        console.log(JSON.stringify({ error: `Unknown category: ${options.category}`, available: [...CATEGORIES] }));
+      } else {
+        console.log(chalk2.red(`Unknown category: ${options.category}`));
+        console.log(chalk2.dim(`Available: ${CATEGORIES.join(", ")}`));
+      }
       return;
     }
     const hooks = getHooksByCategory(category);
+    if (options.json) {
+      console.log(JSON.stringify(hooks));
+      return;
+    }
     console.log(chalk2.bold(`
 ${category} (${hooks.length}):
 `));
@@ -5101,6 +5130,14 @@ ${category} (${hooks.length}):
     }
     return;
   }
+  if (options.json) {
+    const result = {};
+    for (const category of CATEGORIES) {
+      result[category] = getHooksByCategory(category);
+    }
+    console.log(JSON.stringify(result));
+    return;
+  }
   console.log(chalk2.bold(`
 Available hooks (${HOOKS.length}):
 `));
@@ -5113,8 +5150,12 @@ Available hooks (${HOOKS.length}):
     console.log();
   }
 });
-program2.command("search").argument("<query>", "Search term").description("Search for hooks").action((query) => {
+program2.command("search").argument("<query>", "Search term").option("-j, --json", "Output as JSON", false).description("Search for hooks").action((query, options) => {
   const results = searchHooks(query);
+  if (options.json) {
+    console.log(JSON.stringify(results));
+    return;
+  }
   if (results.length === 0) {
     console.log(chalk2.dim(`No hooks found for "${query}"`));
     return;
@@ -5127,15 +5168,28 @@ Found ${results.length} hook(s):
     console.log(`    ${h.description}`);
   }
 });
-program2.command("remove").alias("rm").argument("<hook>", "Hook to remove").description("Remove an installed hook").action((hook) => {
-  const removed = removeHook(hook);
+program2.command("remove").alias("rm").argument("<hook>", "Hook to remove").option("-g, --global", "Remove from global settings", false).option("-p, --project", "Remove from project settings", false).option("-j, --json", "Output as JSON", false).description("Remove an installed hook").action((hook, options) => {
+  const scope = resolveScope(options);
+  const removed = removeHook(hook, scope);
+  if (options.json) {
+    console.log(JSON.stringify({ hook, removed, scope }));
+    return;
+  }
   if (removed) {
-    console.log(chalk2.green(`\u2713 Removed ${hook} (unregistered from Claude settings)`));
+    console.log(chalk2.green(`\u2713 Removed ${hook} (${scope})`));
   } else {
-    console.log(chalk2.red(`\u2717 ${hook} is not installed`));
+    console.log(chalk2.red(`\u2717 ${hook} is not installed (${scope})`));
   }
 });
-program2.command("categories").description("List all categories").action(() => {
+program2.command("categories").option("-j, --json", "Output as JSON", false).description("List all categories").action((options) => {
+  if (options.json) {
+    const result = CATEGORIES.map((cat) => ({
+      name: cat,
+      count: getHooksByCategory(cat).length
+    }));
+    console.log(JSON.stringify(result));
+    return;
+  }
   console.log(chalk2.bold(`
 Categories:
 `));
@@ -5144,10 +5198,20 @@ Categories:
     console.log(`  ${category} (${count})`);
   }
 });
-program2.command("info").argument("<hook>", "Hook name").description("Show detailed info about a hook").action((hook) => {
+program2.command("info").argument("<hook>", "Hook name").option("-j, --json", "Output as JSON", false).description("Show detailed info about a hook").action((hook, options) => {
   const meta = getHook(hook);
   if (!meta) {
-    console.log(chalk2.red(`Hook '${hook}' not found`));
+    if (options.json) {
+      console.log(JSON.stringify({ error: `Hook '${hook}' not found` }));
+    } else {
+      console.log(chalk2.red(`Hook '${hook}' not found`));
+    }
+    return;
+  }
+  const globalInstalled = getRegisteredHooks("global").includes(meta.name);
+  const projectInstalled = getRegisteredHooks("project").includes(meta.name);
+  if (options.json) {
+    console.log(JSON.stringify({ ...meta, global: globalInstalled, project: projectInstalled }));
     return;
   }
   console.log(chalk2.bold(`
@@ -5156,16 +5220,248 @@ ${meta.displayName}
   console.log(`  ${meta.description}`);
   console.log();
   console.log(`  ${chalk2.dim("Category:")}  ${meta.category}`);
+  console.log(`  ${chalk2.dim("Version:")}   ${meta.version}`);
   console.log(`  ${chalk2.dim("Event:")}     ${meta.event}`);
   console.log(`  ${chalk2.dim("Matcher:")}   ${meta.matcher || "(none)"}`);
   console.log(`  ${chalk2.dim("Tags:")}      ${meta.tags.join(", ")}`);
-  console.log(`  ${chalk2.dim("Package:")}   hook-${meta.name}`);
+  console.log(`  ${chalk2.dim("Command:")}   hooks run ${meta.name}`);
   console.log();
-  const registered = getRegisteredHooks();
-  if (registered.includes(meta.name)) {
-    console.log(chalk2.green("  \u25CF Registered in Claude settings"));
+  if (globalInstalled) {
+    console.log(chalk2.green("  \u25CF Installed globally"));
+  } else {
+    console.log(chalk2.dim("  \u25CB Not installed globally"));
+  }
+  if (projectInstalled) {
+    console.log(chalk2.green("  \u25CF Installed in project"));
   } else {
-    console.log(chalk2.dim("  \u25CB Not registered"));
+    console.log(chalk2.dim("  \u25CB Not installed in project"));
   }
 });
+program2.command("doctor").option("-g, --global", "Check global settings", false).option("-p, --project", "Check project settings", false).option("-j, --json", "Output as JSON", false).description("Check health of installed hooks").action((options) => {
+  const scope = resolveScope(options);
+  const settingsPath = getSettingsPath(scope);
+  const issues = [];
+  const healthy = [];
+  const settingsExist = existsSync2(settingsPath);
+  if (!settingsExist) {
+    issues.push({ hook: "(settings)", issue: `${settingsPath} not found`, severity: "warning" });
+  }
+  const registered = getRegisteredHooks(scope);
+  for (const name of registered) {
+    const meta = getHook(name);
+    let hookHealthy = true;
+    if (!hookExists(name)) {
+      issues.push({ hook: name, issue: "Hook not found in @hasna/hooks package", severity: "error" });
+      hookHealthy = false;
+      continue;
+    }
+    const hookDir = getHookPath(name);
+    const hookScript = join2(hookDir, "src", "hook.ts");
+    if (!existsSync2(hookScript)) {
+      issues.push({ hook: name, issue: "Missing src/hook.ts in package", severity: "error" });
+      hookHealthy = false;
+    }
+    if (meta && settingsExist) {
+      try {
+        const settings = JSON.parse(readFileSync2(settingsPath, "utf-8"));
+        const eventHooks = settings.hooks?.[meta.event] || [];
+        const found = eventHooks.some((entry) => entry.hooks?.some((h) => h.command === `hooks run ${name}`));
+        if (!found) {
+          issues.push({ hook: name, issue: `Not registered under correct event (${meta.event})`, severity: "error" });
+          hookHealthy = false;
+        }
+      } catch {}
+    }
+    if (hookHealthy) {
+      healthy.push(name);
+    }
+  }
+  if (options.json) {
+    console.log(JSON.stringify({ healthy, issues, registered, scope }));
+    return;
+  }
+  console.log(chalk2.bold(`
+Hook Health Check (${scope})
+`));
+  if (registered.length === 0) {
+    console.log(chalk2.dim("  No hooks registered."));
+    console.log(chalk2.dim("  Run: hooks install gitguard"));
+    return;
+  }
+  if (healthy.length > 0) {
+    console.log(chalk2.green(`  \u2713 ${healthy.length} hook(s) healthy:`));
+    for (const name of healthy) {
+      console.log(chalk2.green(`    ${name}`));
+    }
+  }
+  if (issues.length > 0) {
+    console.log();
+    for (const issue of issues) {
+      const icon = issue.severity === "error" ? chalk2.red("\u2717") : chalk2.yellow("!");
+      console.log(`  ${icon} ${chalk2.cyan(issue.hook)}: ${issue.issue}`);
+    }
+  }
+  if (issues.length === 0) {
+    console.log(chalk2.green(`
+  All hooks healthy!`));
+  }
+  console.log();
+});
+program2.command("update").argument("[hooks...]", "Hooks to update (defaults to all installed)").option("-g, --global", "Update global hooks", false).option("-p, --project", "Update project hooks", false).option("-j, --json", "Output as JSON", false).description("Re-register hooks (picks up new package version)").action((hooks, options) => {
+  const scope = resolveScope(options);
+  const installed = getInstalledHooks(scope);
+  const toUpdate = hooks.length > 0 ? hooks : installed;
+  if (toUpdate.length === 0) {
+    if (options.json) {
+      console.log(JSON.stringify({ updated: [], error: "No hooks installed" }));
+    } else {
+      console.log(chalk2.dim("No hooks installed to update."));
+    }
+    return;
+  }
+  const results = [];
+  for (const name of toUpdate) {
+    if (!installed.includes(name)) {
+      results.push({ hook: name, success: false, error: "Not installed" });
+      continue;
+    }
+    const result = installHook(name, { scope, overwrite: true });
+    results.push(result);
+  }
+  if (options.json) {
+    console.log(JSON.stringify({
+      updated: results.filter((r) => r.success).map((r) => r.hook),
+      failed: results.filter((r) => !r.success).map((r) => ({ hook: r.hook, error: r.error }))
+    }));
+    return;
+  }
+  console.log(chalk2.bold(`
+Updating hooks...
+`));
+  for (const result of results) {
+    if (result.success) {
+      console.log(chalk2.green(`\u2713 ${result.hook} updated`));
+    } else {
+      console.log(chalk2.red(`\u2717 ${result.hook}: ${result.error}`));
+    }
+  }
+});
+program2.command("docs").argument("[hook]", "Hook name (shows general docs if omitted)").option("-j, --json", "Output as JSON", false).description("Show documentation for hooks").action((hook, options) => {
+  if (hook) {
+    const meta = getHook(hook);
+    if (!meta) {
+      if (options.json) {
+        console.log(JSON.stringify({ error: `Hook '${hook}' not found` }));
+      } else {
+        console.log(chalk2.red(`Hook '${hook}' not found`));
+      }
+      return;
+    }
+    const hookPath = getHookPath(hook);
+    const readmePath = join2(hookPath, "README.md");
+    let readme = "";
+    if (existsSync2(readmePath)) {
+      readme = readFileSync2(readmePath, "utf-8");
+    }
+    if (options.json) {
+      console.log(JSON.stringify({ ...meta, readme }));
+      return;
+    }
+    console.log(chalk2.bold(`
+${meta.displayName} v${meta.version}
+`));
+    console.log(`  ${meta.description}
+`);
+    console.log(chalk2.bold("  Configuration:"));
+    console.log(`    Event:    ${meta.event}`);
+    console.log(`    Matcher:  ${meta.matcher || "(all tools)"}`);
+    console.log(`    Command:  hooks run ${meta.name}`);
+    console.log();
+    console.log(chalk2.bold("  Install:"));
+    console.log(`    hooks install ${meta.name}            # global`);
+    console.log(`    hooks install ${meta.name} --project   # project only`);
+    console.log();
+    if (readme) {
+      console.log(chalk2.bold(`  README:
+`));
+      for (const line of readme.split(`
+`)) {
+        console.log(`    ${line}`);
+      }
+    }
+    return;
+  }
+  const generalDocs = {
+    overview: "Claude Code hooks are scripts that run at specific points in a Claude Code session. Install @hasna/hooks globally, then register hooks \u2014 no files are copied to your project.",
+    events: {
+      PreToolUse: 'Fires before a tool executes. Can block the operation by returning { "decision": "block" }.',
+      PostToolUse: "Fires after a tool executes. Runs asynchronously, cannot block.",
+      Stop: "Fires when a Claude Code session ends. Useful for notifications and cleanup.",
+      Notification: "Fires on notification events like context compaction."
+    },
+    installation: {
+      global: "hooks install gitguard",
+      project: "hooks install gitguard --project",
+      category: 'hooks install --category "Git Safety"',
+      all: "hooks install --all"
+    },
+    management: {
+      list: "hooks list",
+      listInstalled: "hooks list --installed",
+      search: "hooks search <query>",
+      info: "hooks info <name>",
+      remove: "hooks remove <name>",
+      update: "hooks update",
+      doctor: "hooks doctor",
+      docs: "hooks docs <name>"
+    },
+    howItWorks: {
+      install: "bun install -g @hasna/hooks",
+      register: "hooks install gitguard \u2192 writes to ~/.claude/settings.json",
+      execution: "Claude Code runs 'hooks run gitguard' \u2192 executes hook from global package",
+      noFileCopy: "No files are copied to your project. Hooks run from the global @hasna/hooks package."
+    }
+  };
+  if (options.json) {
+    console.log(JSON.stringify(generalDocs));
+    return;
+  }
+  console.log(chalk2.bold(`
+@hasna/hooks Documentation
+`));
+  console.log(chalk2.bold(`  Overview
+`));
+  console.log(`    ${generalDocs.overview}
+`);
+  console.log(chalk2.bold(`  How It Works
+`));
+  for (const [label, desc] of Object.entries(generalDocs.howItWorks)) {
+    console.log(`    ${chalk2.dim(label + ":")}  ${desc}`);
+  }
+  console.log(chalk2.bold(`
+  Hook Events
+`));
+  for (const [event, desc] of Object.entries(generalDocs.events)) {
+    console.log(`    ${chalk2.cyan(event)}`);
+    console.log(`      ${desc}
+`);
+  }
+  console.log(chalk2.bold(`  Installation
+`));
+  for (const [label, cmd] of Object.entries(generalDocs.installation)) {
+    console.log(`    ${chalk2.dim(label + ":")}  ${cmd}`);
+  }
+  console.log(chalk2.bold(`
+  Management
+`));
+  for (const [label, cmd] of Object.entries(generalDocs.management)) {
+    console.log(`    ${chalk2.dim(label + ":")}  ${cmd}`);
+  }
+  console.log(chalk2.bold(`
+  Hook-Specific Docs
+`));
+  console.log(`    hooks docs <name>     View README for a specific hook`);
+  console.log(`    hooks docs --json     Machine-readable documentation`);
+  console.log();
+});
 program2.parse();