thanh-kit 2.5.0 → 2.5.1

package/templates/hooks/lib/scout-checker.cjs

@@ -0,0 +1,263 @@
+#!/usr/bin/env node
+/**
+ * scout-checker.cjs - Facade for scout-block modules
+ *
+ * Provides unified interface to scout-block/* modules for reuse in both
+ * Claude hooks and OpenCode plugins.
+ *
+ * @module scout-checker
+ */
+
+const path = require('path');
+
+// Import scout-block modules
+const { loadPatterns, createMatcher, matchPath } = require('../scout-block/pattern-matcher.cjs');
+const { extractFromToolInput } = require('../scout-block/path-extractor.cjs');
+const { detectBroadPatternIssue } = require('../scout-block/broad-pattern-detector.cjs');
+
+// ═══════════════════════════════════════════════════════════════════════════
+// COMMAND PATTERNS
+// ═══════════════════════════════════════════════════════════════════════════
+
+// Build command allowlist - these are allowed even if they contain blocked paths
+// Handles flags and filters: npm build, pnpm --filter web run build, yarn workspace app build
+const BUILD_COMMAND_PATTERN = /^(npm|pnpm|yarn|bun)\s+([^\s]+\s+)*(run\s+)?(build|test|lint|dev|start|install|ci|add|remove|update|publish|pack|init|create|exec)/;
+
+// Tool commands - JS/TS, Go, Rust, Java, .NET, containers, IaC, Python, Ruby, PHP, Deno, Elixir
+const TOOL_COMMAND_PATTERN = /^(\.\/)?(npx|pnpx|bunx|tsc|esbuild|vite|webpack|rollup|turbo|nx|jest|vitest|mocha|eslint|prettier|go|cargo|make|mvn|mvnw|gradle|gradlew|dotnet|docker|podman|kubectl|helm|terraform|ansible|bazel|cmake|sbt|flutter|swift|ant|ninja|meson|python3?|pip|uv|deno|bundle|rake|gem|php|composer|ruby|mix|elixir)/;
+
+// Allow execution from .venv/bin/ or venv/bin/ (Unix) and .venv/Scripts/ or venv/Scripts/ (Windows)
+const VENV_EXECUTABLE_PATTERN = /(^|[\/\\])\.?venv[\/\\](bin|Scripts)[\/\\]/;
+
+// Allow Python venv creation commands (cross-platform):
+// - python/python3 -m venv (Unix/macOS/Windows)
+// - py -m venv (Windows py launcher, supports -3, -3.11, etc.)
+// - uv venv (fast Rust-based Python package manager)
+// - virtualenv (legacy but still widely used)
+const VENV_CREATION_PATTERN = /^(python3?|py)\s+(-[\w.]+\s+)*-m\s+venv\s+|^uv\s+venv(\s|$)|^virtualenv\s+/;
+
+// ═══════════════════════════════════════════════════════════════════════════
+// HELPER FUNCTIONS
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Strip leading ENV variable assignments and command wrappers (sudo, env, etc.)
+ * e.g., "NODE_ENV=production npm run build" → "npm run build"
+ * @param {string} command - The command to strip
+ * @returns {string}
+ */
+function stripCommandPrefix(command) {
+  if (!command || typeof command !== 'string') return command;
+  let stripped = command.trim();
+  // Strip env var assignments (KEY=VALUE KEY2=VALUE2 ...)
+  stripped = stripped.replace(/^(\w+=\S+\s+)+/, '');
+  // Strip common command wrappers (one level)
+  stripped = stripped.replace(/^(sudo|env|nice|nohup|time|timeout)\s+/, '');
+  // Strip env vars again (sudo env VAR=x cmd)
+  stripped = stripped.replace(/^(\w+=\S+\s+)+/, '');
+  return stripped.trim();
+}
+
+/**
+ * Check if a command is a build/tooling command (should be allowed)
+ * @param {string} command - The command to check
+ * @returns {boolean}
+ */
+function isBuildCommand(command) {
+  if (!command || typeof command !== 'string') return false;
+  const trimmed = command.trim();
+  return BUILD_COMMAND_PATTERN.test(trimmed) || TOOL_COMMAND_PATTERN.test(trimmed);
+}
+
+/**
+ * Split a compound command into sub-commands on &&, ||, and ;.
+ * Does NOT split on newlines — newlines in command strings are typically
+ * heredoc bodies or multiline strings, not compound operators.
+ * Does not handle operators inside quoted strings (extremely rare in practice).
+ *
+ * @param {string} command - The compound command string
+ * @returns {string[]} Array of sub-commands (trimmed, non-empty)
+ */
+function splitCompoundCommand(command) {
+  if (!command || typeof command !== 'string') return [];
+  return command.split(/\s*(?:&&|\|\||;)\s*/).filter(cmd => cmd && cmd.trim().length > 0);
+}
+
+/**
+ * Unwrap shell executor wrappers (bash -c "...", sh -c '...', eval "...").
+ * Returns the inner command string for re-processing.
+ * @param {string} command - The command to unwrap
+ * @returns {string} Inner command, or original if not a shell executor
+ */
+function unwrapShellExecutor(command) {
+  if (!command || typeof command !== 'string') return command;
+  const match = command.trim().match(
+    /^(?:(?:bash|sh|zsh)\s+-c|eval)\s+["'](.+)["']\s*$/
+  );
+  return match ? match[1] : command;
+}
+
+/**
+ * Check if command executes from a .venv bin directory
+ * @param {string} command - The command to check
+ * @returns {boolean}
+ */
+function isVenvExecutable(command) {
+  if (!command || typeof command !== 'string') return false;
+  return VENV_EXECUTABLE_PATTERN.test(command);
+}
+
+/**
+ * Check if command creates a Python virtual environment
+ * @param {string} command - The command to check
+ * @returns {boolean}
+ */
+function isVenvCreationCommand(command) {
+  if (!command || typeof command !== 'string') return false;
+  return VENV_CREATION_PATTERN.test(command.trim());
+}
+
+/**
+ * Check if command should be allowed (build, venv executable, or venv creation)
+ * Strips ENV prefixes and command wrappers before checking.
+ * @param {string} command - The command to check
+ * @returns {boolean}
+ */
+function isAllowedCommand(command) {
+  const stripped = stripCommandPrefix(command);
+  return isBuildCommand(stripped) || isVenvExecutable(stripped) || isVenvCreationCommand(stripped);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// MAIN ENTRY POINT
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Check if a tool call accesses blocked directories or uses overly broad patterns
+ *
+ * @param {Object} params
+ * @param {string} params.toolName - Name of tool (Bash, Glob, Read, etc.)
+ * @param {Object} params.toolInput - Tool input with file_path, path, pattern, command
+ * @param {Object} [params.options]
+ * @param {string} [params.options.ckignorePath] - Path to .ckignore file
+ * @param {string} [params.options.claudeDir] - Path to .claude or .opencode directory
+ * @param {boolean} [params.options.checkBroadPatterns] - Check for overly broad glob patterns (default: true)
+ * @returns {{
+ *   blocked: boolean,
+ *   path?: string,
+ *   pattern?: string,
+ *   reason?: string,
+ *   isBroadPattern?: boolean,
+ *   suggestions?: string[],
+ *   isAllowedCommand?: boolean
+ * }}
+ */
+function checkScoutBlock({ toolName, toolInput, options = {} }) {
+  const {
+    ckignorePath,
+    claudeDir = path.join(process.cwd(), '.claude'),
+    checkBroadPatterns = true
+  } = options;
+
+  // Unwrap shell executor wrappers (bash -c "...", eval "...")
+  // so the inner command gets properly analyzed
+  if (toolInput.command) {
+    const unwrapped = unwrapShellExecutor(toolInput.command);
+    if (unwrapped !== toolInput.command) {
+      toolInput = { ...toolInput, command: unwrapped };
+    }
+  }
+
+  // For Bash commands, split compound commands (&&, ||, ;) and check
+  // each sub-command independently. This prevents "echo msg && npm run build"
+  // from being blocked due to "build" token in the allowed build sub-command.
+  // Must split BEFORE isAllowedCommand because BUILD_COMMAND_PATTERN has no end
+  // anchor and would match the prefix of "npm run build && cat dist/file.js".
+  if (toolInput.command) {
+    const subCommands = splitCompoundCommand(toolInput.command);
+    const nonAllowed = subCommands.filter(cmd => !isAllowedCommand(cmd.trim()));
+    if (nonAllowed.length === 0) {
+      return { blocked: false, isAllowedCommand: true };
+    }
+    // Only extract paths from non-allowed sub-commands
+    if (nonAllowed.length < subCommands.length) {
+      toolInput = { ...toolInput, command: nonAllowed.join(' ; ') };
+    }
+  }
+
+  // Check for overly broad glob patterns (Glob tool)
+  if (checkBroadPatterns && (toolName === 'Glob' || toolInput.pattern)) {
+    const broadResult = detectBroadPatternIssue(toolInput);
+    if (broadResult.blocked) {
+      return {
+        blocked: true,
+        isBroadPattern: true,
+        pattern: toolInput.pattern,
+        reason: broadResult.reason || 'Pattern too broad - may fill context with too many files',
+        suggestions: broadResult.suggestions || []
+      };
+    }
+  }
+
+  // Resolve .ckignore path
+  const resolvedCkignorePath = ckignorePath || path.join(claudeDir, '.ckignore');
+
+  // Load patterns and create matcher
+  const patterns = loadPatterns(resolvedCkignorePath);
+  const matcher = createMatcher(patterns);
+
+  // Extract paths from tool input
+  const extractedPaths = extractFromToolInput(toolInput);
+
+  // If no paths extracted, allow operation
+  if (extractedPaths.length === 0) {
+    return { blocked: false };
+  }
+
+  // Check each path against patterns
+  for (const extractedPath of extractedPaths) {
+    const result = matchPath(matcher, extractedPath);
+    if (result.blocked) {
+      return {
+        blocked: true,
+        path: extractedPath,
+        pattern: result.pattern,
+        reason: `Path matches blocked pattern: ${result.pattern}`
+      };
+    }
+  }
+
+  // All paths allowed
+  return { blocked: false };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// EXPORTS
+// ═══════════════════════════════════════════════════════════════════════════
+
+module.exports = {
+  // Main entry point
+  checkScoutBlock,
+
+  // Command checkers
+  isBuildCommand,
+  isVenvExecutable,
+  isVenvCreationCommand,
+  isAllowedCommand,
+  splitCompoundCommand,
+  stripCommandPrefix,
+  unwrapShellExecutor,
+
+  // Re-export scout-block modules for direct access
+  loadPatterns,
+  createMatcher,
+  matchPath,
+  extractFromToolInput,
+  detectBroadPatternIssue,
+
+  // Patterns (for testing)
+  BUILD_COMMAND_PATTERN,
+  TOOL_COMMAND_PATTERN,
+  VENV_EXECUTABLE_PATTERN,
+  VENV_CREATION_PATTERN
+};

package/templates/hooks/lib/transcript-parser.cjs

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Transcript Parser - Extract tool/agent/todo state from session JSONL
+ * @module transcript-parser
+ */
+
+const fs = require('fs');
+const readline = require('readline');
+
+/**
+ * Parse transcript JSONL file
+ * @param {string} transcriptPath - Path to transcript file
+ * @returns {Promise<TranscriptData>}
+ */
+async function parseTranscript(transcriptPath) {
+  const result = {
+    tools: [],
+    agents: [],
+    todos: [],
+    sessionStart: null
+  };
+
+  if (!transcriptPath || !fs.existsSync(transcriptPath)) {
+    return result;
+  }
+
+  const toolMap = new Map();
+  const agentMap = new Map();
+  let latestTodos = [];
+
+  try {
+    const fileStream = fs.createReadStream(transcriptPath);
+    const rl = readline.createInterface({
+      input: fileStream,
+      crlfDelay: Infinity
+    });
+
+    for await (const line of rl) {
+      if (!line.trim()) continue;
+
+      try {
+        const entry = JSON.parse(line);
+        processEntry(entry, toolMap, agentMap, latestTodos, result);
+      } catch {
+        // Skip malformed lines
+      }
+    }
+  } catch {
+    // Return partial results on error
+  }
+
+  result.tools = Array.from(toolMap.values()).slice(-20);
+  result.agents = Array.from(agentMap.values()).slice(-10);
+  result.todos = latestTodos;
+
+  return result;
+}
+
+/**
+ * Process single JSONL entry
+ * @param {Object} entry - Parsed JSON line
+ * @param {Map} toolMap - Tool tracking map
+ * @param {Map} agentMap - Agent tracking map
+ * @param {Array} latestTodos - Latest todo array reference
+ * @param {Object} result - Result object
+ */
+function processEntry(entry, toolMap, agentMap, latestTodos, result) {
+  const timestamp = entry.timestamp ? new Date(entry.timestamp) : new Date();
+
+  // Track session start
+  if (!result.sessionStart && entry.timestamp) {
+    result.sessionStart = timestamp;
+  }
+
+  const content = entry.message?.content;
+  if (!content || !Array.isArray(content)) return;
+
+  for (const block of content) {
+    // Handle tool_use blocks
+    if (block.type === 'tool_use' && block.id && block.name) {
+      if (block.name === 'Task') {
+        // Agent spawn
+        agentMap.set(block.id, {
+          id: block.id,
+          type: block.input?.subagent_type ?? 'unknown',
+          model: block.input?.model ?? null,
+          description: block.input?.description ?? null,
+          status: 'running',
+          startTime: timestamp,
+          endTime: null
+        });
+      } else if (block.name === 'TodoWrite') {
+        // Legacy: Replace todo array (deprecated, kept for backwards compatibility)
+        if (block.input?.todos && Array.isArray(block.input.todos)) {
+          latestTodos.length = 0;
+          latestTodos.push(...block.input.todos);
+        }
+      } else if (block.name === 'TaskCreate') {
+        // Native Task API: Add new task
+        if (block.input?.subject) {
+          latestTodos.push({
+            content: block.input.subject,
+            status: 'pending',
+            activeForm: block.input.activeForm || null
+          });
+        }
+      } else if (block.name === 'TaskUpdate') {
+        // Native Task API: Update existing task status
+        if (block.input?.taskId && block.input?.status) {
+          const task = latestTodos.find(t => t.id === block.input.taskId);
+          if (task) {
+            task.status = block.input.status;
+          }
+        }
+      } else {
+        // Regular tool
+        toolMap.set(block.id, {
+          id: block.id,
+          name: block.name,
+          target: extractTarget(block.name, block.input),
+          status: 'running',
+          startTime: timestamp,
+          endTime: null
+        });
+      }
+    }
+
+    // Handle tool_result blocks
+    if (block.type === 'tool_result' && block.tool_use_id) {
+      const tool = toolMap.get(block.tool_use_id);
+      if (tool) {
+        tool.status = block.is_error ? 'error' : 'completed';
+        tool.endTime = timestamp;
+      }
+
+      const agent = agentMap.get(block.tool_use_id);
+      if (agent) {
+        agent.status = 'completed';
+        agent.endTime = timestamp;
+      }
+    }
+  }
+}
+
+/**
+ * Extract target from tool input
+ * @param {string} toolName - Tool name
+ * @param {Object} input - Tool input object
+ * @returns {string|null} - Extracted target
+ */
+function extractTarget(toolName, input) {
+  if (!input) return null;
+
+  switch (toolName) {
+    case 'Read':
+    case 'Write':
+    case 'Edit':
+      return input.file_path ?? input.path ?? null;
+
+    case 'Glob':
+    case 'Grep':
+      return input.pattern ?? null;
+
+    case 'Bash':
+      const cmd = input.command;
+      if (!cmd) return null;
+      return cmd.length > 30 ? cmd.slice(0, 30) + '...' : cmd;
+
+    default:
+      return null;
+  }
+}
+
+module.exports = {
+  parseTranscript,
+  // Export for testing
+  processEntry,
+  extractTarget
+};

package/templates/hooks/notifications/discord_notify.sh

@@ -1,9 +1,22 @@
 #!/bin/bash
 
-# Discord Notification Hook for Claude Code
-# This hook sends a notification to Discord when Claude finishes a task
-
-set -euo pipefail
+# ┌─────────────────────────────────────────────────────────────────────────┐
+# │ DEPRECATED: This script is no longer maintained                         │
+# │                                                                         │
+# │ Use notify.cjs instead - zero dependencies, works everywhere:           │
+# │   node .claude/hooks/notifications/notify.cjs                           │
+# │                                                                         │
+# │ In your settings.json:                                                  │
+# │   "Stop": [{"matcher": "*", "hooks": [{"type": "command",               │
+# │     "command": "node .claude/hooks/notifications/notify.cjs"}]}]        │
+# └─────────────────────────────────────────────────────────────────────────┘
+
+echo "⚠️  DEPRECATED: discord_notify.sh is no longer maintained" >&2
+echo "   Use: node .claude/hooks/notifications/notify.cjs" >&2
+echo "   See: .claude/hooks/notifications/docs/discord-hook-setup.md" >&2
+exit 1
+
+# --- LEGACY CODE BELOW (kept for reference) ---
 
 # Load environment variables with priority: process.env > .claude/.env > .claude/hooks/.env
 load_env() {

package/templates/hooks/notifications/docs/discord-hook-setup.md

@@ -1,12 +1,10 @@
 # Discord Notification Hook Setup
 
-## Quick Start (Unified System - Recommended)
+Get Discord notifications when Claude Code sessions complete.
 
-The new unified notification system fixes field name issues and routes to all providers.
+## Quick Start
 
-**Bug Fix:** The original bash script used incorrect field names (hookType, projectDir, sessionId). The new Node.js provider correctly uses snake_case fields (hook_event_name, cwd, session_id) matching Claude Code's hook input format.
-
-### 1. Set Environment Variables
+### 1. Set Environment Variable
 
 Add to `~/.claude/.env` (global) or `.claude/.env` (project):
 
@@ -14,9 +12,27 @@ Add to `~/.claude/.env` (global) or `.claude/.env` (project):
 DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/xxx/yyy
 ```
 
-### 2. Enable in settings.json
+### 2. Add Hook to settings.json
+
+Add to your `.claude/settings.json` (project) or `~/.claude/settings.json` (global):
 
-Hooks are already configured in `.claude/settings.json`.
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/notifications/notify.cjs"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
 
 ### 3. Test
 
@@ -27,9 +43,9 @@ echo '{"hook_event_name":"Stop","cwd":"'"$(pwd)"'","session_id":"test123"}' | \
 
 ---
 
-## Legacy Bash Script Setup
+## Legacy Bash Scripts (Deprecated)
 
-The original scripts are still available for backward compatibility.
+The original bash scripts (`discord_notify.sh`, `telegram_notify.sh`) are **deprecated** due to jq PATH issues in Claude Code's subprocess environment. Use `notify.cjs` instead.
 
 ---
 
@@ -147,7 +163,7 @@ Send a notification with a custom message:
 
 ### Automated Usage (Claude Code Workflow)
 
-Claude automatically calls this script when completing implementations. This is configured in `.claude/workflows/development-rules.md`:
+Claude automatically calls this script when completing implementations. This is configured in `.claude/rules/development-rules.md`:
 
 ```markdown
 - When you finish the implementation, send a full summary report to Discord channel

package/templates/hooks/notifications/docs/telegram-hook-setup.md

@@ -1,8 +1,8 @@
 # Telegram Notification Hook Setup
 
-## Quick Start (Unified System - Recommended)
+Get Telegram notifications when Claude Code sessions complete.
 
-The new unified notification system routes to all configured providers automatically.
+## Quick Start
 
 ### 1. Set Environment Variables
 
@@ -13,9 +13,27 @@ TELEGRAM_BOT_TOKEN=your_bot_token
 TELEGRAM_CHAT_ID=your_chat_id
 ```
 
-### 2. Enable in settings.json
+### 2. Add Hook to settings.json
 
-Hooks are already configured in `.claude/settings.json`. The unified system is enabled by default for Stop, SubagentStop, and AskUserPrompt events.
+Add to your `.claude/settings.json` (project) or `~/.claude/settings.json` (global):
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/notifications/notify.cjs"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
 
 ### 3. Test
 
@@ -26,9 +44,9 @@ echo '{"hook_event_name":"Stop","cwd":"'"$(pwd)"'","session_id":"test123"}' | \
 
 ---
 
-## Legacy Bash Script Setup
+## Legacy Bash Scripts (Deprecated)
 
-The original `telegram_notify.sh` is still available for backward compatibility. See below for legacy setup.
+The original `telegram_notify.sh` is **deprecated** due to jq PATH issues in Claude Code's subprocess environment. Use `notify.cjs` instead.
 
 ---
 

package/templates/hooks/notifications/telegram_notify.sh

@@ -1,9 +1,22 @@
 #!/bin/bash
 
-# Telegram Notification Hook for Claude Code (Project-Specific)
-# This hook sends a notification to Telegram when Claude finishes a task
-
-set -euo pipefail
+# ┌─────────────────────────────────────────────────────────────────────────┐
+# │ DEPRECATED: This script is no longer maintained                         │
+# │                                                                         │
+# │ Use notify.cjs instead - zero dependencies, works everywhere:           │
+# │   node .claude/hooks/notifications/notify.cjs                           │
+# │                                                                         │
+# │ In your settings.json:                                                  │
+# │   "Stop": [{"matcher": "*", "hooks": [{"type": "command",               │
+# │     "command": "node .claude/hooks/notifications/notify.cjs"}]}]        │
+# └─────────────────────────────────────────────────────────────────────────┘
+
+echo "⚠️  DEPRECATED: telegram_notify.sh is no longer maintained" >&2
+echo "   Use: node .claude/hooks/notifications/notify.cjs" >&2
+echo "   See: .claude/hooks/notifications/docs/" >&2
+exit 1
+
+# --- LEGACY CODE BELOW (kept for reference) ---
 
 # Load environment variables with priority: process.env > .claude/.env > .claude/hooks/.env
 load_env() {