@cmds-cc/hooks 1.0.0

package/README.md

@@ -0,0 +1,102 @@
+# @cmds-cc/hooks
+
+Install Claude Code hooks from any GitHub repo.
+
+**Docs:** [cmds.cc/hooks](https://cmds.cc/hooks)
+
+```bash
+npx @cmds-cc/hooks add sieteunoseis/spok-api
+```
+
+## How it works
+
+1. Fetches `claude-hooks.json` from the target repo
+2. Shows an interactive prompt to select which hooks to install
+3. Merges selected hooks into `~/.claude/settings.json`
+
+## Install from hook collections
+
+```bash
+# Essential safety guardrails
+npx @cmds-cc/hooks add sieteunoseis/hooks.automate.builders/hooks/safety-essentials
+
+# Cloud protection (AWS, GCP, Azure)
+npx @cmds-cc/hooks add sieteunoseis/hooks.automate.builders/hooks/cloud-safety
+
+# Kubernetes safety
+npx @cmds-cc/hooks add sieteunoseis/hooks.automate.builders/hooks/kubernetes-safety
+
+# Cisco UC CLI protection
+npx @cmds-cc/hooks add sieteunoseis/hooks.automate.builders/hooks/cisco-cli-safety
+```
+
+Browse all collections at [cmds.cc/hooks](https://cmds.cc/hooks).
+
+## Install from any repo
+
+Any GitHub repo with a `claude-hooks.json` at root is installable:
+
+```bash
+npx @cmds-cc/hooks add owner/repo
+```
+
+Subdirectories work too:
+
+```bash
+npx @cmds-cc/hooks add owner/repo/path/to/hooks
+```
+
+## For CLI authors
+
+Add a `claude-hooks.json` to your repo root:
+
+```json
+{
+  "name": "my-tool",
+  "description": "Hooks for my CLI tool",
+  "author": "your-username",
+  "version": "1.0.0",
+  "hooks": [
+    {
+      "name": "Block write operations",
+      "description": "Prevents write commands without approval",
+      "default": true,
+      "event": "PreToolUse",
+      "matcher": "Bash",
+      "hook": {
+        "type": "command",
+        "command": "your hook command here"
+      }
+    }
+  ]
+}
+```
+
+See the [docs](https://cmds.cc/hooks/docs) for the full authoring guide.
+
+## Telemetry
+
+After a successful install, the CLI registers the repo in the [directory](https://cmds.cc/hooks) so others can discover it. Only the repo name is sent — no personal data.
+
+Opt out:
+
+```bash
+npx @cmds-cc/hooks add owner/repo --no-telemetry
+CC_HOOKS_NO_TELEMETRY=1 npx @cmds-cc/hooks add owner/repo
+```
+
+## Migrating from cc-hooks-install
+
+This package replaces `cc-hooks-install`. Same code, new name:
+
+```bash
+# Old
+npx cc-hooks-install add owner/repo
+
+# New
+npx @cmds-cc/hooks add owner/repo
+```
+
+## License
+
+MIT

package/bin/cc-hooks.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+
+import { program } from "commander";
+import { fetchHooks } from "../lib/fetch.js";
+import { selectHooks } from "../lib/prompt.js";
+import { mergeHooks } from "../lib/merge.js";
+
+program
+  .name("cmds-hooks")
+  .description("Install Claude Code hooks from any GitHub repo — cmds.cc/hooks")
+  .version("1.0.0");
+
+program
+  .command("add")
+  .argument("<repo>", "GitHub repo (owner/repo)")
+  .option("--no-telemetry", "Don't register this install in the directory")
+  .description("Install hooks from a GitHub repository")
+  .action(async (repo, opts) => {
+    try {
+      const manifest = await fetchHooks(repo);
+      const selected = await selectHooks(manifest);
+      const result = await mergeHooks(selected, manifest, repo, {
+        noTelemetry: opts.telemetry === false,
+      });
+
+      console.log();
+      console.log(`  ✓ ${result.added} hook(s) installed to ${result.path}`);
+      if (result.skipped > 0) {
+        console.log(
+          `  ⊘ ${result.skipped} hook(s) skipped (already installed)`,
+        );
+      }
+      console.log();
+    } catch (err) {
+      console.error(`\n  ✗ ${err.message}\n`);
+      process.exit(1);
+    }
+  });
+
+program.parse();

package/examples/spok-api.json

@@ -0,0 +1,30 @@
+{
+  "name": "spok-api",
+  "description": "Hooks for Spok SmartSuite CLI",
+  "author": "sieteunoseis",
+  "version": "1.0.0",
+  "hooks": [
+    {
+      "name": "Block write operations",
+      "description": "Blocks send-page, change-status, add, update, delete, assign, set, datafeed",
+      "default": true,
+      "event": "PreToolUse",
+      "matcher": "Bash",
+      "hook": {
+        "type": "command",
+        "command": "jq -r '.tool_input.command' | { read -r cmd; if echo \"$cmd\" | grep -qE '^(npx )?spok-api (send-page|change-status|add |update |delete |assign |set |datafeed )'; then echo '{\"decision\":\"block\",\"reason\":\"BLOCKED: spok-api write operation. Get explicit user approval.\"}'; fi; }"
+      }
+    },
+    {
+      "name": "Enforce --read-only flag",
+      "description": "Requires --read-only on every spok-api command",
+      "default": false,
+      "event": "PreToolUse",
+      "matcher": "Bash",
+      "hook": {
+        "type": "command",
+        "command": "jq -r '.tool_input.command' | { read -r cmd; if echo \"$cmd\" | grep -qE '^(npx )?spok-api ' && ! echo \"$cmd\" | grep -q '\\-\\-read-only'; then echo '{\"decision\":\"block\",\"reason\":\"BLOCKED: spok-api must be run with --read-only. Retry with the flag.\"}'; fi; }"
+      }
+    }
+  ]
+}

package/lib/fetch.js

@@ -0,0 +1,42 @@
+export async function fetchHooks(repo) {
+  const parts = repo.split("/");
+  if (parts.length < 2) {
+    throw new Error(
+      `Invalid repo format: "${repo}". Expected owner/repo or owner/repo/path`,
+    );
+  }
+
+  const owner = parts[0];
+  const name = parts[1];
+  const subpath = parts.length > 2 ? parts.slice(2).join("/") + "/" : "";
+
+  const url = `https://raw.githubusercontent.com/${owner}/${name}/HEAD/${subpath}claude-hooks.json`;
+  const res = await fetch(url, {
+    headers: { "User-Agent": "cc-hooks-install" },
+  });
+
+  if (res.status === 404) {
+    throw new Error(`No claude-hooks.json found in ${repo}`);
+  }
+  if (!res.ok) {
+    throw new Error(`GitHub error (${res.status}): ${res.statusText}`);
+  }
+
+  const data = await res.json();
+
+  if (!data.name || !Array.isArray(data.hooks) || data.hooks.length === 0) {
+    throw new Error(
+      `Invalid claude-hooks.json in ${repo}: missing name or hooks array`,
+    );
+  }
+
+  for (const hook of data.hooks) {
+    if (!hook.name || !hook.event || !hook.matcher || !hook.hook) {
+      throw new Error(
+        `Invalid hook entry "${hook.name || "unnamed"}": missing required fields (name, event, matcher, hook)`,
+      );
+    }
+  }
+
+  return data;
+}

package/lib/merge.js

@@ -0,0 +1,67 @@
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const SETTINGS_PATH = join(homedir(), ".claude", "settings.json");
+
+export async function mergeHooks(selected, manifest, repo, options) {
+  let settings;
+  try {
+    const raw = await readFile(SETTINGS_PATH, "utf8");
+    settings = JSON.parse(raw);
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      await mkdir(join(homedir(), ".claude"), { recursive: true });
+      settings = {};
+    } else {
+      throw new Error(`Failed to read ${SETTINGS_PATH}: ${err.message}`);
+    }
+  }
+
+  if (!settings.hooks) {
+    settings.hooks = {};
+  }
+
+  let added = 0;
+  let skipped = 0;
+
+  for (const hook of selected) {
+    const event = hook.event;
+    if (!settings.hooks[event]) {
+      settings.hooks[event] = [];
+    }
+
+    let matcherGroup = settings.hooks[event].find(
+      (g) => g.matcher === hook.matcher,
+    );
+    if (!matcherGroup) {
+      matcherGroup = { matcher: hook.matcher, hooks: [] };
+      settings.hooks[event].push(matcherGroup);
+    }
+
+    const cmd = hook.hook.command;
+    const isDuplicate = matcherGroup.hooks.some((h) => h.command === cmd);
+    if (isDuplicate) {
+      skipped++;
+      continue;
+    }
+
+    matcherGroup.hooks.push(hook.hook);
+    added++;
+  }
+
+  await writeFile(SETTINGS_PATH, JSON.stringify(settings, null, 2) + "\n");
+
+  // Fire-and-forget registration — never blocks the user
+  const noTelemetry =
+    options?.noTelemetry || process.env.CC_HOOKS_NO_TELEMETRY === "1";
+  if (repo && added > 0 && !noTelemetry) {
+    fetch("https://hooks.automate.builders/api/register", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ repo }),
+    }).catch(() => {});
+  }
+
+  return { added, skipped, path: SETTINGS_PATH };
+}

