claude-code-hookkit 1.0.0

package/dist/init-RHEFGGUF.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+import {
+  log
+} from "./chunk-2BZZUQQ3.js";
+import {
+  readSettings,
+  writeSettings
+} from "./chunk-LRXKKJDU.js";
+import {
+  createBackup
+} from "./chunk-QKT647BI.js";
+import {
+  getHooksDir,
+  getSettingsPath
+} from "./chunk-PEDGREZY.js";
+
+// src/commands/init.ts
+import { mkdir } from "fs/promises";
+import { existsSync } from "fs";
+import { dirname as pathDirname } from "path";
+async function _initAt(opts) {
+  const { settingsPath, hooksDir, dryRun = false } = opts;
+  const existing = await readSettings(settingsPath);
+  if (existing.hooks !== void 0) {
+    const hookCount = Object.keys(existing.hooks).length;
+    if (hookCount > 0) {
+      log.info(`Already initialized at ${settingsPath}`);
+      return;
+    }
+    if (!dryRun) {
+      await mkdir(hooksDir, { recursive: true });
+    }
+    return;
+  }
+  if (dryRun) {
+    log.dryRun(`Would create directory: ${hooksDir}`);
+    log.dryRun(`Would seed settings.json at: ${settingsPath}`);
+    log.dryRun("Would add empty hooks structure");
+    return;
+  }
+  const hooksDirCreated = !existsSync(hooksDir);
+  await mkdir(hooksDir, { recursive: true });
+  const settingsParent = pathDirname(settingsPath);
+  await mkdir(settingsParent, { recursive: true });
+  const backupPath = await createBackup(settingsPath);
+  const newSettings = { ...existing, hooks: {} };
+  await writeSettings(settingsPath, newSettings);
+  if (hooksDirCreated) {
+    log.success(`Created ${hooksDir}`);
+  }
+  log.success(`Seeded ${settingsPath} with hooks configuration`);
+  if (backupPath) {
+    log.dim(`  Backed up existing settings to ${backupPath}`);
+  }
+}
+async function initCommand(opts) {
+  const validScopes = ["user", "project", "local"];
+  const scope = validScopes.includes(opts.scope) ? opts.scope : "project";
+  const resolvedSettingsPath = getSettingsPath(scope);
+  const resolvedHooksDir = getHooksDir(scope);
+  await _initAt({
+    settingsPath: resolvedSettingsPath,
+    hooksDir: resolvedHooksDir,
+    dryRun: opts.dryRun
+  });
+}
+export {
+  _initAt,
+  initCommand
+};

