@hasna/hooks 0.0.1

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

@@ -0,0 +1,321 @@
+#!/usr/bin/env bun
+
+/**
+ * Claude Code Hook: check-files
+ *
+ * Runs a headless Claude Code agent to review files and create tasks.
+ * Uses service-implementation CLI to dispatch tasks.
+ *
+ * This hook runs ASYNC (non-blocking) on PostToolUse.
+ *
+ * Configuration:
+ * - taskListId: task list for dispatching review tasks
+ * - editThreshold: run review after this many edits (default: 3, range: 3-7)
+ * - keywords: keywords that trigger the check (default: ["dev"])
+ * - reviewPrompt: custom prompt for the headless agent
+ * - enabled: enable/disable the hook
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import { spawn } from "child_process";
+
+interface CheckFilesConfig {
+  taskListId?: string;
+  editThreshold?: number;
+  keywords?: string[];
+  reviewPrompt?: string;
+  enabled?: boolean;
+}
+
+interface HookInput {
+  session_id: string;
+  transcript_path: string;
+  cwd: string;
+  tool_name: string;
+  tool_input: Record<string, unknown>;
+  tool_output?: string;
+}
+
+interface SessionState {
+  editCount: number;
+  editedFiles: string[];
+  lastReviewRun: number;
+  reviewInProgress: boolean;
+}
+
+const CONFIG_KEY = "checkFilesConfig";
+const STATE_DIR = join(homedir(), ".claude", "hook-state");
+const EDIT_TOOLS = ["Edit", "Write", "NotebookEdit"];
+
+/**
+ * Sanitize ID to prevent path traversal and injection attacks
+ */
+function sanitizeId(id: string): string {
+  if (!id || typeof id !== 'string') return 'default';
+  return id.replace(/[^a-zA-Z0-9_-]/g, '-').slice(0, 100) || 'default';
+}
+
+/**
+ * Sanitize file path for safe display in prompts
+ */
+function sanitizePath(path: string): string {
+  if (!path || typeof path !== 'string') return '';
+  return path.replace(/[`$"'\\;&|<>(){}[\]!#*?~]/g, '_');
+}
+
+const DEFAULT_REVIEW_PROMPT = `You are a code reviewer. Review the following files that were recently edited and identify any issues:
+
+FILES TO REVIEW:
+{files}
+
+For each issue found, create a task using the service-implementation CLI:
+service-implementation task dispatch "{taskListId}" -s "REVIEW: [brief issue description]" -d "[detailed description with file:line reference]"
+
+Focus on:
+- Potential bugs or logic errors
+- Security vulnerabilities
+- Performance issues
+- Code style violations
+- Missing error handling
+
+If no issues are found, do not create any tasks.
+Only create tasks for real issues, not minor style preferences.
+Limit to max 5 most important issues.`;
+
+function readStdinJson(): HookInput | null {
+  try {
+    const stdin = readFileSync(0, "utf-8");
+    return JSON.parse(stdin);
+  } catch {
+    return null;
+  }
+}
+
+function readSettings(path: string): Record<string, unknown> {
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+
+function getConfig(cwd: string): CheckFilesConfig {
+  // Try project settings first
+  const projectSettings = readSettings(join(cwd, ".claude", "settings.json"));
+  if (projectSettings[CONFIG_KEY]) {
+    return projectSettings[CONFIG_KEY] as CheckFilesConfig;
+  }
+
+  // Fall back to global settings
+  const globalSettings = readSettings(join(homedir(), ".claude", "settings.json"));
+  if (globalSettings[CONFIG_KEY]) {
+    return globalSettings[CONFIG_KEY] as CheckFilesConfig;
+  }
+
+  // Default config
+  return {
+    editThreshold: 3,
+    keywords: ["dev"],
+    enabled: true,
+  };
+}
+
+function getStateFile(sessionId: string): string {
+  mkdirSync(STATE_DIR, { recursive: true });
+  const safeSessionId = sanitizeId(sessionId);
+  return join(STATE_DIR, `checkfiles-${safeSessionId}.json`);
+}
+
+function getSessionState(sessionId: string): SessionState {
+  const stateFile = getStateFile(sessionId);
+  if (existsSync(stateFile)) {
+    try {
+      return JSON.parse(readFileSync(stateFile, "utf-8"));
+    } catch {
+      // Corrupted state, reset
+    }
+  }
+  return { editCount: 0, editedFiles: [], lastReviewRun: 0, reviewInProgress: false };
+}
+
+function saveSessionState(sessionId: string, state: SessionState): void {
+  const stateFile = getStateFile(sessionId);
+  writeFileSync(stateFile, JSON.stringify(state, null, 2));
+}
+
+function getSessionName(transcriptPath: string): string | null {
+  if (!existsSync(transcriptPath)) return null;
+
+  try {
+    const content = readFileSync(transcriptPath, "utf-8");
+    let lastTitle: string | null = null;
+    let searchStart = 0;
+
+    while (true) {
+      const titleIndex = content.indexOf('"custom-title"', searchStart);
+      if (titleIndex === -1) break;
+
+      const lineStart = content.lastIndexOf("\n", titleIndex) + 1;
+      const lineEnd = content.indexOf("\n", titleIndex);
+      const line = content.slice(lineStart, lineEnd === -1 ? undefined : lineEnd);
+
+      try {
+        const entry = JSON.parse(line);
+        if (entry.type === "custom-title" && entry.customTitle) {
+          lastTitle = entry.customTitle;
+        }
+      } catch {
+        // Skip malformed lines
+      }
+
+      searchStart = titleIndex + 1;
+    }
+
+    return lastTitle;
+  } catch {
+    return null;
+  }
+}
+
+function getProjectTaskListId(cwd: string): string | null {
+  const dirName = cwd.split("/").filter(Boolean).pop() || "";
+  // Default to project-bugfixes or project-dev
+  return `${dirName}-bugfixes`;
+}
+
+function runHeadlessReview(
+  cwd: string,
+  files: string[],
+  taskListId: string,
+  customPrompt?: string
+): void {
+  // Sanitize file paths to prevent prompt injection
+  const filesFormatted = files.map((f) => `- ${sanitizePath(f)}`).join("\n");
+  // Sanitize taskListId
+  const safeTaskListId = sanitizeId(taskListId);
+
+  const prompt = (customPrompt || DEFAULT_REVIEW_PROMPT)
+    .replace("{files}", filesFormatted)
+    .replace("{taskListId}", safeTaskListId);
+
+  // Spawn headless Claude Code agent in background
+  const child = spawn(
+    "claude",
+    [
+      "-p",
+      prompt,
+      "--permission-mode",
+      "acceptEdits",
+      "--allowedTools",
+      "Bash,Read",
+      "--no-session-persistence",
+    ],
+    {
+      cwd,
+      detached: true,
+      stdio: "ignore",
+    }
+  );
+
+  // Detach from parent process
+  child.unref();
+
+  console.error(`[hook-checkfiles] Started headless review of ${files.length} files`);
+}
+
+function approve() {
+  console.log(JSON.stringify({ decision: "approve" }));
+  process.exit(0);
+}
+
+export function run() {
+  const hookInput = readStdinJson();
+  if (!hookInput) {
+    approve();
+    return;
+  }
+
+  const { session_id, cwd, tool_name, tool_input, transcript_path } = hookInput;
+
+  // Only process edit tools
+  if (!EDIT_TOOLS.includes(tool_name)) {
+    approve();
+    return;
+  }
+
+  const config = getConfig(cwd);
+
+  // Check if hook is disabled
+  if (config.enabled === false) {
+    approve();
+    return;
+  }
+
+  // Check keywords match
+  const sessionName = transcript_path ? getSessionName(transcript_path) : null;
+  const nameToCheck = sessionName || config.taskListId || "";
+  const keywords = config.keywords || ["dev"];
+
+  const matchesKeyword = keywords.some((keyword) =>
+    nameToCheck.toLowerCase().includes(keyword.toLowerCase())
+  );
+
+  // If keywords are configured and we have a session name, check for match
+  if (keywords.length > 0 && nameToCheck && !matchesKeyword) {
+    approve();
+    return;
+  }
+
+  // Get edited file path
+  const filePath = (tool_input.file_path || tool_input.notebook_path) as string | undefined;
+  if (!filePath) {
+    approve();
+    return;
+  }
+
+  // Update session state
+  const state = getSessionState(session_id);
+
+  // Skip if review already in progress
+  if (state.reviewInProgress) {
+    approve();
+    return;
+  }
+
+  state.editCount++;
+
+  if (!state.editedFiles.includes(filePath)) {
+    state.editedFiles.push(filePath);
+  }
+
+  const threshold = Math.min(7, Math.max(3, config.editThreshold || 3));
+
+  // Check if we should run review
+  if (state.editCount >= threshold) {
+    const taskListId = config.taskListId || getProjectTaskListId(cwd) || "default-bugfixes";
+
+    // Mark review in progress
+    state.reviewInProgress = true;
+    saveSessionState(session_id, state);
+
+    // Run headless review (async, non-blocking)
+    runHeadlessReview(cwd, state.editedFiles, taskListId, config.reviewPrompt);
+
+    // Reset counter after starting review
+    state.editCount = 0;
+    state.editedFiles = [];
+    state.lastReviewRun = Date.now();
+    state.reviewInProgress = false;
+  }
+
+  saveSessionState(session_id, state);
+  approve();
+}
+
+// Allow direct execution
+if (import.meta.main) {
+  run();
+}

package/hooks/hook-checkfiles/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "./dist",
+    "declaration": true,
+    "declarationMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/hooks/hook-checklint/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-checklint/README.md

@@ -0,0 +1,147 @@
+# @hasnaxyz/hook-checklint
+
+Claude Code hook that runs linting after file edits and creates tasks for errors.
+
+## Features
+
+- **Automatic lint checking**: Runs lint after every N file edits (configurable, default: 3)
+- **Task creation**: Creates bug tasks for lint errors so AI can fix them
+- **Auto-detection**: Detects lint command and task lists automatically
+- **Session-aware**: Only runs for sessions matching configured keywords
+- **Multiple linters**: Supports ESLint, Biome, and custom lint commands
+
+## Installation
+
+### Global CLI
+
+```bash
+bun add -g @hasnaxyz/hook-checklint
+hook-checklint install --global
+```
+
+### Project-specific
+
+```bash
+cd /path/to/your/project
+bunx @hasnaxyz/hook-checklint install
+```
+
+## Usage
+
+Once installed, the hook runs automatically after file edits (Edit, Write, NotebookEdit tools).
+
+### Commands
+
+```bash
+hook-checklint install [path]     # Install the hook
+hook-checklint config [path]      # Update configuration
+hook-checklint uninstall [path]   # Remove the hook
+hook-checklint status             # Show hook status
+hook-checklint 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": {
+    "PostToolUse": [{
+      "matcher": {
+        "tool_name": "^(Edit|Write|NotebookEdit)$"
+      },
+      "hooks": [{
+        "type": "command",
+        "command": "bunx @hasnaxyz/hook-checklint@latest run",
+        "timeout": 120
+      }]
+    }]
+  },
+  "checkLintConfig": {
+    "editThreshold": 3,
+    "lintCommand": "bun lint",
+    "taskListId": "myproject-bugfixes",
+    "keywords": ["dev"],
+    "createTasks": true,
+    "enabled": true
+  }
+}
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `editThreshold` | number | 3 | Run lint after this many edits (3-7) |
+| `lintCommand` | string | auto | Lint command to run |
+| `taskListId` | string | auto | Task list for error tasks |
+| `keywords` | string[] | ["dev"] | Only run for matching sessions |
+| `createTasks` | boolean | true | Create tasks for lint errors |
+| `enabled` | boolean | true | Enable/disable the hook |
+
+## How It Works
+
+1. **Tracks file edits**: Monitors Edit, Write, and NotebookEdit tool calls
+2. **Counts edits**: Maintains a per-session edit counter
+3. **Triggers lint**: After N edits, runs the configured lint command
+4. **Parses output**: Extracts errors from ESLint/Biome output
+5. **Creates tasks**: For each error, creates a bug task in the configured task list
+6. **Resets counter**: After lint run, resets the edit counter
+
+## Auto-Detection
+
+### Lint Command
+
+The hook auto-detects the lint command by checking:
+
+1. `package.json` scripts: `lint`, `lint:check`, `eslint`, `biome`
+2. Config files: `biome.json`, `.eslintrc.json`, `eslint.config.js`
+
+### Task List
+
+The hook auto-detects the task list by:
+
+1. Looking for `{project}-bugfixes` list
+2. Falling back to `{project}-dev` list
+
+## Task Format
+
+Created tasks follow this format:
+
+```
+Subject: BUG: MEDIUM - Fix lint error in src/file.ts:42
+Description:
+  Fix lint error at src/file.ts:42:5
+
+  **Error:** Unexpected console statement
+  **Rule:** no-console
+  **File:** src/file.ts
+  **Line:** 42
+  **Column:** 5
+
+  **Acceptance criteria:**
+  - Lint error is fixed
+  - No new lint errors introduced
+```
+
+## Session State
+
+The hook maintains session state in `~/.claude/hook-state/checklint-{session_id}.json`:
+
+```json
+{
+  "editCount": 2,
+  "editedFiles": ["src/file.ts", "src/other.ts"],
+  "lastLintRun": 1706500000000
+}
+```
+
+## License
+
+MIT

package/hooks/hook-checklint/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@hasnaxyz/hook-checklint",
+  "version": "0.1.7",
+  "description": "Claude Code hook that runs linting after file edits and creates tasks for errors",
+  "type": "module",
+  "bin": {
+    "hook-checklint": "./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",
+    "hook",
+    "lint",
+    "eslint",
+    "biome",
+    "automation",
+    "cli"
+  ],
+  "author": "Hasna",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hasnaxyz/hook-checklint.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"
+  }
+}

package/hooks/hook-checklint/src/cli-patch.ts

@@ -0,0 +1,32 @@
+interface InstallOptions {
+  global?: boolean;
+  taskListId?: string;
+  keywords?: string[];
+  editThreshold?: number;
+  yes?: boolean;
+  path?: string;
+}
+
+function parseInstallArgs(args: string[]): InstallOptions {
+  const options: InstallOptions = {};
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === "--global" || arg === "-g") {
+      options.global = true;
+    } else if (arg === "--yes" || arg === "-y") {
+      options.yes = true;
+    } else if (arg === "--task-list-id" || arg === "-t") {
+      options.taskListId = args[++i];
+    } else if (arg === "--keywords" || arg === "-k") {
+      options.keywords = args[++i]?.split(",").map(k => k.trim().toLowerCase()).filter(Boolean);
+    } else if (arg === "--threshold" || arg === "-n") {
+      options.editThreshold = parseInt(args[++i], 10);
+    } else if (!arg.startsWith("-")) {
+      options.path = arg;
+    }
+  }
+
+  return options;
+}