thanh-kit 2.5.0

package/templates/hooks/scout-block.cjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+/**
+ * scout-block.cjs - Cross-platform hook for blocking directory access
+ *
+ * Blocks access to directories listed in .claude/.ckignore
+ * Uses gitignore-spec compliant pattern matching via 'ignore' package
+ *
+ * Blocking Rules:
+ * - File paths: Blocks any file_path/path/pattern containing blocked directories
+ * - Bash commands: Blocks directory access (cd, ls, cat, etc.) but ALLOWS build commands
+ *   - Blocked: cd node_modules, ls packages/web/node_modules, cat dist/file.js
+ *   - Allowed: npm build, go build, cargo build, make, mvn, gradle, docker build, kubectl, terraform
+ *
+ * Configuration:
+ * - Edit .claude/.ckignore to customize blocked patterns (one per line, # for comments)
+ * - Supports negation patterns (!) to allow specific paths
+ *
+ * Exit Codes:
+ * - 0: Command allowed
+ * - 2: Command blocked
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Import modules
+const { loadPatterns, createMatcher, matchPath } = require('./scout-block/pattern-matcher.cjs');
+const { extractFromToolInput } = require('./scout-block/path-extractor.cjs');
+const { formatBlockedError } = require('./scout-block/error-formatter.cjs');
+const { detectBroadPatternIssue, formatBroadPatternError } = require('./scout-block/broad-pattern-detector.cjs');
+
+// 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
+// Also allows: go, cargo, make, mvn/mvnw, gradle/gradlew, dotnet, docker, bazel, cmake, sbt, flutter, swift, ant, ninja, meson
+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)/;
+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)/;
+
+/**
+ * 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);
+}
+
+try {
+  // Read stdin synchronously
+  const hookInput = fs.readFileSync(0, 'utf-8');
+
+  // Validate input not empty
+  if (!hookInput || hookInput.trim().length === 0) {
+    console.error('ERROR: Empty input');
+    process.exit(2);
+  }
+
+  // Parse JSON
+  let data;
+  try {
+    data = JSON.parse(hookInput);
+  } catch (parseError) {
+    // Fail-open for unparseable input
+    console.error('WARN: JSON parse failed, allowing operation');
+    process.exit(0);
+  }
+
+  // Validate structure
+  if (!data.tool_input || typeof data.tool_input !== 'object') {
+    // Fail-open for invalid structure
+    console.error('WARN: Invalid JSON structure, allowing operation');
+    process.exit(0);
+  }
+
+  const toolInput = data.tool_input;
+  const toolName = data.tool_name || 'unknown';
+
+  // Check if it's a build command (allowed regardless of paths)
+  if (toolInput.command && isBuildCommand(toolInput.command)) {
+    process.exit(0);
+  }
+
+  // Check for overly broad glob patterns (Glob tool)
+  // This prevents LLMs from filling context with **/*.ts at project root
+  if (toolName === 'Glob' || toolInput.pattern) {
+    const broadResult = detectBroadPatternIssue(toolInput);
+    if (broadResult.blocked) {
+      const errorMsg = formatBroadPatternError(broadResult, path.dirname(__dirname));
+      console.error(errorMsg);
+      process.exit(2);
+    }
+  }
+
+  // Load patterns from .ckignore
+  const scriptDir = __dirname;
+  const claudeDir = path.dirname(scriptDir); // Go up from hooks/ to .claude/
+  const ckignorePath = path.join(claudeDir, '.ckignore');
+  const patterns = loadPatterns(ckignorePath);
+  const matcher = createMatcher(patterns);
+
+  // Extract paths from tool input
+  const extractedPaths = extractFromToolInput(toolInput);
+
+  // If no paths extracted, allow operation
+  if (extractedPaths.length === 0) {
+    process.exit(0);
+  }
+
+  // Check each path against patterns
+  for (const extractedPath of extractedPaths) {
+    const result = matchPath(matcher, extractedPath);
+    if (result.blocked) {
+      // Output rich error message
+      const errorMsg = formatBlockedError({
+        path: extractedPath,
+        pattern: result.pattern,
+        tool: toolName,
+        claudeDir: claudeDir
+      });
+      console.error(errorMsg);
+      process.exit(2);
+    }
+  }
+
+  // All paths allowed
+  process.exit(0);
+
+} catch (error) {
+  // Fail-open for unexpected errors
+  console.error('WARN: Hook error, allowing operation -', error.message);
+  process.exit(0);
+}