package/dist/list-SCSGYOBR.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+import {
+  listHooks
+} from "./chunk-XLX5K6TZ.js";
+import {
+  getHooksDir
+} from "./chunk-PEDGREZY.js";
+
+// src/commands/list.ts
+import { existsSync } from "fs";
+import { join } from "path";
+import pc from "picocolors";
+function pad(str, width) {
+  return str.length >= width ? str : str + " ".repeat(width - str.length);
+}
+function stripAnsi(str) {
+  return str.replace(/\x1B\[[0-9;]*m/g, "");
+}
+function padColored(str, width) {
+  const visibleLen = stripAnsi(str).length;
+  const padding = Math.max(0, width - visibleLen);
+  return str + " ".repeat(padding);
+}
+async function _listAt(opts) {
+  const { hooksDir } = opts;
+  const hooks = listHooks();
+  const COL_NAME = 26;
+  const COL_EVENT = 18;
+  const COL_MATCHER = 22;
+  const COL_PACK = 16;
+  const COL_INSTALLED = 9;
+  const header = pad("Name", COL_NAME) + pad("Event", COL_EVENT) + pad("Matcher", COL_MATCHER) + pad("Pack", COL_PACK) + "Installed";
+  console.log(pc.bold(header));
+  console.log(pc.dim("-".repeat(COL_NAME + COL_EVENT + COL_MATCHER + COL_PACK + COL_INSTALLED)));
+  for (const hook of hooks) {
+    const scriptPath = join(hooksDir, hook.scriptFile);
+    const installed = existsSync(scriptPath);
+    const name = padColored(installed ? pc.green(hook.name) : hook.name, COL_NAME);
+    const event = pad(hook.event, COL_EVENT);
+    const matcher = pad(hook.matcher ?? "-", COL_MATCHER);
+    const pack = pad(hook.pack ?? "-", COL_PACK);
+    const installedStr = installed ? pc.green("yes") : pc.dim("no");
+    console.log(name + event + matcher + pack + installedStr);
+  }
+}
+async function listCommand(opts) {
+  const validScopes = ["user", "project", "local"];
+  const scope = validScopes.includes(opts.scope) ? opts.scope : "project";
+  await _listAt({ hooksDir: getHooksDir(scope) });
+}
+export {
+  _listAt,
+  listCommand
+};

package/dist/remove-Z5QIW45P.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+import {
+  log
+} from "./chunk-2BZZUQQ3.js";
+import {
+  readSettings,
+  writeSettings
+} from "./chunk-LRXKKJDU.js";
+import {
+  createBackup
+} from "./chunk-QKT647BI.js";
+import {
+  getHook
+} from "./chunk-XLX5K6TZ.js";
+import {
+  getHooksDir,
+  getSettingsPath
+} from "./chunk-PEDGREZY.js";
+
+// src/commands/remove.ts
+import { unlink, readFile, mkdir } from "fs/promises";
+import { existsSync } from "fs";
+import { join, dirname as pathDirname } from "path";
+function removeHookFromSettings(settings, exactScriptPath) {
+  if (!settings.hooks) {
+    return { settings, removedCount: 0 };
+  }
+  const modified = structuredClone(settings);
+  let removedCount = 0;
+  for (const [event, groups] of Object.entries(modified.hooks)) {
+    const filtered = [];
+    for (const group of groups) {
+      const remainingHooks = group.hooks.filter((h) => {
+        const matches = h.command === exactScriptPath;
+        if (matches) removedCount++;
+        return !matches;
+      });
+      if (remainingHooks.length > 0) {
+        filtered.push({ ...group, hooks: remainingHooks });
+      }
+    }
+    modified.hooks[event] = filtered;
+  }
+  return { settings: modified, removedCount };
+}
+async function _removeAt(opts) {
+  const { settingsPath, hooksDir, hookName, dryRun = false } = opts;
+  const hook = getHook(hookName);
+  if (!hook) {
+    log.error(`Unknown hook: "${hookName}". Run "claude-code-hookkit list" to see available hooks.`);
+    return;
+  }
+  const scriptPath = join(hooksDir, hook.scriptFile);
+  const scriptExists = existsSync(scriptPath);
+  const existing = await readSettings(settingsPath);
+  const { settings: updated, removedCount } = removeHookFromSettings(existing, scriptPath);
+  if (!scriptExists && removedCount === 0) {
+    log.warn(`Hook "${hookName}" is not installed.`);
+    return;
+  }
+  if (dryRun) {
+    if (scriptExists) {
+      log.dryRun(`Would delete: ${scriptPath}`);
+    }
+    if (removedCount > 0) {
+      log.dryRun(`Would remove ${removedCount} settings entr${removedCount === 1 ? "y" : "ies"} from settings.json`);
+    }
+    return;
+  }
+  if (removedCount > 0 && existsSync(settingsPath)) {
+    await createBackup(settingsPath);
+    let originalRaw;
+    try {
+      originalRaw = await readFile(settingsPath, "utf8");
+    } catch {
+      originalRaw = void 0;
+    }
+    const settingsParent = pathDirname(settingsPath);
+    await mkdir(settingsParent, { recursive: true });
+    await writeSettings(settingsPath, updated, originalRaw);
+  }
+  if (scriptExists) {
+    await unlink(scriptPath);
+  }
+  log.success(`Removed hook: ${hookName}`);
+  if (scriptExists) {
+    log.dim(`  Deleted: ${scriptPath}`);
+  }
+  if (removedCount > 0) {
+    log.dim(`  Removed ${removedCount} settings entr${removedCount === 1 ? "y" : "ies"} from settings.json`);
+  }
+  if (!scriptExists && removedCount > 0) {
+    log.dim(`  (Script was already missing \u2014 cleaned up settings entry)`);
+  }
+}
+async function removeCommand(opts) {
+  const validScopes = ["user", "project", "local"];
+  const scope = validScopes.includes(opts.scope) ? opts.scope : "project";
+  await _removeAt({
+    settingsPath: getSettingsPath(scope),
+    hooksDir: getHooksDir(scope),
+    hookName: opts.hookName,
+    dryRun: opts.dryRun
+  });
+}
+export {
+  _removeAt,
+  removeCommand
+};

package/dist/restore-7JQ3CHWZ.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import {
+  log
+} from "./chunk-2BZZUQQ3.js";
+import {
+  restoreBackup
+} from "./chunk-QKT647BI.js";
+import {
+  getSettingsPath
+} from "./chunk-PEDGREZY.js";
+
+// src/commands/restore.ts
+async function restoreCommand(opts) {
+  const scope = opts.scope;
+  const settingsPath = getSettingsPath(scope);
+  const backupPath = settingsPath + ".backup";
+  const success = await restoreBackup(settingsPath);
+  if (success) {
+    log.success(`Restored settings from backup`);
+    log.dim(`  settings: ${settingsPath}`);
+    log.dim(`  restored from: ${backupPath}`);
+    process.exit(0);
+  } else {
+    log.error(`No backup found for scope '${scope}'`);
+    log.dim(`  expected: ${backupPath}`);
+    process.exit(1);
+  }
+}
+export {
+  restoreCommand
+};

package/dist/test-ZRRLZ62R.js

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+import {
+  getHook,
+  listHooks
+} from "./chunk-XLX5K6TZ.js";
+import {
+  getHooksDir
+} from "./chunk-PEDGREZY.js";
+
+// src/commands/test.ts
+import { spawnSync } from "child_process";
+import { readdir, readFile } from "fs/promises";
+import { existsSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, join, resolve } from "path";
+import pc from "picocolors";
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = dirname(__filename);
+function findPackageRoot() {
+  let dir = __dirname;
+  for (let i = 0; i < 5; i++) {
+    if (existsSync(join(dir, "registry", "hooks", "fixtures"))) return dir;
+    const parent = resolve(dir, "..");
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return resolve(__dirname, "..", "..");
+}
+var PACKAGE_ROOT = findPackageRoot();
+var BUNDLED_HOOKS_DIR = join(PACKAGE_ROOT, "registry", "hooks");
+var BUNDLED_FIXTURES_DIR = join(PACKAGE_ROOT, "registry", "hooks", "fixtures");
+async function discoverFixtures(fixtureDir) {
+  if (!existsSync(fixtureDir)) {
+    return [];
+  }
+  let entries;
+  try {
+    entries = await readdir(fixtureDir);
+  } catch {
+    return [];
+  }
+  const fixtures = [];
+  for (const entry of entries) {
+    if (!entry.endsWith(".json")) continue;
+    const filePath = join(fixtureDir, entry);
+    try {
+      const raw = await readFile(filePath, "utf8");
+      const parsed = JSON.parse(raw);
+      fixtures.push(parsed);
+    } catch {
+    }
+  }
+  return fixtures;
+}
+async function runFixture(scriptPath, fixture, opts = {}) {
+  const hookName = opts.hookName ?? "";
+  const input = JSON.stringify(fixture.input);
+  const result = spawnSync("bash", [scriptPath], {
+    input,
+    encoding: "utf8",
+    env: { ...process.env, ...fixture.env ?? {} }
+  });
+  const actualExitCode = result.status ?? -1;
+  const passed = actualExitCode === fixture.expectedExitCode;
+  return {
+    hookName,
+    description: fixture.description,
+    expectedExitCode: fixture.expectedExitCode,
+    actualExitCode,
+    passed,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? ""
+  };
+}
+function resolveBundledScriptPath(scriptFile) {
+  return join(BUNDLED_HOOKS_DIR, scriptFile);
+}
+async function testHook(hookName, scope) {
+  const def = getHook(hookName);
+  const userHooksDir = getHooksDir(scope);
+  let scriptPath;
+  if (def) {
+    scriptPath = resolveBundledScriptPath(def.scriptFile);
+  } else {
+    const userScript = join(userHooksDir, `${hookName}.sh`);
+    if (existsSync(userScript)) {
+      scriptPath = userScript;
+    } else {
+      console.error(pc.red(`Hook not found: ${hookName}`));
+      console.error(pc.dim("  Not in registry and no script at: " + userScript));
+      console.error(pc.dim("  Run `claude-code-hookkit list` to see available hooks"));
+      process.exitCode = 1;
+      return [];
+    }
+  }
+  const bundledFixtureDir = join(BUNDLED_FIXTURES_DIR, hookName);
+  const userFixtureDir = join(userHooksDir, "fixtures", hookName);
+  const bundledFixtures = await discoverFixtures(bundledFixtureDir);
+  const userFixtures = await discoverFixtures(userFixtureDir);
+  const allFixtures = [...bundledFixtures, ...userFixtures];
+  if (allFixtures.length === 0) {
+    console.log(pc.yellow(`  warning`) + `  ${hookName}: no fixtures found`);
+    console.log(pc.dim(`    Add fixtures at: ${userFixtureDir}/*.json`));
+    return [];
+  }
+  const results = [];
+  for (const fixture of allFixtures) {
+    const result = await runFixture(scriptPath, fixture, { hookName });
+    results.push(result);
+    printResult(result);
+  }
+  return results;
+}
+function printResult(result) {
+  if (result.passed) {
+    const label = pc.green("  PASS");
+    const name = pc.bold(result.hookName);
+    console.log(`${label}  ${name}: ${result.description}`);
+  } else {
+    const label = pc.red("  FAIL");
+    const name = pc.bold(result.hookName);
+    const detail = pc.dim(`(expected ${result.expectedExitCode}, got ${result.actualExitCode})`);
+    console.log(`${label}  ${name}: ${result.description} ${detail}`);
+  }
+}
+function printSummary(summary) {
+  const { passed, failed } = summary;
+  const passStr = pc.green(`${passed} passed`);
+  const failStr = failed > 0 ? pc.red(`${failed} failed`) : pc.dim(`${failed} failed`);
+  console.log(`
+${passStr}, ${failStr}`);
+}
+async function testCommand(opts) {
+  const scope = opts.scope ?? "project";
+  const allResults = [];
+  if (opts.all) {
+    const userHooksDir = getHooksDir(scope);
+    const bundledHooks = listHooks();
+    const testedNames = /* @__PURE__ */ new Set();
+    for (const def of bundledHooks) {
+      const installedScript = join(userHooksDir, def.scriptFile);
+      if (existsSync(installedScript)) {
+        console.log(pc.bold(`
+${def.name}`));
+        const results = await testHook(def.name, scope);
+        allResults.push(...results);
+        testedNames.add(def.name);
+      }
+    }
+    const userFixturesRoot = join(userHooksDir, "fixtures");
+    if (existsSync(userFixturesRoot)) {
+      try {
+        const dirs = await readdir(userFixturesRoot, { withFileTypes: true });
+        for (const d of dirs) {
+          if (d.isDirectory() && !testedNames.has(d.name)) {
+            const userScript = join(userHooksDir, `${d.name}.sh`);
+            if (existsSync(userScript)) {
+              console.log(pc.bold(`
+${d.name}`) + pc.dim(" (custom)"));
+              const results = await testHook(d.name, scope);
+              allResults.push(...results);
+            }
+          }
+        }
+      } catch {
+      }
+    }
+    if (testedNames.size === 0 && allResults.length === 0) {
+      console.log(pc.yellow("\nNo installed hooks found. Run `claude-code-hookkit add <hook>` first."));
+    }
+  } else if (opts.hookName) {
+    console.log(pc.bold(`
+${opts.hookName}`));
+    const results = await testHook(opts.hookName, scope);
+    allResults.push(...results);
+  } else {
+    console.error(pc.red("Error: specify a hook name or use --all"));
+    process.exitCode = 1;
+    return { passed: 0, failed: 0, results: [] };
+  }
+  const passed = allResults.filter((r) => r.passed).length;
+  const failed = allResults.filter((r) => !r.passed).length;
+  const summary = { passed, failed, results: allResults };
+  printSummary(summary);
+  if (failed > 0) {
+    process.exitCode = 1;
+  }
+  return summary;
+}
+export {
+  discoverFixtures,
+  runFixture,
+  testCommand
+};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "claude-code-hookkit",
+  "version": "1.0.0",
+  "description": "Hook manager for Claude Code — install, manage, test, and share hooks with a single command",
+  "type": "module",
+  "bin": {
+    "claude-code-hookkit": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "registry"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build && npm run typecheck && npm run test"
+  },
+  "author": "Austin Amelone",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AmeloneGHS/claude-hooks.git"
+  },
+  "homepage": "https://github.com/AmeloneGHS/claude-hooks#readme",
+  "bugs": {
+    "url": "https://github.com/AmeloneGHS/claude-hooks/issues"
+  },
+  "dependencies": {
+    "commander": "^14.0.0",
+    "picocolors": "^1.1.1",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "hooks",
+    "cli",
+    "anthropic",
+    "developer-tools",
+    "automation",
+    "hook-manager",
+    "llm-tools",
+    "ai-safety",
+    "code-quality",
+    "security"
+  ],
+  "license": "MIT"
+}

