@hasna/hooks 0.0.1

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

@@ -0,0 +1,310 @@
+#!/usr/bin/env bun
+
+/**
+ * Claude Code Hook: check-docs
+ *
+ * Runs a headless Claude Code agent to check for missing documentation.
+ * Uses service-implementation CLI to dispatch tasks.
+ *
+ * This hook runs ASYNC (non-blocking) on PostToolUse.
+ * Only runs for repos matching [prefix]-[name] pattern.
+ *
+ * Configuration:
+ * - taskListId: task list for dispatching doc tasks
+ * - editThreshold: run check after this many edits (default: 3, range: 3-7)
+ * - keywords: keywords that trigger the check (default: ["dev"])
+ * - 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 CheckDocsConfig {
+  taskListId?: string;
+  editThreshold?: number;
+  keywords?: 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[];
+  lastCheckRun: number;
+  checkInProgress: boolean;
+}
+
+const CONFIG_KEY = "checkDocsConfig";
+const STATE_DIR = join(homedir(), ".claude", "hook-state");
+const EDIT_TOOLS = ["Edit", "Write", "NotebookEdit"];
+
+const DOCS_PROMPT = `You are a documentation reviewer. Review the following files that were recently edited and identify missing or outdated documentation:
+
+FILES TO REVIEW:
+{files}
+
+For each documentation issue found, create a task using the service-implementation CLI:
+service-implementation task dispatch "{taskListId}" -s "DOCS: [brief description]" -d "[detailed description of what docs need to be added/updated]"
+
+Focus on:
+- Missing function/method documentation
+- Outdated README sections
+- Missing API documentation
+- Missing inline comments for complex logic
+- Missing type definitions documentation
+- Missing usage examples
+
+If no documentation issues are found, do not create any tasks.
+Only create tasks for meaningful documentation gaps, not trivial ones.
+Limit to max 5 most important documentation tasks.`;
+
+function isValidRepoPattern(cwd: string): boolean {
+  const dirName = cwd.split("/").filter(Boolean).pop() || "";
+  // Match: hook-checklint, skill-installhook, iapp-mail, etc.
+  return /^[a-z]+-[a-z0-9-]+$/i.test(dirName);
+}
+
+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): CheckDocsConfig {
+  // Try project settings first
+  const projectSettings = readSettings(join(cwd, ".claude", "settings.json"));
+  if (projectSettings[CONFIG_KEY]) {
+    return projectSettings[CONFIG_KEY] as CheckDocsConfig;
+  }
+
+  // Fall back to global settings
+  const globalSettings = readSettings(join(homedir(), ".claude", "settings.json"));
+  if (globalSettings[CONFIG_KEY]) {
+    return globalSettings[CONFIG_KEY] as CheckDocsConfig;
+  }
+
+  // Default config
+  return {
+    editThreshold: 3,
+    keywords: ["dev"],
+    enabled: true,
+  };
+}
+
+function getStateFile(sessionId: string): string {
+  mkdirSync(STATE_DIR, { recursive: true });
+  return join(STATE_DIR, `checkdocs-${sessionId}.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: [], lastCheckRun: 0, checkInProgress: 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() || "";
+  return `${dirName}-dev`;
+}
+
+function runHeadlessDocsCheck(
+  cwd: string,
+  files: string[],
+  taskListId: string
+): void {
+  const filesFormatted = files.map((f) => `- ${f}`).join("\n");
+
+  const prompt = DOCS_PROMPT
+    .replace("{files}", filesFormatted)
+    .replace("{taskListId}", taskListId);
+
+  // 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-checkdocs] Started docs check for ${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;
+  }
+
+  // Check repo pattern - only run for [prefix]-[name] folders
+  if (!isValidRepoPattern(cwd)) {
+    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 (!matchesKeyword && keywords.length > 0 && nameToCheck) {
+    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 check already in progress
+  if (state.checkInProgress) {
+    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 docs check
+  if (state.editCount >= threshold) {
+    const taskListId = config.taskListId || getProjectTaskListId(cwd) || "default-dev";
+
+    // Mark check in progress
+    state.checkInProgress = true;
+    saveSessionState(session_id, state);
+
+    // Run headless docs check (async, non-blocking)
+    runHeadlessDocsCheck(cwd, state.editedFiles, taskListId);
+
+    // Reset counter after starting check
+    state.editCount = 0;
+    state.editedFiles = [];
+    state.lastCheckRun = Date.now();
+    state.checkInProgress = false;
+  }
+
+  saveSessionState(session_id, state);
+  approve();
+}
+
+// Allow direct execution
+if (import.meta.main) {
+  run();
+}

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

@@ -0,0 +1,141 @@
+# @hasnaxyz/hook-checkfiles
+
+Claude Code hook that runs a headless agent to review files and create tasks via service-implementation.
+
+## Features
+
+- **Async execution**: Runs in background, non-blocking
+- **Headless Claude agent**: Spawns `claude -p` to review files
+- **Task dispatch**: Creates tasks via `service-implementation task dispatch`
+- **Configurable threshold**: Review after N file edits (3-7, default: 3)
+- **Session-aware**: Only runs for sessions matching configured keywords
+
+## Installation
+
+### Global CLI
+
+```bash
+bun add -g @hasnaxyz/hook-checkfiles
+hook-checkfiles install --global
+```
+
+### Project-specific
+
+```bash
+cd /path/to/your/project
+bunx @hasnaxyz/hook-checkfiles install
+```
+
+## Requirements
+
+- `claude` CLI (for headless agent)
+- `service-implementation` CLI (for task dispatch)
+
+## Usage
+
+Once installed, the hook runs automatically after file edits (Edit, Write, NotebookEdit tools).
+
+### Commands
+
+```bash
+hook-checkfiles install [path]     # Install the hook
+hook-checkfiles config [path]      # Update configuration
+hook-checkfiles uninstall [path]   # Remove the hook
+hook-checkfiles status             # Show hook status
+hook-checkfiles 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-checkfiles@latest run",
+        "timeout": 120,
+        "async": true
+      }]
+    }]
+  },
+  "checkFilesConfig": {
+    "editThreshold": 3,
+    "taskListId": "myproject-bugfixes",
+    "keywords": ["dev"],
+    "enabled": true
+  }
+}
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `editThreshold` | number | 3 | Run review after this many edits (3-7) |
+| `taskListId` | string | auto | Task list for dispatching tasks |
+| `keywords` | string[] | ["dev"] | Only run for matching sessions |
+| `reviewPrompt` | string | default | Custom prompt for headless agent |
+| `enabled` | boolean | true | Enable/disable the hook |
+
+## How It Works
+
+1. **Tracks file edits**: Monitors Edit, Write, NotebookEdit tool calls
+2. **Counts edits**: Maintains per-session edit counter
+3. **Triggers review**: After N edits, spawns headless Claude agent
+4. **Agent reviews**: Claude analyzes files for issues
+5. **Creates tasks**: Uses `service-implementation task dispatch` for each issue
+6. **Non-blocking**: Runs async, doesn't block main session
+
+## Headless Agent
+
+The hook spawns:
+
+```bash
+claude -p "<review prompt>" \
+  --permission-mode acceptEdits \
+  --allowedTools "Bash,Read" \
+  --no-session-persistence
+```
+
+The agent:
+- Reads the edited files
+- Identifies bugs, security issues, performance problems
+- Creates tasks via `service-implementation task dispatch`
+
+## Task Format
+
+Tasks are dispatched with:
+
+```bash
+service-implementation task dispatch "myproject-bugfixes" \
+  -s "REVIEW: [brief issue description]" \
+  -d "[detailed description with file:line reference]"
+```
+
+## Session State
+
+State is persisted in `~/.claude/hook-state/checkfiles-{session_id}.json`:
+
+```json
+{
+  "editCount": 2,
+  "editedFiles": ["src/file.ts", "src/other.ts"],
+  "lastReviewRun": 1706500000000,
+  "reviewInProgress": false
+}
+```
+
+## License
+
+MIT

package/hooks/hook-checkfiles/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@hasnaxyz/hook-checkfiles",
+  "version": "0.1.1",
+  "description": "Claude Code hook that runs headless agent to review files and create tasks",
+  "type": "module",
+  "bin": {
+    "hook-checkfiles": "./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",
+    "review",
+    "headless",
+    "automation",
+    "cli"
+  ],
+  "author": "Hasna",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hasnaxyz/hook-checkfiles.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"
+  }
+}