package/templates/hooks/scss-styling-context.cjs

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+/**
+ * SCSS Styling Context Injector - PreToolUse Hook
+ *
+ * Automatically injects SCSS styling guide when editing .scss/.css files
+ * in frontend applications. Complements design-system-context.cjs which
+ * handles app-specific design tokens.
+ *
+ * Pattern Matching:
+ *   src/PlatformExampleAppWeb/*    → Angular 19 example app (shared-mixin)
+ *   libs/*                         → Shared libraries
+ *
+ * Exit Codes:
+ *   0 - Success (non-blocking)
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ═══════════════════════════════════════════════════════════════════════════
+// CONFIGURATION
+// ═══════════════════════════════════════════════════════════════════════════
+
+const SCSS_GUIDE_PATH = 'docs/claude/scss-styling-guide.md';
+
+const FRONTEND_PATTERNS = [
+  {
+    name: 'Example App',
+    patterns: [
+      /src[\/\\]PlatformExampleAppWeb[\/\\]/i,
+      /libs[\/\\]platform-core[\/\\]/i,
+      /libs[\/\\]apps-domains[\/\\]/i
+    ],
+    description: 'Angular 19 with shared-mixin SCSS system'
+  },
+  {
+    name: 'Libraries',
+    patterns: [
+      /libs[\/\\]/i
+    ],
+    description: 'Shared component libraries'
+  }
+];
+
+// App-specific patterns for detailed guidance
+const APP_PATTERNS = {
+  'playground-text-snippet': /PlatformExampleAppWeb[\/\\]apps[\/\\]playground-text-snippet/i
+};
+
+// ═══════════════════════════════════════════════════════════════════════════
+// HELPER FUNCTIONS
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Check if SCSS styling context was recently injected
+ */
+function wasRecentlyInjected(transcriptPath) {
+  try {
+    if (!transcriptPath || !fs.existsSync(transcriptPath)) return false;
+    const transcript = fs.readFileSync(transcriptPath, 'utf-8');
+    const recentLines = transcript.split('\n').slice(-200).join('\n');
+    return recentLines.includes('**SCSS Styling Context Detected**');
+  } catch (e) {
+    return false;
+  }
+}
+
+function isStyleFile(filePath) {
+  if (!filePath) return false;
+  const ext = path.extname(filePath).toLowerCase();
+  return ext === '.scss' || ext === '.css' || ext === '.sass' || ext === '.less';
+}
+
+function detectFrontendContext(filePath) {
+  if (!filePath) return null;
+
+  const normalizedPath = filePath.replace(/\\/g, '/');
+
+  for (const context of FRONTEND_PATTERNS) {
+    for (const pattern of context.patterns) {
+      if (pattern.test(normalizedPath)) {
+        return context;
+      }
+    }
+  }
+
+  return null;
+}
+
+function detectApp(filePath) {
+  if (!filePath) return null;
+
+  const normalizedPath = filePath.replace(/\\/g, '/');
+
+  for (const [appName, pattern] of Object.entries(APP_PATTERNS)) {
+    if (pattern.test(normalizedPath)) {
+      return appName;
+    }
+  }
+
+  return null;
+}
+
+function shouldInject(filePath, transcriptPath) {
+  if (!isStyleFile(filePath)) return false;
+  const context = detectFrontendContext(filePath);
+  if (!context) return false;
+  if (wasRecentlyInjected(transcriptPath)) return false;
+  return true;
+}
+
+function buildInjection(context, filePath, app) {
+  const fileName = path.basename(filePath);
+
+  const lines = [
+    '',
+    '## SCSS Styling Context Detected',
+    '',
+    `**Context:** ${context.name}`,
+    `**File:** ${fileName}`,
+    app ? `**App:** ${app}` : '',
+    '',
+    '### Required Reading',
+    '',
+    `Before implementing SCSS/CSS changes, you MUST read:`,
+    '',
+    `**\`${SCSS_GUIDE_PATH}\`**`,
+    '',
+    'This guide contains:',
+    '- BEM naming conventions (block__element --modifier)',
+    '- SCSS architecture patterns and file organization',
+    '- Mixin usage and shared-mixin imports',
+    '- CSS variable conventions for theming',
+    '- Responsive design patterns and breakpoints',
+    '- Component-scoped styling best practices',
+    '',
+    '### Critical Rules',
+    '',
+    '1. **BEM Classes:** Use `block__element` with separate `--modifier` class',
+    '2. **No Magic Numbers:** Use variables for colors, spacing, breakpoints',
+    '3. **Imports:** Use `@use \'shared-mixin\'` for modern Angular apps',
+    '4. **Nesting:** Max 3 levels deep, avoid over-specificity',
+    '5. **Component Scope:** Styles scoped to component block class',
+    ''
+  ];
+
+  // Add context-specific guidance
+  if (context.name === 'Example App') {
+    lines.push(
+      '### Example App SCSS Patterns',
+      '',
+      '```scss',
+      '// Import pattern',
+      '@use \'shared-mixin\' as *;',
+      '',
+      '// CSS Variables for theming',
+      'color: var(--text-primary-cl);',
+      'background: var(--bg-pri-cl);',
+      '',
+      '// Flex mixins',
+      '@include flex-column-container();',
+      '@include flex-row-gap(8px);',
+      '```',
+      ''
+    );
+  }
+
+  // Filter consecutive empty lines
+  return lines.filter((line, i, arr) => {
+    if (line === '' && arr[i - 1] === '') return false;
+    return true;
+  }).join('\n');
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// MAIN EXECUTION
+// ═══════════════════════════════════════════════════════════════════════════
+
+async function main() {
+  try {
+    const stdin = fs.readFileSync(0, 'utf-8').trim();
+    if (!stdin) process.exit(0);
+
+    const payload = JSON.parse(stdin);
+    const toolName = payload.tool_name || '';
+    const toolInput = payload.tool_input || {};
+    const transcriptPath = payload.transcript_path || '';
+
+    if (!['Edit', 'Write', 'MultiEdit'].includes(toolName)) {
+      process.exit(0);
+    }
+
+    const filePath = toolInput.file_path || toolInput.filePath || '';
+    if (!filePath) process.exit(0);
+
+    if (!shouldInject(filePath, transcriptPath)) {
+      process.exit(0);
+    }
+
+    const context = detectFrontendContext(filePath);
+    if (!context) process.exit(0);
+
+    const app = detectApp(filePath);
+    const injection = buildInjection(context, filePath, app);
+    console.log(injection);
+
+    process.exit(0);
+  } catch (error) {
+    process.exit(0);
+  }
+}
+
+main();

package/templates/hooks/session-end.cjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+/**
+ * SessionEnd Hook - Cleanup on session end
+ *
+ * Fires: When session ends (clear, compact, user exit)
+ * Purpose: Delete compact marker files to reset context baseline on /clear
+ *
+ * Exit Codes:
+ *   0 - Success (non-blocking)
+ */
+
+const fs = require('fs');
+const { deleteMarker } = require('./lib/context-tracker.cjs');
+
+async function main() {
+  try {
+    const stdin = fs.readFileSync(0, 'utf-8').trim();
+    const data = stdin ? JSON.parse(stdin) : {};
+    const reason = data.reason || 'unknown';
+    const sessionId = data.session_id || null;
+
+    // Delete marker on /clear to reset context baseline
+    // SessionEnd fires with OLD session_id before new session starts
+    // This ensures clean slate for the next session
+    if (reason === 'clear' && sessionId) {
+      deleteMarker(sessionId);
+    }
+
+    process.exit(0);
+  } catch (error) {
+    process.exit(0);
+  }
+}
+
+main();