package/registry/hooks/cost-tracker.sh

@@ -0,0 +1,44 @@
+#!/bin/bash
+# cost-tracker.sh
+# PostToolUse hook (no matcher — runs for all tools)
+#
+# Appends a log entry for every tool call to a per-session log file.
+# This creates a usage audit trail useful for understanding which tools
+# Claude is calling most frequently and estimating session costs.
+#
+# Log file: /tmp/claude-code-hookkit-cost-<session_id>.log
+# Log format: timestamp|tool_name
+#
+# Claude Code passes JSON via stdin. We extract tool_name and session_id.
+#
+# Exit codes:
+#   0  - always allow (this hook never blocks)
+
+INPUT=$(cat)
+
+# Extract session_id from JSON using grep/sed (no jq or python3 required)
+SESSION_ID=$(printf '%s' "$INPUT" | grep -o '"session_id"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/"session_id"[[:space:]]*:[[:space:]]*"\(.*\)"/\1/')
+
+# Extract tool_name from JSON
+TOOL_NAME=$(printf '%s' "$INPUT" | grep -o '"tool_name"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/"tool_name"[[:space:]]*:[[:space:]]*"\(.*\)"/\1/')
+
+# Fallbacks for missing fields
+if [ -z "$SESSION_ID" ]; then
+  SESSION_ID="default"
+fi
+
+if [ -z "$TOOL_NAME" ]; then
+  TOOL_NAME="unknown"
+fi
+
+# Get current UTC timestamp in ISO 8601 format (POSIX date compatible)
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || date +"%Y-%m-%dT%H:%M:%SZ")
+
+# Log file path — unique per session
+LOG_FILE="/tmp/claude-code-hookkit-cost-${SESSION_ID}.log"
+
+# Append log entry: timestamp|tool_name
+printf '%s|%s\n' "$TIMESTAMP" "$TOOL_NAME" >> "$LOG_FILE"
+
+# Always exit 0 — this hook logs, it does not block
+exit 0