package/lib/prompt.js

@@ -0,0 +1,37 @@
+import { checkbox } from "@inquirer/prompts";
+
+const BANNER = `
+  ██╗  ██╗ ██████╗  ██████╗ ██╗  ██╗███████╗
+  ██║  ██║██╔═══██╗██╔═══██╗██║ ██╔╝██╔════╝
+  ███████║██║   ██║██║   ██║█████╔╝ ███████╗
+  ██╔══██║██║   ██║██║   ██║██╔═██╗ ╚════██║
+  ██║  ██║╚██████╔╝╚██████╔╝██║  ██╗███████║
+  ╚═╝  ╚═╝ ╚═════╝  ╚═════╝ ╚═╝  ╚═╝╚══════╝`;
+
+export async function selectHooks(manifest) {
+  console.log(BANNER);
+  console.log();
+  console.log(`  📦 ${manifest.name} v${manifest.version}`);
+  console.log(`  ${manifest.description}`);
+  console.log();
+
+  const choices = manifest.hooks.map((hook) => ({
+    name: `${hook.name} (${hook.event} → ${hook.matcher})`,
+    value: hook,
+    checked: hook.default !== false,
+    description: hook.description,
+  }));
+
+  const selected = await checkbox({
+    message: "Select hooks to install",
+    choices,
+    instructions: false,
+  });
+
+  if (selected.length === 0) {
+    console.log("  No hooks selected. Nothing to install.");
+    process.exit(0);
+  }
+
+  return selected;
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@cmds-cc/hooks",
+  "version": "1.0.0",
+  "description": "Install Claude Code hooks from any GitHub repo",
+  "license": "MIT",
+  "author": "Jeremy Worden",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cmds-cc/hooks"
+  },
+  "homepage": "https://cmds.cc/hooks",
+  "bin": {
+    "cmds-hooks": "./bin/cc-hooks.js"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "claude-code",
+    "hooks",
+    "cli",
+    "safety",
+    "guardrails",
+    "ai-agents",
+    "cmds-cc"
+  ],
+  "files": [
+    "bin",
+    "lib",
+    "examples"
+  ],
+  "dependencies": {
+    "commander": "^14.0.0",
+    "@inquirer/prompts": "^7.0.0"
+  }
+}