@hasna/hooks 0.0.1

package/hooks/hook-checkpoint/src/cli.ts

@@ -0,0 +1,191 @@
+#!/usr/bin/env bun
+
+/**
+ * CLI for hook-checkpoint
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import { execSync } from "child_process";
+import { join } from "path";
+import { homedir } from "os";
+
+const HOOK_NAME = "hook-checkpoint";
+const SETTINGS_PATH = join(homedir(), ".claude", "settings.json");
+const CHECKPOINT_DIR = ".claude-checkpoints";
+
+interface ClaudeSettings {
+  hooks?: {
+    PreToolUse?: Array<{
+      matcher: string;
+      hooks: Array<{ type: "command"; command: string }>;
+    }>;
+  };
+  [key: string]: unknown;
+}
+
+function readSettings(): ClaudeSettings {
+  try {
+    if (existsSync(SETTINGS_PATH)) {
+      return JSON.parse(readFileSync(SETTINGS_PATH, "utf-8"));
+    }
+  } catch {}
+  return {};
+}
+
+function writeSettings(settings: ClaudeSettings): void {
+  const dir = join(homedir(), ".claude");
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(SETTINGS_PATH, JSON.stringify(settings, null, 2));
+}
+
+function install(): void {
+  const settings = readSettings();
+  if (!settings.hooks) settings.hooks = {};
+  if (!settings.hooks.PreToolUse) settings.hooks.PreToolUse = [];
+
+  const existing = settings.hooks.PreToolUse.find((h) =>
+    h.hooks.some((hook) => hook.command.includes(HOOK_NAME))
+  );
+
+  if (existing) {
+    console.log(`${HOOK_NAME} is already installed`);
+    return;
+  }
+
+  settings.hooks.PreToolUse.push({
+    matcher: "Write|Edit|NotebookEdit",
+    hooks: [{ type: "command", command: `bunx @hasnaxyz/${HOOK_NAME}` }],
+  });
+
+  writeSettings(settings);
+  console.log(`${HOOK_NAME} installed successfully`);
+  console.log("Hook will create shadow git snapshots before Write/Edit/NotebookEdit");
+}
+
+function uninstall(): void {
+  const settings = readSettings();
+  if (!settings.hooks?.PreToolUse) {
+    console.log(`${HOOK_NAME} is not installed`);
+    return;
+  }
+
+  const before = settings.hooks.PreToolUse.length;
+  settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(
+    (h) => !h.hooks.some((hook) => hook.command.includes(HOOK_NAME))
+  );
+
+  if (before === settings.hooks.PreToolUse.length) {
+    console.log(`${HOOK_NAME} is not installed`);
+    return;
+  }
+
+  writeSettings(settings);
+  console.log(`${HOOK_NAME} uninstalled successfully`);
+}
+
+function status(): void {
+  const settings = readSettings();
+  const installed = settings.hooks?.PreToolUse?.some((h) =>
+    h.hooks.some((hook) => hook.command.includes(HOOK_NAME))
+  );
+  console.log(`${HOOK_NAME} is ${installed ? "installed" : "not installed"}`);
+}
+
+function list(): void {
+  const checkpointDir = join(process.cwd(), CHECKPOINT_DIR);
+  if (!existsSync(checkpointDir)) {
+    console.log("No checkpoints found in current directory");
+    return;
+  }
+
+  try {
+    const log = execSync("git log --oneline -20", {
+      cwd: checkpointDir,
+      encoding: "utf-8",
+    });
+    console.log("Recent checkpoints:");
+    console.log(log);
+  } catch {
+    console.log("No checkpoints found");
+  }
+}
+
+function restore(ref: string): void {
+  const checkpointDir = join(process.cwd(), CHECKPOINT_DIR);
+  if (!existsSync(checkpointDir)) {
+    console.log("No checkpoints found in current directory");
+    return;
+  }
+
+  try {
+    const files = execSync(`git show ${ref} --name-only --pretty=format:""`, {
+      cwd: checkpointDir,
+      encoding: "utf-8",
+    }).trim().split("\n").filter((f) => f.startsWith("files/"));
+
+    for (const file of files) {
+      const relativePath = file.replace("files/", "");
+      try {
+        const content = execSync(`git show ${ref}:${file}`, {
+          cwd: checkpointDir,
+        });
+        const targetPath = join(process.cwd(), relativePath);
+        writeFileSync(targetPath, content);
+        console.log(`Restored: ${relativePath}`);
+      } catch {
+        console.error(`Failed to restore: ${relativePath}`);
+      }
+    }
+  } catch (error) {
+    console.error(`Failed to restore from ${ref}:`, error);
+  }
+}
+
+function help(): void {
+  console.log(`
+${HOOK_NAME} - Shadow git snapshots for Claude Code file modifications
+
+Usage: ${HOOK_NAME} <command>
+
+Commands:
+  install       Install hook to Claude Code settings
+  uninstall     Remove hook from Claude Code settings
+  status        Check if hook is installed
+  list          Show recent checkpoints in current directory
+  restore <ref> Restore files from a checkpoint (git ref)
+  help          Show this help message
+
+How it works:
+  Before any Write/Edit/NotebookEdit, the hook copies the original file
+  into a shadow git repo (.claude-checkpoints/) and commits it. This gives
+  you a full history of every file before Claude modified it.
+`);
+}
+
+const command = process.argv[2];
+
+switch (command) {
+  case "install": install(); break;
+  case "uninstall": uninstall(); break;
+  case "status": status(); break;
+  case "list": list(); break;
+  case "restore":
+    if (process.argv[3]) {
+      restore(process.argv[3]);
+    } else {
+      console.error("Usage: hook-checkpoint restore <git-ref>");
+      process.exit(1);
+    }
+    break;
+  case "help":
+  case "--help":
+  case "-h": help(); break;
+  default:
+    if (!command) {
+      import("./hook.ts").then((m) => m.run());
+    } else {
+      console.error(`Unknown command: ${command}`);
+      help();
+      process.exit(1);
+    }
+}

package/hooks/hook-checkpoint/src/hook.ts

@@ -0,0 +1,207 @@
+#!/usr/bin/env bun
+
+/**
+ * Claude Code Hook: checkpoint
+ *
+ * PreToolUse hook that creates shadow git snapshots before any file
+ * Write/Edit operations. This provides a safety net with easy rollback
+ * capability without cluttering the main project's git history.
+ *
+ * Shadow repo is stored in .claude-checkpoints/ (gitignored).
+ */
+
+import { readFileSync, existsSync, mkdirSync, writeFileSync, appendFileSync } from "fs";
+import { execSync } from "child_process";
+import { join, resolve } from "path";
+
+interface HookInput {
+  session_id: string;
+  cwd: string;
+  tool_name: string;
+  tool_input: Record<string, unknown>;
+}
+
+interface HookOutput {
+  decision?: "approve" | "block";
+  reason?: string;
+}
+
+const CHECKPOINT_DIR = ".claude-checkpoints";
+const TOOLS_TO_CHECKPOINT = ["Write", "Edit", "NotebookEdit"];
+
+/**
+ * Read JSON from stdin
+ */
+function readStdinJson(): HookInput | null {
+  try {
+    const input = readFileSync(0, "utf-8").trim();
+    if (!input) return null;
+    return JSON.parse(input);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Initialize shadow git repo for checkpoints
+ */
+function initShadowRepo(cwd: string): string {
+  const shadowPath = join(cwd, CHECKPOINT_DIR);
+
+  if (!existsSync(shadowPath)) {
+    mkdirSync(shadowPath, { recursive: true });
+  }
+
+  const gitDir = join(shadowPath, ".git");
+  if (!existsSync(gitDir)) {
+    execSync("git init", { cwd: shadowPath, stdio: "pipe" });
+    execSync('git config user.email "hook-checkpoint@claude.local"', {
+      cwd: shadowPath,
+      stdio: "pipe",
+    });
+    execSync('git config user.name "hook-checkpoint"', {
+      cwd: shadowPath,
+      stdio: "pipe",
+    });
+
+    // Create initial commit
+    writeFileSync(join(shadowPath, ".checkpoint-init"), new Date().toISOString());
+    execSync("git add -A && git commit -m 'init: checkpoint repo'", {
+      cwd: shadowPath,
+      stdio: "pipe",
+    });
+  }
+
+  // Ensure .claude-checkpoints is gitignored in main project
+  const mainGitignore = join(cwd, ".gitignore");
+  if (existsSync(mainGitignore)) {
+    const content = readFileSync(mainGitignore, "utf-8");
+    if (!content.includes(CHECKPOINT_DIR)) {
+      appendFileSync(mainGitignore, `\n${CHECKPOINT_DIR}/\n`);
+    }
+  }
+
+  return shadowPath;
+}
+
+/**
+ * Copy the target file into the shadow repo and commit
+ */
+function createCheckpoint(
+  cwd: string,
+  shadowPath: string,
+  toolName: string,
+  filePath: string,
+  sessionId: string
+): void {
+  const absFilePath = resolve(cwd, filePath);
+
+  if (!existsSync(absFilePath)) {
+    // File doesn't exist yet (new file being created) — log but no snapshot needed
+    const logEntry = `[${new Date().toISOString()}] ${toolName} creating new file: ${filePath}\n`;
+    appendFileSync(join(shadowPath, "checkpoint.log"), logEntry);
+    return;
+  }
+
+  // Copy file to shadow repo preserving relative path
+  const relativePath = filePath.startsWith("/")
+    ? filePath.replace(cwd, "").replace(/^\//, "")
+    : filePath;
+  const shadowFilePath = join(shadowPath, "files", relativePath);
+  const shadowFileDir = join(shadowFilePath, "..");
+
+  mkdirSync(shadowFileDir, { recursive: true });
+
+  const content = readFileSync(absFilePath);
+  writeFileSync(shadowFilePath, content);
+
+  // Create metadata
+  const metadata = {
+    tool: toolName,
+    file: filePath,
+    session: sessionId,
+    timestamp: new Date().toISOString(),
+  };
+  writeFileSync(
+    join(shadowPath, "last-checkpoint.json"),
+    JSON.stringify(metadata, null, 2)
+  );
+
+  // Commit to shadow repo
+  try {
+    execSync("git add -A", { cwd: shadowPath, stdio: "pipe" });
+    const msg = `checkpoint: ${toolName} ${relativePath}`;
+    execSync(`git commit -m "${msg}" --allow-empty`, {
+      cwd: shadowPath,
+      stdio: "pipe",
+    });
+  } catch {
+    // Commit may fail if nothing changed — that's fine
+  }
+
+  // Log
+  const logEntry = `[${new Date().toISOString()}] ${toolName} → ${relativePath} (session: ${sessionId})\n`;
+  appendFileSync(join(shadowPath, "checkpoint.log"), logEntry);
+}
+
+/**
+ * Extract file path from tool input
+ */
+function getFilePath(toolName: string, toolInput: Record<string, unknown>): string | null {
+  switch (toolName) {
+    case "Write":
+    case "Edit":
+      return (toolInput.file_path as string) || null;
+    case "NotebookEdit":
+      return (toolInput.notebook_path as string) || null;
+    default:
+      return null;
+  }
+}
+
+/**
+ * Output hook response
+ */
+function respond(output: HookOutput): void {
+  console.log(JSON.stringify(output));
+}
+
+/**
+ * Main hook execution
+ */
+export function run(): void {
+  const input = readStdinJson();
+
+  if (!input) {
+    respond({ decision: "approve" });
+    return;
+  }
+
+  // Only checkpoint file-modifying tools
+  if (!TOOLS_TO_CHECKPOINT.includes(input.tool_name)) {
+    respond({ decision: "approve" });
+    return;
+  }
+
+  const filePath = getFilePath(input.tool_name, input.tool_input);
+  if (!filePath) {
+    respond({ decision: "approve" });
+    return;
+  }
+
+  try {
+    const shadowPath = initShadowRepo(input.cwd);
+    createCheckpoint(input.cwd, shadowPath, input.tool_name, filePath, input.session_id);
+  } catch (error) {
+    // Never block operations due to checkpoint failures
+    const errMsg = error instanceof Error ? error.message : String(error);
+    console.error(`[hook-checkpoint] Warning: checkpoint failed: ${errMsg}`);
+  }
+
+  // Always approve — checkpointing is non-blocking
+  respond({ decision: "approve" });
+}
+
+if (import.meta.main) {
+  run();
+}

package/hooks/hook-checkpoint/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "lib": ["ESNext"],
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["bun-types"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/hooks/hook-checksecurity/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Hasna
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/hooks/hook-checksecurity/README.md

@@ -0,0 +1,158 @@
+# @hasnaxyz/hook-checksecurity
+
+Claude Code hook that runs security checks via Claude and Codex headless agents. This is a **blocker** hook on the Stop event.
+
+## Features
+
+- **Stop event blocker**: Runs before session ends
+- **Dual agent review**: Spawns both Claude and Codex for thorough coverage
+- **Task dispatch**: Creates security tasks via `service-implementation task dispatch`
+- **Repo pattern check**: Only runs for repos matching `[prefix]-[name]` pattern
+- **One-time per session**: Only runs once (state flag prevents re-runs)
+- **Session-aware**: Only runs for sessions matching configured keywords
+
+## Installation
+
+### Global CLI
+
+```bash
+bun add -g @hasnaxyz/hook-checksecurity
+hook-checksecurity install --global
+```
+
+### Project-specific
+
+```bash
+cd /path/to/your/project
+bunx @hasnaxyz/hook-checksecurity install
+```
+
+## Requirements
+
+- `claude` CLI (for headless agent)
+- `codex` CLI (optional, for additional security review)
+- `service-implementation` CLI (for task dispatch)
+
+## Usage
+
+Once installed, the hook runs automatically on the Stop event.
+
+### Commands
+
+```bash
+hook-checksecurity install [path]     # Install the hook
+hook-checksecurity config [path]      # Update configuration
+hook-checksecurity uninstall [path]   # Remove the hook
+hook-checksecurity status             # Show hook status
+hook-checksecurity run                # Execute hook (called by Claude Code)
+```
+
+### Options
+
+- `--global`, `-g`: Apply to global settings (`~/.claude/settings.json`)
+- `/path/to/repo`: Apply to specific project path
+
+## Configuration
+
+Configuration is stored in `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "Stop": [{
+      "hooks": [
+        {
+          "type": "command",
+          "command": "bunx @hasnaxyz/hook-checksecurity@latest run",
+          "timeout": 300
+        },
+        {
+          "type": "command",
+          "command": "bunx @hasnaxyz/hook-checktasks@latest run"
+        }
+      ]
+    }]
+  },
+  "checkSecurityConfig": {
+    "taskListId": "myproject-dev",
+    "keywords": ["dev"],
+    "enabled": true
+  }
+}
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `taskListId` | string | auto | Task list for dispatching security tasks |
+| `keywords` | string[] | ["dev"] | Only run for matching sessions |
+| `enabled` | boolean | true | Enable/disable the hook |
+
+## How It Works
+
+1. **Stop event triggers**: When user tries to end session
+2. **Validates repo pattern**: Only runs for `[prefix]-[name]` folders
+3. **Checks session state**: Skips if already ran this session
+4. **Runs Claude security check**: Headless agent scans for vulnerabilities
+5. **Runs Codex security check**: Additional headless agent review
+6. **Creates tasks**: Both agents dispatch tasks via `service-implementation`
+7. **hook-checktasks blocks**: If tasks exist, session is blocked
+
+## Security Issues Detected
+
+The hook checks for:
+
+- Injection vulnerabilities (SQL, XSS, command injection)
+- Authentication/authorization issues
+- Sensitive data exposure
+- Insecure configurations
+- Dependency vulnerabilities
+- Hardcoded secrets or credentials
+- Input validation issues
+- CSRF vulnerabilities
+- Insecure deserialization
+
+## Task Format
+
+Tasks are dispatched with:
+
+```bash
+service-implementation task dispatch "myproject-dev" \
+  -s "SECURITY: [severity] - [brief description]" \
+  -d "[detailed description with file:line reference and remediation]"
+```
+
+Severity levels: CRITICAL, HIGH, MEDIUM, LOW
+
+## Session State
+
+State is persisted in `~/.claude/hook-state/checksecurity-{session_id}.json`:
+
+```json
+{
+  "securityChecked": true,
+  "lastCheckRun": 1706500000000
+}
+```
+
+## Hook Ordering
+
+For proper operation, checksecurity should run **before** checktasks:
+
+```json
+{
+  "hooks": {
+    "Stop": [{
+      "hooks": [
+        { "command": "bunx @hasnaxyz/hook-checksecurity@latest run" },
+        { "command": "bunx @hasnaxyz/hook-checktasks@latest run" }
+      ]
+    }]
+  }
+}
+```
+
+## License
+
+MIT

package/hooks/hook-checksecurity/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@hasnaxyz/hook-checksecurity",
+  "version": "0.1.4",
+  "description": "Claude Code hook that runs security checks via Claude and Codex headless agents",
+  "type": "module",
+  "bin": {
+    "hook-checksecurity": "./dist/cli.js"
+  },
+  "main": "./dist/hook.js",
+  "exports": {
+    ".": {
+      "import": "./dist/hook.js",
+      "types": "./dist/hook.d.ts"
+    },
+    "./cli": {
+      "import": "./dist/cli.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bun build ./src/cli.ts ./src/hook.ts --outdir ./dist --target node",
+    "prepublishOnly": "bun run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "claude-code",
+    "claude",
+    "codex",
+    "hook",
+    "security",
+    "headless",
+    "automation",
+    "cli"
+  ],
+  "author": "Hasna",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hasnaxyz/hook-checksecurity.git"
+  },
+  "publishConfig": {
+    "access": "restricted",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=18",
+    "bun": ">=1.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.8",
+    "@types/node": "^20",
+    "typescript": "^5.0.0"
+  }
+}