package/registry/hooks/error-advisor.sh

@@ -0,0 +1,114 @@
+#!/bin/bash
+# error-advisor.sh
+# PostToolUse hook for Bash events
+#
+# Analyzes the output of failed Bash commands and suggests contextual fixes.
+# When Claude runs a command that fails, this hook examines the error output
+# and prints actionable fix suggestions to stderr.
+#
+# Known error patterns and suggestions:
+#   EADDRINUSE         -> Port already in use
+#   ENOENT             -> File not found
+#   permission denied  -> chmod/ownership issue
+#   MODULE_NOT_FOUND   -> npm install needed
+#   ENOMEM             -> Out of memory
+#   command not found  -> Tool not installed
+#   ECONNREFUSED       -> Service not running
+#   ETIMEDOUT          -> Network timeout
+#   error TS[0-9]{4}   -> TypeScript compilation error
+#
+# Claude Code PostToolUse JSON includes tool_response with command output.
+# JSON is parsed with grep/sed (no jq or python3 required, bash 3.2+ compatible).
+#
+# Exit codes:
+#   0  - always allow (advisory PostToolUse hook)
+
+INPUT=$(cat)
+
+# Extract tool_name to confirm this is a Bash tool call
+TOOL_NAME=$(printf '%s' "$INPUT" | grep -o '"tool_name"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/"tool_name"[[:space:]]*:[[:space:]]*"\(.*\)"/\1/')
+
+# Only provide advice for Bash tool calls
+if [ "$TOOL_NAME" != "Bash" ]; then
+  exit 0
+fi
+
+# Extract tool output / response (where error messages appear)
+# Claude Code PostToolUse includes tool_response as a JSON field
+TOOL_RESPONSE=$(printf '%s' "$INPUT" | grep -o '"tool_response"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/"tool_response"[[:space:]]*:[[:space:]]*"\(.*\)"/\1/')
+
+# Also check stdout/stderr fields
+STDOUT=$(printf '%s' "$INPUT" | grep -o '"stdout"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/"stdout"[[:space:]]*:[[:space:]]*"\(.*\)"/\1/')
+STDERR_VAL=$(printf '%s' "$INPUT" | grep -o '"stderr"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/"stderr"[[:space:]]*:[[:space:]]*"\(.*\)"/\1/')
+
+# Combine all output for pattern matching
+ALL_OUTPUT="${TOOL_RESPONSE} ${STDOUT} ${STDERR_VAL}"
+
+# If no output at all, nothing to advise on
+if [ -z "$(printf '%s' "$ALL_OUTPUT" | tr -d '[:space:]')" ]; then
+  exit 0
+fi
+
+# --- Error pattern detection and advice ---
+# Each pattern uses case-insensitive grep for robustness
+
+# EADDRINUSE: Port already in use
+# Common when starting a dev server when another process holds the port
+if printf '%s' "$ALL_OUTPUT" | grep -qi "EADDRINUSE"; then
+  PORT=$(printf '%s' "$ALL_OUTPUT" | grep -o 'EADDRINUSE.*[0-9][0-9][0-9][0-9]' | grep -o '[0-9][0-9][0-9][0-9]*' | head -1)
+  if [ -n "$PORT" ]; then
+    printf '[error-advisor] Port %s is already in use. Fix:\n  lsof -ti:%s | xargs kill -9\n' "$PORT" "$PORT" >&2
+  else
+    printf '[error-advisor] A port is already in use. Fix:\n  lsof -ti:<port> | xargs kill -9\n' >&2
+  fi
+fi
+
+# ENOENT: No such file or directory
+# Common when referencing a path that doesn't exist yet
+if printf '%s' "$ALL_OUTPUT" | grep -qi "ENOENT\|No such file or directory"; then
+  printf '[error-advisor] File or directory not found. Fix:\n  Check the path exists: ls -la <path>\n  Create missing directories: mkdir -p <dir>\n' >&2
+fi
+
+# Permission denied: file permission issue
+# Common when a script is not executable or user lacks write access
+if printf '%s' "$ALL_OUTPUT" | grep -qi "permission denied\|EACCES"; then
+  printf '[error-advisor] Permission denied. Fix:\n  Make executable: chmod +x <file>\n  Check ownership: ls -la <file>\n' >&2
+fi
+
+# MODULE_NOT_FOUND: Node.js module missing
+# Common after checkout or when dependencies haven't been installed
+if printf '%s' "$ALL_OUTPUT" | grep -qi "MODULE_NOT_FOUND\|Cannot find module"; then
+  printf '[error-advisor] Node.js module not found. Fix:\n  npm install\n  # or: npm ci (for clean installs)\n' >&2
+fi
+
+# ENOMEM: Out of memory
+# Node.js heap exhaustion or system memory pressure
+if printf '%s' "$ALL_OUTPUT" | grep -qi "ENOMEM\|out of memory\|JavaScript heap out of memory"; then
+  printf '[error-advisor] Out of memory. Fix:\n  NODE_OPTIONS="--max-old-space-size=4096" <command>\n  Close other applications to free memory\n' >&2
+fi
+
+# command not found: tool not installed
+# Common when a CLI tool needs to be installed first
+if printf '%s' "$ALL_OUTPUT" | grep -qi "command not found"; then
+  printf '[error-advisor] A required command was not found. Install the missing tool via package manager.\n' >&2
+fi
+
+# ECONNREFUSED: Service not running
+# Common when trying to connect to a server that hasn't started
+if printf '%s' "$ALL_OUTPUT" | grep -qi "ECONNREFUSED\|Connection refused"; then
+  printf '[error-advisor] Connection refused — the target service is not running. Fix:\n  Check if service is running: ps aux | grep <service>\n  Start the service first, then retry\n' >&2
+fi
+
+# ETIMEDOUT: Network timeout
+# Common on slow networks or when a service is unreachable
+if printf '%s' "$ALL_OUTPUT" | grep -qi "ETIMEDOUT\|timed out\|timeout"; then
+  printf '[error-advisor] Network timeout. Fix:\n  Check network connectivity: ping <host>\n  The service may be temporarily unavailable — retry in a moment\n' >&2
+fi
+
+# TypeScript compilation errors
+if printf '%s' "$ALL_OUTPUT" | grep -qi "error TS[0-9]"; then
+  printf '[error-advisor] TypeScript compilation error detected. Fix:\n  Run: npx tsc --noEmit to see all errors\n  Check type annotations and interface definitions\n' >&2
+fi
+
+# Always exit 0 — this hook advises, it does not block
+exit 0