@hasna/hooks 0.2.3 → 0.2.4

package/bin/index.js

@@ -2184,6 +2184,16 @@ var init_registry = __esm(() => {
       matcher: "",
       tags: ["errors", "failures", "logging", "debugging"]
     },
+    {
+      name: "stylescheck",
+      displayName: "Styles Check",
+      description: "Blocks frontend files with design anti-patterns: hardcoded colors, magic font sizes, inline styles",
+      version: "0.1.0",
+      category: "Code Quality",
+      event: "PreToolUse",
+      matcher: "Write|Edit",
+      tags: ["design", "styles", "frontend", "css", "tailwind", "design-system", "anti-patterns"]
+    },
     {
       name: "taskgate",
       displayName: "Task Gate",
@@ -3848,8 +3858,11 @@ function normalizeHookName(name) {
 function shortHookName(name) {
   return normalizeHookName(name).replace("hook-", "");
 }
-function removeHookEntries(entries, hookCommand) {
-  return entries.filter((entry) => !entry.hooks?.some((h) => h.command === hookCommand));
+function removeHookEntriesByName(entries, hookName) {
+  return entries.filter((entry) => !entry.hooks?.some((h) => {
+    const match = h.command?.match(/^hooks run (\w+)/);
+    return match && match[1] === hookName;
+  }));
 }
 function getTargetSettingsDir(target) {
   if (target === "gemini")
@@ -3892,7 +3905,7 @@ function writeSettings(settings, scope = "global", target = "claude") {
 function getTargetEventName(internalEvent, target) {
   return EVENT_MAP[target]?.[internalEvent] || internalEvent;
 }
-function installForTarget(name, scope, overwrite, target) {
+function installForTarget(name, scope, overwrite, target, profile) {
   const shortName = shortHookName(name);
   if (!hookExists(shortName)) {
     return { hook: shortName, success: false, error: `Hook '${shortName}' not found`, target };
@@ -3902,7 +3915,7 @@ function installForTarget(name, scope, overwrite, target) {
     return { hook: shortName, success: false, error: "Already installed. Use --overwrite to replace.", scope, target };
   }
   try {
-    registerHook(shortName, scope, target);
+    registerHook(shortName, scope, target, profile);
     return { hook: shortName, success: true, scope, target };
   } catch (error) {
     return {
@@ -3914,15 +3927,15 @@ function installForTarget(name, scope, overwrite, target) {
   }
 }
 function installHook(name, options = {}) {
-  const { scope = "global", overwrite = false, target = "claude" } = options;
+  const { scope = "global", overwrite = false, target = "claude", profile } = options;
   if (target === "all") {
-    const claudeResult = installForTarget(name, scope, overwrite, "claude");
-    installForTarget(name, scope, overwrite, "gemini");
+    const claudeResult = installForTarget(name, scope, overwrite, "claude", profile);
+    installForTarget(name, scope, overwrite, "gemini", profile);
     return { ...claudeResult, target: "all" };
   }
-  return installForTarget(name, scope, overwrite, target);
+  return installForTarget(name, scope, overwrite, target, profile);
 }
-function registerHook(name, scope = "global", target = "claude") {
+function registerHook(name, scope = "global", target = "claude", profile) {
   const meta = getHook(name);
   if (!meta)
     return;
@@ -3932,8 +3945,8 @@ function registerHook(name, scope = "global", target = "claude") {
   const eventKey = getTargetEventName(meta.event, target);
   if (!settings.hooks[eventKey])
     settings.hooks[eventKey] = [];
-  const hookCommand = `hooks run ${name}`;
-  settings.hooks[eventKey] = removeHookEntries(settings.hooks[eventKey], hookCommand);
+  settings.hooks[eventKey] = removeHookEntriesByName(settings.hooks[eventKey], name);
+  const hookCommand = profile ? `hooks run ${name} --profile ${profile}` : `hooks run ${name}`;
   const entry = {
     hooks: [{ type: "command", command: hookCommand }]
   };
@@ -3953,8 +3966,7 @@ function unregisterHook(name, scope = "global", target = "claude") {
   const eventKey = getTargetEventName(meta.event, target);
   if (!settings.hooks[eventKey])
     return;
-  const hookCommand = `hooks run ${name}`;
-  settings.hooks[eventKey] = removeHookEntries(settings.hooks[eventKey], hookCommand);
+  settings.hooks[eventKey] = removeHookEntriesByName(settings.hooks[eventKey], name);
   if (settings.hooks[eventKey].length === 0) {
     delete settings.hooks[eventKey];
   }
@@ -3971,7 +3983,7 @@ function getRegisteredHooksForTarget(scope = "global", target = "claude") {
   for (const eventKey of Object.keys(settings.hooks)) {
     for (const entry of settings.hooks[eventKey]) {
       for (const hook of entry.hooks || []) {
-        const newMatch = hook.command?.match(/^hooks run (\w+)$/);
+        const newMatch = hook.command?.match(/^hooks run (\w+)(?:\s+--profile\s+\w+)?$/);
         const oldMatch = hook.command?.match(/^hook-(\w+)$/);
         const match = newMatch || oldMatch;
         if (match) {
@@ -4024,6 +4036,79 @@ var init_installer = __esm(() => {
   getInstalledHooks = getRegisteredHooks;
 });
 
+// src/lib/profiles.ts
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2, readdirSync, rmSync } from "fs";
+import { join as join2 } from "path";
+import { homedir as homedir2 } from "os";
+function ensureProfilesDir() {
+  if (!existsSync2(PROFILES_DIR)) {
+    mkdirSync2(PROFILES_DIR, { recursive: true });
+  }
+}
+function profilePath(id) {
+  return join2(PROFILES_DIR, `${id}.json`);
+}
+function shortUuid() {
+  return crypto.randomUUID().slice(0, 8);
+}
+function createProfile(input) {
+  ensureProfilesDir();
+  const id = shortUuid();
+  const now = new Date().toISOString();
+  const profile = {
+    agent_id: id,
+    agent_type: input.agent_type,
+    created_at: now,
+    last_seen_at: now,
+    preferences: {}
+  };
+  if (input.name) {
+    profile.name = input.name;
+  }
+  writeFileSync2(profilePath(id), JSON.stringify(profile, null, 2) + `
+`);
+  return profile;
+}
+function getProfile(id) {
+  const path = profilePath(id);
+  try {
+    if (!existsSync2(path))
+      return null;
+    return JSON.parse(readFileSync2(path, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function listProfiles() {
+  if (!existsSync2(PROFILES_DIR))
+    return [];
+  try {
+    const files = readdirSync(PROFILES_DIR).filter((f) => f.endsWith(".json"));
+    const profiles = [];
+    for (const file of files) {
+      try {
+        const content = readFileSync2(join2(PROFILES_DIR, file), "utf-8");
+        profiles.push(JSON.parse(content));
+      } catch {}
+    }
+    return profiles.sort((a, b) => new Date(a.created_at).getTime() - new Date(b.created_at).getTime());
+  } catch {
+    return [];
+  }
+}
+function touchProfile(id) {
+  const profile = getProfile(id);
+  if (!profile)
+    return;
+  profile.last_seen_at = new Date().toISOString();
+  writeFileSync2(profilePath(id), JSON.stringify(profile, null, 2) + `
+`);
+}
+var PROFILES_DIR;
+var init_profiles = __esm(() => {
+  PROFILES_DIR = join2(homedir2(), ".hooks", "profiles");
+});
+
 // src/mcp/server.ts
 var exports_server = {};
 __export(exports_server, {
@@ -4037,8 +4122,8 @@ import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { createServer } from "http";
-import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
-import { join as join2, dirname as dirname2 } from "path";
+import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
+import { join as join3, dirname as dirname2 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 function formatInstallResults(results, extra) {
   const installed = results.filter((r) => r.success).map((r) => r.hook);
@@ -4085,10 +4170,11 @@ function createHooksServer() {
   server.tool("hooks_install", "Install one or more hooks by registering them in agent settings", {
     hooks: z.array(z.string()).describe("Hook names to install"),
     scope: z.enum(["global", "project"]).default("global").describe("Install scope"),
-    overwrite: z.boolean().default(false).describe("Overwrite if already installed")
-  }, async ({ hooks, scope, overwrite }) => {
-    const results = hooks.map((name) => installHook(name, { scope, overwrite }));
-    return formatInstallResults(results, { scope });
+    overwrite: z.boolean().default(false).describe("Overwrite if already installed"),
+    profile: z.string().optional().describe("Agent profile ID to scope hooks to")
+  }, async ({ hooks, scope, overwrite, profile }) => {
+    const results = hooks.map((name) => installHook(name, { scope, overwrite, profile }));
+    return formatInstallResults(results, { scope, profile });
   });
   server.tool("hooks_install_category", "Install all hooks in a category", {
     category: z.string().describe("Category name"),
@@ -4123,7 +4209,7 @@ function createHooksServer() {
     const settingsPath = getSettingsPath(scope);
     const issues = [];
     const healthy = [];
-    const settingsExist = existsSync2(settingsPath);
+    const settingsExist = existsSync3(settingsPath);
     if (!settingsExist) {
       issues.push({ hook: "(settings)", issue: `${settingsPath} not found`, severity: "warning" });
     }
@@ -4136,15 +4222,18 @@ function createHooksServer() {
         continue;
       }
       const hookDir = getHookPath(name);
-      if (!existsSync2(join2(hookDir, "src", "hook.ts"))) {
+      if (!existsSync3(join3(hookDir, "src", "hook.ts"))) {
         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 settings = JSON.parse(readFileSync3(settingsPath, "utf-8"));
           const eventHooks = settings.hooks?.[meta.event] || [];
-          const found = eventHooks.some((entry) => entry.hooks?.some((h) => h.command === `hooks run ${name}`));
+          const found = eventHooks.some((entry) => entry.hooks?.some((h) => {
+            const match = h.command?.match(/^hooks run (\w+)/);
+            return match && match[1] === name;
+          }));
           if (!found) {
             issues.push({ hook: name, issue: `Not registered under correct event (${meta.event})`, severity: "error" });
             hookHealthy = false;
@@ -4170,10 +4259,10 @@ function createHooksServer() {
         return { content: [{ type: "text", text: JSON.stringify({ error: `Hook '${name}' not found` }) }] };
       }
       const hookPath = getHookPath(name);
-      const readmePath = join2(hookPath, "README.md");
+      const readmePath = join3(hookPath, "README.md");
       let readme = "";
-      if (existsSync2(readmePath)) {
-        readme = readFileSync2(readmePath, "utf-8");
+      if (existsSync3(readmePath)) {
+        readme = readFileSync3(readmePath, "utf-8");
       }
       return { content: [{ type: "text", text: JSON.stringify({ ...meta, readme }) }] };
     }
@@ -4211,6 +4300,67 @@ function createHooksServer() {
     });
     return { content: [{ type: "text", text: JSON.stringify(result) }] };
   });
+  server.tool("hooks_run", "Execute a hook programmatically with the given input and return its output", {
+    name: z.string().describe("Hook name (e.g. 'gitguard', 'checkpoint')"),
+    input: z.record(z.string(), z.unknown()).default(() => ({})).describe("Hook input as JSON object (HookInput)"),
+    profile: z.string().optional().describe("Agent profile ID to inject into hook input")
+  }, async ({ name, input, profile }) => {
+    const meta = getHook(name);
+    if (!meta) {
+      return { content: [{ type: "text", text: JSON.stringify({ error: `Hook '${name}' not found` }) }] };
+    }
+    const hookDir = getHookPath(name);
+    const hookScript = join3(hookDir, "src", "hook.ts");
+    if (!existsSync3(hookScript)) {
+      return { content: [{ type: "text", text: JSON.stringify({ error: `Hook script not found: ${hookScript}` }) }] };
+    }
+    let hookInput = { ...input };
+    if (profile) {
+      const p = getProfile(profile);
+      if (p) {
+        hookInput.agent = {
+          agent_id: p.agent_id,
+          agent_type: p.agent_type,
+          name: p.name,
+          preferences: p.preferences
+        };
+      }
+    }
+    const proc = Bun.spawn(["bun", "run", hookScript], {
+      stdin: new Response(JSON.stringify(hookInput)),
+      stdout: "pipe",
+      stderr: "pipe",
+      env: process.env
+    });
+    const [stdoutText, stderrText, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited
+    ]);
+    let output = {};
+    try {
+      output = JSON.parse(stdoutText);
+    } catch {
+      output = { raw: stdoutText };
+    }
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify({ hook: name, output, stderr: stderrText || undefined, exitCode })
+      }]
+    };
+  });
+  server.tool("hooks_init", "Register a new agent profile \u2014 returns a unique agent_id for use with hook installation and execution", {
+    agent_type: z.enum(["claude", "gemini", "custom"]).default("claude").describe("Type of AI agent"),
+    name: z.string().optional().describe("Optional display name for the agent")
+  }, async ({ agent_type, name }) => {
+    const profile = createProfile({ agent_type, name });
+    return { content: [{ type: "text", text: JSON.stringify(profile) }] };
+  });
+  server.tool("hooks_profiles", "List all registered agent profiles", {}, async () => {
+    const profiles = listProfiles();
+    return { content: [{ type: "text", text: JSON.stringify(profiles) }] };
+  });
   return server;
 }
 async function startSSEServer(port = MCP_PORT) {
@@ -4254,8 +4404,9 @@ var __dirname3, pkg, MCP_PORT = 39427;
 var init_server = __esm(() => {
   init_registry();
   init_installer();
+  init_profiles();
   __dirname3 = dirname2(fileURLToPath2(import.meta.url));
-  pkg = JSON.parse(readFileSync2(join2(__dirname3, "..", "..", "package.json"), "utf-8"));
+  pkg = JSON.parse(readFileSync3(join3(__dirname3, "..", "..", "package.json"), "utf-8"));
 });
 
 // src/cli/index.tsx
@@ -4279,8 +4430,8 @@ var {
 
 // src/cli/index.tsx
 import chalk2 from "chalk";
-import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
-import { join as join3, dirname as dirname3 } from "path";
+import { existsSync as existsSync4, readFileSync as readFileSync4 } from "fs";
+import { join as join4, dirname as dirname3 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 
 // src/cli/components/App.tsx
@@ -5455,10 +5606,11 @@ function App({ initialHooks, overwrite = false }) {
 // src/cli/index.tsx
 init_registry();
 init_installer();
+init_profiles();
 import { jsxDEV as jsxDEV8 } from "react/jsx-dev-runtime";
 var __dirname4 = dirname3(fileURLToPath3(import.meta.url));
-var pkgPath = existsSync3(join3(__dirname4, "..", "package.json")) ? join3(__dirname4, "..", "package.json") : join3(__dirname4, "..", "..", "package.json");
-var pkg2 = JSON.parse(readFileSync3(pkgPath, "utf-8"));
+var pkgPath = existsSync4(join4(__dirname4, "..", "package.json")) ? join4(__dirname4, "..", "package.json") : join4(__dirname4, "..", "..", "package.json");
+var pkg2 = JSON.parse(readFileSync4(pkgPath, "utf-8"));
 var program2 = new Command;
 function resolveScope(options) {
   if (options.project)
@@ -5469,21 +5621,68 @@ program2.name("hooks").description("Install hooks for AI coding agents").version
 program2.command("interactive", { isDefault: true }).alias("i").description("Interactive hook browser").action(() => {
   render(/* @__PURE__ */ jsxDEV8(App, {}, undefined, false, undefined, this));
 });
-program2.command("run").argument("<hook>", "Hook to run").description("Execute a hook (called by AI coding agents)").action(async (hook) => {
+program2.command("init").description("Register a new agent profile with a unique ID").option("-a, --agent <type>", "Agent type: claude, gemini, custom", "claude").option("-n, --name <name>", "Optional display name for the agent").option("-j, --json", "Output as JSON", false).action((options) => {
+  const agentType = options.agent;
+  if (!["claude", "gemini", "custom"].includes(agentType)) {
+    if (options.json) {
+      console.log(JSON.stringify({ error: `Invalid agent type: ${options.agent}`, valid: ["claude", "gemini", "custom"] }));
+    } else {
+      console.log(chalk2.red(`Invalid agent type: ${options.agent}`));
+      console.log(chalk2.dim("Valid types: claude, gemini, custom"));
+    }
+    return;
+  }
+  const profile = createProfile({ agent_type: agentType, name: options.name });
+  if (options.json) {
+    console.log(JSON.stringify(profile));
+    return;
+  }
+  console.log(chalk2.green(`
+\u2713 Agent profile created
+`));
+  console.log(`  ${chalk2.dim("Agent ID:")}   ${chalk2.bold(profile.agent_id)}`);
+  console.log(`  ${chalk2.dim("Type:")}       ${profile.agent_type}`);
+  if (profile.name) {
+    console.log(`  ${chalk2.dim("Name:")}       ${profile.name}`);
+  }
+  console.log(`  ${chalk2.dim("Profile:")}    ~/.hooks/profiles/${profile.agent_id}.json`);
+  console.log();
+  console.log(chalk2.dim("  Install hooks with this profile:"));
+  console.log(`    hooks install gitguard --profile ${profile.agent_id}`);
+  console.log();
+});
+program2.command("run").argument("<hook>", "Hook to run").option("--profile <id>", "Agent profile ID").description("Execute a hook (called by AI coding agents)").action(async (hook, options) => {
   const meta = getHook(hook);
   if (!meta) {
     console.error(JSON.stringify({ error: `Hook '${hook}' not found` }));
     process.exit(1);
   }
   const hookDir = getHookPath(hook);
-  const hookScript = join3(hookDir, "src", "hook.ts");
-  if (!existsSync3(hookScript)) {
+  const hookScript = join4(hookDir, "src", "hook.ts");
+  if (!existsSync4(hookScript)) {
     console.error(JSON.stringify({ error: `Hook script not found: ${hookScript}` }));
     process.exit(1);
   }
   const stdin = await new Response(Bun.stdin.stream()).text();
+  let hookStdin = stdin;
+  if (options.profile) {
+    const profile = getProfile(options.profile);
+    if (profile) {
+      touchProfile(options.profile);
+      try {
+        const input = JSON.parse(stdin);
+        input.agent = {
+          agent_id: profile.agent_id,
+          agent_type: profile.agent_type,
+          name: profile.name,
+          preferences: profile.preferences
+        };
+        hookStdin = JSON.stringify(input);
+      } catch {}
+    }
+  }
   const proc = Bun.spawn(["bun", "run", hookScript], {
-    stdin: new Response(stdin),
+    stdin: new Response(hookStdin),
     stdout: "pipe",
     stderr: "pipe",
     env: process.env
@@ -5497,7 +5696,7 @@ program2.command("run").argument("<hook>", "Hook to run").description("Execute a
     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) => {
+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("--profile <id>", "Agent profile ID to scope hooks to").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) {
@@ -5521,7 +5720,7 @@ program2.command("install").alias("add").argument("[hooks...]", "Hooks to instal
   }
   const results = [];
   for (const name of toInstall) {
-    const result = installHook(name, { scope, overwrite: options.overwrite });
+    const result = installHook(name, { scope, overwrite: options.overwrite, profile: options.profile });
     results.push(result);
   }
   if (options.json) {
@@ -5552,23 +5751,24 @@ Installing hooks (${scope})...
   console.log(chalk2.dim(`
 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 registered hooks", 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) => {
+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 registered hooks", false).option("-g, --global", "Check global settings", false).option("-p, --project", "Check project settings", false).option("-t, --target <target>", "Agent target: claude, gemini (default: claude)", "claude").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);
+    const target = options.target === "gemini" ? "gemini" : "claude";
+    const registered = getRegisteredHooksForTarget(scope, target);
     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 { name, event: meta?.event, version: meta?.version, description: meta?.description, scope, target };
       })));
       return;
     }
     if (registered.length === 0) {
-      console.log(chalk2.dim(`No hooks registered (${scope})`));
+      console.log(chalk2.dim(`No hooks registered (${scope}, ${target})`));
       return;
     }
     console.log(chalk2.bold(`
-Registered hooks \u2014 ${scope} (${registered.length}):
+Registered hooks \u2014 ${scope}/${target} (${registered.length}):
 `));
     for (const name of registered) {
       const meta = getHook(name);
@@ -5712,7 +5912,7 @@ program2.command("doctor").option("-g, --global", "Check global settings", false
   const settingsPath = getSettingsPath(scope);
   const issues = [];
   const healthy = [];
-  const settingsExist = existsSync3(settingsPath);
+  const settingsExist = existsSync4(settingsPath);
   if (!settingsExist) {
     issues.push({ hook: "(settings)", issue: `${settingsPath} not found`, severity: "warning" });
   }
@@ -5726,16 +5926,19 @@ program2.command("doctor").option("-g, --global", "Check global settings", false
       continue;
     }
     const hookDir = getHookPath(name);
-    const hookScript = join3(hookDir, "src", "hook.ts");
-    if (!existsSync3(hookScript)) {
+    const hookScript = join4(hookDir, "src", "hook.ts");
+    if (!existsSync4(hookScript)) {
       issues.push({ hook: name, issue: "Missing src/hook.ts in package", severity: "error" });
       hookHealthy = false;
     }
     if (meta && settingsExist) {
       try {
-        const settings = JSON.parse(readFileSync3(settingsPath, "utf-8"));
+        const settings = JSON.parse(readFileSync4(settingsPath, "utf-8"));
         const eventHooks = settings.hooks?.[meta.event] || [];
-        const found = eventHooks.some((entry) => entry.hooks?.some((h) => h.command === `hooks run ${name}`));
+        const found = eventHooks.some((entry) => entry.hooks?.some((h) => {
+          const match = h.command?.match(/^hooks run (\w+)/);
+          return match && match[1] === name;
+        }));
         if (!found) {
           issues.push({ hook: name, issue: `Not registered under correct event (${meta.event})`, severity: "error" });
           hookHealthy = false;
@@ -5828,10 +6031,10 @@ program2.command("docs").argument("[hook]", "Hook name (shows general docs if om
       return;
     }
     const hookPath = getHookPath(hook);
-    const readmePath = join3(hookPath, "README.md");
+    const readmePath = join4(hookPath, "README.md");
     let readme = "";
-    if (existsSync3(readmePath)) {
-      readme = readFileSync3(readmePath, "utf-8");
+    if (existsSync4(readmePath)) {
+      readme = readFileSync4(readmePath, "utf-8");
     }
     if (options.json) {
       console.log(JSON.stringify({ ...meta, readme }));
@@ -5934,6 +6137,68 @@ ${meta.displayName} v${meta.version}
   console.log(`    hooks docs --json     Machine-readable documentation`);
   console.log();
 });
+program2.command("upgrade").option("-c, --check", "Check for updates without installing", false).option("-j, --json", "Output as JSON", false).description("Update the @hasna/hooks package to the latest version").action(async (options) => {
+  const current = pkg2.version;
+  let pm = "npm";
+  try {
+    const which = Bun.spawnSync(["which", "bun"]);
+    if (which.exitCode === 0)
+      pm = "bun";
+  } catch {}
+  if (options.check) {
+    const proc2 = Bun.spawnSync(["npm", "view", "@hasna/hooks", "version"]);
+    const latest2 = new TextDecoder().decode(proc2.stdout).trim();
+    if (!latest2) {
+      if (options.json) {
+        console.log(JSON.stringify({ error: "Failed to fetch latest version" }));
+      } else {
+        console.log(chalk2.red("Failed to fetch latest version from npm registry."));
+      }
+      process.exit(1);
+    }
+    const upToDate = current === latest2;
+    if (options.json) {
+      console.log(JSON.stringify({ current, latest: latest2, upToDate }));
+    } else if (upToDate) {
+      console.log(chalk2.green(`\u2713 Already on latest version (${current})`));
+    } else {
+      console.log(chalk2.yellow(`Update available: ${current} \u2192 ${latest2}`));
+      console.log(chalk2.dim(`  Run: hooks upgrade`));
+    }
+    return;
+  }
+  const installCmd = pm === "bun" ? ["bun", "install", "-g", "@hasna/hooks@latest"] : ["npm", "install", "-g", "@hasna/hooks@latest"];
+  if (!options.json) {
+    console.log(chalk2.bold(`
+Upgrading @hasna/hooks (${pm})...
+`));
+    console.log(chalk2.dim(`  $ ${installCmd.join(" ")}
+`));
+  }
+  const proc = Bun.spawn(installCmd, {
+    stdout: options.json ? "pipe" : "inherit",
+    stderr: options.json ? "pipe" : "inherit",
+    env: process.env
+  });
+  const exitCode = await proc.exited;
+  if (exitCode !== 0) {
+    if (options.json) {
+      console.log(JSON.stringify({ current, updated: false, error: `${pm} exited with code ${exitCode}` }));
+    } else {
+      console.log(chalk2.red(`
+\u2717 Upgrade failed (exit code ${exitCode})`));
+    }
+    process.exit(exitCode);
+  }
+  const versionProc = Bun.spawnSync(["npm", "view", "@hasna/hooks", "version"]);
+  const latest = new TextDecoder().decode(versionProc.stdout).trim() || "unknown";
+  if (options.json) {
+    console.log(JSON.stringify({ current, latest, updated: true }));
+  } else {
+    console.log(chalk2.green(`
+\u2713 Upgraded: ${current} \u2192 ${latest}`));
+  }
+});
 program2.command("mcp").option("-s, --stdio", "Use stdio transport (for agent MCP integration)", false).option("-p, --port <port>", "Port for SSE transport", "39427").description("Start MCP server for AI agent integration").action(async (options) => {
   if (options.stdio) {
     const { startStdioServer: startStdioServer2 } = await Promise.resolve().then(() => (init_server(), exports_server));