@mcptoolshop/claude-hook-debug 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## 1.0.1 (2026-03-20)
+
+### Added
+
+- CI workflow with vitest coverage + codecov upload
+- Landing page (site-theme) + Starlight handbook (5 pages)
+- Coverage badge in README
+- `--help` and `--version` CLI flags
+- vitest.config.ts scoping coverage to src/
+
+### Fixed
+
+- Exit code logic moved outside format branch so JSON mode also returns exit code 1 on errors
+
+## 1.0.0 (2026-03-19)
+
+### Added
+
+- Settings scanner — reads all 4 Claude Code settings scopes (managed, user, project, local)
+- Plugin state extraction — tracks enabled/disabled state across scopes with merge resolution
+- Hook extraction — maps all user-defined hooks by event type with provenance
+- 8 diagnostic rules detecting known Claude Code bugs:
+  - `GHOST_HOOK_PREVIEW` — disabled claude-preview plugin still fires hooks (#19893)
+  - `GHOST_HOOK_GENERIC` — any disabled plugin with potential ghost hooks
+  - `LOCAL_ONLY_PLUGINS` — enabledPlugins in local-only settings silently dropped (#25086)
+  - `SCOPE_CONFLICT` — plugin enabled/disabled conflict across scopes
+  - `STOP_CONTINUE_LOOP` — Stop hook with continue:true causes infinite loop (#1288)
+  - `DISABLE_ALL_HOOKS_ACTIVE` — disableAllHooks suppresses all hooks including managed
+  - `BROKEN_SETTINGS_JSON` — invalid JSON silently disables all settings from that file
+  - `LARGE_SETTINGS_FILE` — settings file >100KB may cause slow startup
+  - `PLUGIN_HOOKS_INVISIBLE` — no user hooks but plugins enabled
+- CLI with ANSI table and JSON output formats
+- Library API (`debug()` function) for programmatic use
+- 24 tests across 2 test suites

package/README.md

@@ -1,4 +1,16 @@
-# claude-hook-debug
+<p align="center">
+  <a href="https://mcp-tool-shop-org.github.io/claude-hook-debug/">
+    <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/claude-hook-debug/readme.png" width="400" alt="claude-hook-debug" />
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/mcp-tool-shop-org/claude-hook-debug/actions/workflows/ci.yml"><img src="https://github.com/mcp-tool-shop-org/claude-hook-debug/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <a href="https://codecov.io/gh/mcp-tool-shop-org/claude-hook-debug"><img src="https://codecov.io/gh/mcp-tool-shop-org/claude-hook-debug/branch/main/graph/badge.svg" alt="Coverage" /></a>
+  <a href="https://www.npmjs.com/package/@mcptoolshop/claude-hook-debug"><img src="https://img.shields.io/npm/v/@mcptoolshop/claude-hook-debug" alt="npm" /></a>
+  <a href="https://github.com/mcp-tool-shop-org/claude-hook-debug/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License" /></a>
+  <a href="https://mcp-tool-shop-org.github.io/claude-hook-debug/"><img src="https://img.shields.io/badge/Landing_Page-live-blue" alt="Landing Page" /></a>
+</p>
 
 Diagnostic CLI for Claude Code hook issues. Detects ghost hooks from disabled plugins, scope conflicts, misconfigured settings, and known Claude Code bugs.
 
@@ -68,12 +80,15 @@ console.log(report.plugins);
 // [{ pluginId: 'claude-preview@...', mergedEnabled: false, scopes: [...] }]
 ```
 
-## Security
+## Security & Threat Model
 
-- **Read-only.** Reads settings files, never modifies them.
-- **No network.** No API calls, no telemetry, no phone-home.
-- **No secrets.** Does not read or log env var values, API keys, or tokens.
-- **Zero dependencies.** Only Node.js built-ins.
+**What it touches:** Claude Code settings files (`~/.claude/settings.json`, `.claude/settings.json`, `.claude/settings.local.json`, `~/.claude/managed-settings.json`). All reads are read-only — the tool never modifies any file.
+
+**What it does NOT touch:** No API keys, tokens, env var values, or credentials are read or logged. The `env` block in settings is completely ignored. No files outside Claude Code settings paths are accessed.
+
+**Permissions required:** Filesystem read access to `~/.claude/` and the project's `.claude/` directory. No elevated permissions, no network access, no shell execution.
+
+**No telemetry.** No analytics. No phone-home. No data collection of any kind. Zero production dependencies.
 
 ---
 

package/dist/cli.js

@@ -448,6 +448,42 @@ function debug(opts) {
 
 // src/cli.ts
 var args = process.argv.slice(2);
+if (args.includes("--help") || args.includes("-h")) {
+  console.log(`claude-hook-debug \u2014 Diagnostic CLI for Claude Code hook issues
+
+Usage:
+  claude-hook-debug [project-path] [flags]
+
+Flags:
+  --json       Output as JSON (for piping/scripting)
+  --help, -h   Show this help message
+  --version    Show version
+
+Examples:
+  claude-hook-debug                  # Scan current workspace
+  claude-hook-debug /path/to/project # Scan specific project
+  claude-hook-debug --json           # JSON output
+
+Exit codes:
+  0  No errors found
+  1  One or more diagnostic errors detected
+
+Built by MCP Tool Shop \u2014 https://mcp-tool-shop.github.io/`);
+  process.exit(0);
+}
+if (args.includes("--version")) {
+  try {
+    const { readFileSync: readFileSync2 } = await import("fs");
+    const { dirname, join: join2 } = await import("path");
+    const { fileURLToPath } = await import("url");
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    const pkg = JSON.parse(readFileSync2(join2(__dirname, "..", "package.json"), "utf-8"));
+    console.log(pkg.version);
+  } catch {
+    console.log("unknown");
+  }
+  process.exit(0);
+}
 var useJson = args.includes("--json");
 var projectRoot = args.find((a) => !a.startsWith("-"));
 var report = debug({ projectRoot: projectRoot ?? process.cwd() });
@@ -455,6 +491,6 @@ if (useJson) {
   console.log(formatReportJson(report));
 } else {
   console.log(formatReport(report));
-  const hasErrors = report.diagnostics.some((d) => d.severity === "error");
-  process.exit(hasErrors ? 1 : 0);
 }
+var hasErrors = report.diagnostics.some((d) => d.severity === "error");
+process.exit(hasErrors ? 1 : 0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcptoolshop/claude-hook-debug",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Diagnostic CLI for Claude Code hook issues — detects ghost hooks, scope conflicts, and plugin lifecycle bugs",
   "type": "module",
   "main": "./dist/index.js",
@@ -19,13 +19,14 @@
   "files": [
     "dist",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {
     "build": "tsup",
     "test": "vitest run",
     "test:watch": "vitest",
-    "verify": "npm run build && node dist/cli.js",
+    "verify": "npm run build && npm test -- --coverage && node dist/cli.js",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -48,6 +49,7 @@
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^3.2.4",
     "tsup": "^8.0.0",
     "typescript": "^5.4.0",
     "vitest": "^3.0.0"