kodelyth-ecc 1.2.0

package/scripts/hooks/auto-tmux-dev.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+/**
+ * Auto-Tmux Dev Hook - Start dev servers in tmux/cmd automatically
+ *
+ * macOS/Linux: Runs dev server in a named tmux session (non-blocking).
+ *              Falls back to original command if tmux is not installed.
+ * Windows: Opens dev server in a new cmd window (non-blocking).
+ *
+ * Runs before Bash tool use. If command is a dev server (npm run dev, pnpm dev, yarn dev, bun run dev),
+ * transforms it to run in a detached session.
+ *
+ * Benefits:
+ * - Dev server runs detached (doesn't block Claude Code)
+ * - Session persists (can run `tmux capture-pane -t <session> -p` to see logs on Unix)
+ * - Session name matches project directory (allows multiple projects simultaneously)
+ *
+ * Session management (Unix):
+ * - Checks tmux availability before transforming
+ * - Kills any existing session with the same name (clean restart)
+ * - Creates new detached session
+ * - Reports session name and how to view logs
+ *
+ * Session management (Windows):
+ * - Opens new cmd window with descriptive title
+ * - Allows multiple dev servers to run simultaneously
+ */
+
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const MAX_STDIN = 1024 * 1024; // 1MB limit
+let data = '';
+process.stdin.setEncoding('utf8');
+
+process.stdin.on('data', chunk => {
+  if (data.length < MAX_STDIN) {
+    const remaining = MAX_STDIN - data.length;
+    data += chunk.substring(0, remaining);
+  }
+});
+
+process.stdin.on('end', () => {
+  let input;
+  try {
+    input = JSON.parse(data);
+    const cmd = input.tool_input?.command || '';
+
+    // Detect dev server commands: npm run dev, pnpm dev, yarn dev, bun run dev
+    // Use word boundary (\b) to avoid matching partial commands
+    const devServerRegex = /(npm run dev\b|pnpm( run)? dev\b|yarn dev\b|bun run dev\b)/;
+
+    if (devServerRegex.test(cmd)) {
+      // Get session name from current directory basename, sanitize for shell safety
+      // e.g., /home/user/Portfolio → "Portfolio", /home/user/my-app-v2 → "my-app-v2"
+      const rawName = path.basename(process.cwd());
+      // Replace non-alphanumeric characters (except - and _) with underscore to prevent shell injection
+      const sessionName = rawName.replace(/[^a-zA-Z0-9_-]/g, '_') || 'dev';
+
+      if (process.platform === 'win32') {
+        // Windows: open in a new cmd window (non-blocking)
+        // Escape double quotes in cmd for cmd /k syntax
+        const escapedCmd = cmd.replace(/"/g, '""');
+        input.tool_input.command = `start "DevServer-${sessionName}" cmd /k "${escapedCmd}"`;
+      } else {
+        // Unix (macOS/Linux): Check tmux is available before transforming
+        const tmuxCheck = spawnSync('which', ['tmux'], { encoding: 'utf8' });
+        if (tmuxCheck.status === 0) {
+          // Escape single quotes for shell safety: 'text' -> 'text'\''text'
+          const escapedCmd = cmd.replace(/'/g, "'\\''");
+
+          // Build the transformed command:
+          // 1. Kill existing session (silent if doesn't exist)
+          // 2. Create new detached session with the dev command
+          // 3. Echo confirmation message with instructions for viewing logs
+          const transformedCmd = `SESSION="${sessionName}"; tmux kill-session -t "$SESSION" 2>/dev/null || true; tmux new-session -d -s "$SESSION" '${escapedCmd}' && echo "[Hook] Dev server started in tmux session '${sessionName}'. View logs: tmux capture-pane -t ${sessionName} -p -S -100"`;
+
+          input.tool_input.command = transformedCmd;
+        }
+        // else: tmux not found, pass through original command unchanged
+      }
+    }
+    process.stdout.write(JSON.stringify(input));
+  } catch {
+    // Invalid input — pass through original data unchanged
+    process.stdout.write(data);
+  }
+  process.exit(0);
+});

package/scripts/hooks/branch-name-check.js

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+/**
+ * Kodelyth ECC — Branch Name Check Hook
+ * PreToolUse: Bash
+ *
+ * Intercepts `git checkout -b` and `git switch -c` commands.
+ * Validates the branch name follows conventional patterns.
+ * Blocks invalid names with a clear explanation.
+ *
+ * Valid patterns:
+ *   feat/description
+ *   fix/description
+ *   chore/description
+ *   docs/description
+ *   refactor/description
+ *   test/description
+ *   perf/description
+ *   ci/description
+ *   hotfix/description
+ *   release/1.2.0
+ *
+ * Respects ECC_DISABLED_HOOKS env var.
+ */
+
+'use strict'
+
+const VALID_PREFIXES = [
+  'feat',
+  'fix',
+  'chore',
+  'docs',
+  'refactor',
+  'test',
+  'perf',
+  'ci',
+  'hotfix',
+  'release',
+  'experiment',
+  'spike',
+  'wip',
+]
+
+const BRANCH_REGEX = new RegExp(
+  `^(${VALID_PREFIXES.join('|')})\\/[a-z0-9][a-z0-9-._/]{1,60}$`
+)
+
+// Protected branches — never block these
+const PROTECTED_BRANCHES = ['main', 'master', 'develop', 'staging', 'production']
+
+// Extract branch name from git command
+function extractBranchName (command) {
+  // git checkout -b branch-name
+  const checkoutMatch = command.match(/git\s+checkout\s+(?:-b|-B)\s+([^\s]+)/)
+  if (checkoutMatch) return checkoutMatch[1]
+
+  // git switch -c branch-name
+  const switchMatch = command.match(/git\s+switch\s+(?:-c|-C)\s+([^\s]+)/)
+  if (switchMatch) return switchMatch[1]
+
+  return null
+}
+
+function isDisabled () {
+  const disabled = (process.env.ECC_DISABLED_HOOKS || '').split(',')
+  return disabled.includes('kodelyth:branch-name')
+}
+
+function isProtected (name) {
+  return PROTECTED_BRANCHES.includes(name)
+}
+
+function isValid (name) {
+  return BRANCH_REGEX.test(name)
+}
+
+function buildError (branchName) {
+  return {
+    type: 'user_prompt_submit',
+    content: [
+      {
+        type: 'text',
+        text: [
+          `Branch name "${branchName}" doesn't follow the Kodelyth convention.`,
+          '',
+          'Valid format: <type>/<description>',
+          '',
+          'Types: ' + VALID_PREFIXES.join(', '),
+          '',
+          'Examples:',
+          '  feat/add-user-authentication',
+          '  fix/null-pointer-in-checkout',
+          '  chore/upgrade-typescript-5',
+          '  hotfix/payment-double-charge',
+          '  release/2.1.0',
+          '',
+          'Rules:',
+          '  - lowercase letters, numbers, hyphens only',
+          '  - must have a type prefix',
+          '  - description must be meaningful (not just "fix" or "test")',
+        ].join('\n'),
+      },
+    ],
+  }
+}
+
+async function main () {
+  const raw = await readStdin()
+
+  if (isDisabled()) {
+    process.stdout.write(raw)
+    return
+  }
+
+  let input
+
+  try {
+    input = JSON.parse(raw)
+  } catch {
+    process.stdout.write(raw)
+    return
+  }
+
+  const command = input?.tool_input?.command || ''
+
+  const branchName = extractBranchName(command)
+
+  if (!branchName) {
+    // Not a branch creation command — pass through
+    process.stdout.write(raw)
+    return
+  }
+
+  if (isProtected(branchName)) {
+    // Protected branches are fine
+    process.stdout.write(raw)
+    return
+  }
+
+  if (isValid(branchName)) {
+    // Valid name — pass through silently
+    process.stdout.write(raw)
+    return
+  }
+
+  // Invalid — block with explanation
+  process.stdout.write(JSON.stringify(buildError(branchName)))
+  process.exit(2) // exit code 2 = block the tool call
+}
+
+function readStdin () {
+  return new Promise((resolve) => {
+    let data = ''
+    process.stdin.setEncoding('utf8')
+    process.stdin.on('data', chunk => { data += chunk })
+    process.stdin.on('end', () => resolve(data))
+    process.stdin.on('error', () => resolve(data))
+    setTimeout(() => resolve(data), 3000)
+  })
+}
+
+main().catch(() => {
+  process.exit(0) // never hard-fail — just pass through
+})

package/scripts/hooks/check-console-log.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+
+/**
+ * Stop Hook: Check for console.log statements in modified files
+ *
+ * Cross-platform (Windows, macOS, Linux)
+ *
+ * Runs after each response and checks if any modified JavaScript/TypeScript
+ * files contain console.log statements. Provides warnings to help developers
+ * remember to remove debug statements before committing.
+ *
+ * Exclusions: test files, config files, and scripts/ directory (where
+ * console.log is often intentional).
+ */
+
+const fs = require('fs');
+const { isGitRepo, getGitModifiedFiles, readFile, log } = require('../lib/utils');
+
+// Files where console.log is expected and should not trigger warnings
+const EXCLUDED_PATTERNS = [
+  /\.test\.[jt]sx?$/,
+  /\.spec\.[jt]sx?$/,
+  /\.config\.[jt]s$/,
+  /scripts\//,
+  /__tests__\//,
+  /__mocks__\//,
+];
+
+const MAX_STDIN = 1024 * 1024; // 1MB limit
+let data = '';
+process.stdin.setEncoding('utf8');
+
+process.stdin.on('data', chunk => {
+  if (data.length < MAX_STDIN) {
+    const remaining = MAX_STDIN - data.length;
+    data += chunk.substring(0, remaining);
+  }
+});
+
+process.stdin.on('end', () => {
+  try {
+    if (!isGitRepo()) {
+      process.stdout.write(data);
+      process.exit(0);
+    }
+
+    const files = getGitModifiedFiles(['\\.tsx?$', '\\.jsx?$'])
+      .filter(f => fs.existsSync(f))
+      .filter(f => !EXCLUDED_PATTERNS.some(pattern => pattern.test(f)));
+
+    let hasConsole = false;
+
+    for (const file of files) {
+      const content = readFile(file);
+      if (content && content.includes('console.log')) {
+        log(`[Hook] WARNING: console.log found in ${file}`);
+        hasConsole = true;
+      }
+    }
+
+    if (hasConsole) {
+      log('[Hook] Remove console.log statements before committing');
+    }
+  } catch (err) {
+    log(`[Hook] check-console-log error: ${err.message}`);
+  }
+
+  // Always output the original data
+  process.stdout.write(data);
+  process.exit(0);
+});

package/scripts/hooks/check-hook-enabled.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+'use strict';
+
+const { isHookEnabled } = require('../lib/hook-flags');
+
+const [, , hookId, profilesCsv] = process.argv;
+if (!hookId) {
+  process.stdout.write('yes');
+  process.exit(0);
+}
+
+process.stdout.write(isHookEnabled(hookId, { profiles: profilesCsv }) ? 'yes' : 'no');

package/scripts/hooks/config-protection.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+/**
+ * Config Protection Hook
+ *
+ * Blocks modifications to linter/formatter config files.
+ * Agents frequently modify these to make checks pass instead of fixing
+ * the actual code. This hook steers the agent back to fixing the source.
+ *
+ * Exit codes:
+ *   0 = allow (not a config file)
+ *   2 = block (config file modification attempted)
+ */
+
+'use strict';
+
+const path = require('path');
+
+const MAX_STDIN = 1024 * 1024;
+let raw = '';
+
+const PROTECTED_FILES = new Set([
+  // ESLint (legacy + v9 flat config, JS/TS/MJS/CJS)
+  '.eslintrc',
+  '.eslintrc.js',
+  '.eslintrc.cjs',
+  '.eslintrc.json',
+  '.eslintrc.yml',
+  '.eslintrc.yaml',
+  'eslint.config.js',
+  'eslint.config.mjs',
+  'eslint.config.cjs',
+  'eslint.config.ts',
+  'eslint.config.mts',
+  'eslint.config.cts',
+  // Prettier (all config variants including ESM)
+  '.prettierrc',
+  '.prettierrc.js',
+  '.prettierrc.cjs',
+  '.prettierrc.json',
+  '.prettierrc.yml',
+  '.prettierrc.yaml',
+  'prettier.config.js',
+  'prettier.config.cjs',
+  'prettier.config.mjs',
+  // Biome
+  'biome.json',
+  'biome.jsonc',
+  // Ruff (Python)
+  '.ruff.toml',
+  'ruff.toml',
+  // Note: pyproject.toml is intentionally NOT included here because it
+  // contains project metadata alongside linter config. Blocking all edits
+  // to pyproject.toml would prevent legitimate dependency changes.
+  // Shell / Style / Markdown
+  '.shellcheckrc',
+  '.stylelintrc',
+  '.stylelintrc.json',
+  '.stylelintrc.yml',
+  '.markdownlint.json',
+  '.markdownlint.yaml',
+  '.markdownlintrc',
+]);
+
+function parseInput(inputOrRaw) {
+  if (typeof inputOrRaw === 'string') {
+    try {
+      return inputOrRaw.trim() ? JSON.parse(inputOrRaw) : {};
+    } catch {
+      return {};
+    }
+  }
+
+  return inputOrRaw && typeof inputOrRaw === 'object' ? inputOrRaw : {};
+}
+
+/**
+ * Exportable run() for in-process execution via run-with-flags.js.
+ * Avoids the ~50-100ms spawnSync overhead when available.
+ */
+function run(inputOrRaw, options = {}) {
+  if (options.truncated) {
+    return {
+      exitCode: 2,
+      stderr:
+        `BLOCKED: Hook input exceeded ${options.maxStdin || MAX_STDIN} bytes. ` +
+        'Refusing to bypass config-protection on a truncated payload. ' +
+        'Retry with a smaller edit or disable the config-protection hook temporarily.'
+    };
+  }
+
+  const input = parseInput(inputOrRaw);
+  const filePath = input?.tool_input?.file_path || input?.tool_input?.file || '';
+  if (!filePath) return { exitCode: 0 };
+
+  const basename = path.basename(filePath);
+  if (PROTECTED_FILES.has(basename)) {
+    return {
+      exitCode: 2,
+      stderr:
+        `BLOCKED: Modifying ${basename} is not allowed. ` +
+        'Fix the source code to satisfy linter/formatter rules instead of ' +
+        'weakening the config. If this is a legitimate config change, ' +
+        'disable the config-protection hook temporarily.',
+    };
+  }
+
+  return { exitCode: 0 };
+}
+
+module.exports = { run };
+
+// Stdin fallback for spawnSync execution
+let truncated = /^(1|true|yes)$/i.test(String(process.env.ECC_HOOK_INPUT_TRUNCATED || ''));
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => {
+  if (raw.length < MAX_STDIN) {
+    const remaining = MAX_STDIN - raw.length;
+    raw += chunk.substring(0, remaining);
+    if (chunk.length > remaining) truncated = true;
+  } else {
+    truncated = true;
+  }
+});
+
+process.stdin.on('end', () => {
+  const result = run(raw, {
+    truncated,
+    maxStdin: Number(process.env.ECC_HOOK_INPUT_MAX_BYTES) || MAX_STDIN,
+  });
+
+  if (result.stderr) {
+    process.stderr.write(result.stderr + '\n');
+  }
+
+  if (result.exitCode === 2) {
+    process.exit(2);
+  }
+
+  process.stdout.write(raw);
+});

package/scripts/hooks/cost-tracker.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+/**
+ * Cost Tracker Hook
+ *
+ * Appends lightweight session usage metrics to ~/.claude/metrics/costs.jsonl.
+ */
+
+'use strict';
+
+const path = require('path');
+const {
+  ensureDir,
+  appendFile,
+  getClaudeDir,
+} = require('../lib/utils');
+
+const MAX_STDIN = 1024 * 1024;
+let raw = '';
+
+function toNumber(value) {
+  const n = Number(value);
+  return Number.isFinite(n) ? n : 0;
+}
+
+function estimateCost(model, inputTokens, outputTokens) {
+  // Approximate per-1M-token blended rates. Conservative defaults.
+  const table = {
+    'haiku': { in: 0.8, out: 4.0 },
+    'sonnet': { in: 3.0, out: 15.0 },
+    'opus': { in: 15.0, out: 75.0 },
+  };
+
+  const normalized = String(model || '').toLowerCase();
+  let rates = table.sonnet;
+  if (normalized.includes('haiku')) rates = table.haiku;
+  if (normalized.includes('opus')) rates = table.opus;
+
+  const cost = (inputTokens / 1_000_000) * rates.in + (outputTokens / 1_000_000) * rates.out;
+  return Math.round(cost * 1e6) / 1e6;
+}
+
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => {
+  if (raw.length < MAX_STDIN) {
+    const remaining = MAX_STDIN - raw.length;
+    raw += chunk.substring(0, remaining);
+  }
+});
+
+process.stdin.on('end', () => {
+  try {
+    const input = raw.trim() ? JSON.parse(raw) : {};
+    const usage = input.usage || input.token_usage || {};
+    const inputTokens = toNumber(usage.input_tokens || usage.prompt_tokens || 0);
+    const outputTokens = toNumber(usage.output_tokens || usage.completion_tokens || 0);
+
+    const model = String(input.model || input._cursor?.model || process.env.CLAUDE_MODEL || 'unknown');
+    const sessionId = String(process.env.CLAUDE_SESSION_ID || 'default');
+
+    const metricsDir = path.join(getClaudeDir(), 'metrics');
+    ensureDir(metricsDir);
+
+    const row = {
+      timestamp: new Date().toISOString(),
+      session_id: sessionId,
+      model,
+      input_tokens: inputTokens,
+      output_tokens: outputTokens,
+      estimated_cost_usd: estimateCost(model, inputTokens, outputTokens),
+    };
+
+    appendFile(path.join(metricsDir, 'costs.jsonl'), `${JSON.stringify(row)}\n`);
+  } catch {
+    // Keep hook non-blocking.
+  }
+
+  process.stdout.write(raw);
+});

package/scripts/hooks/design-quality-check.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+/**
+ * PostToolUse hook: lightweight frontend design-quality reminder.
+ *
+ * This stays self-contained inside ECC. It does not call remote models or
+ * install packages. The goal is to catch obviously generic UI drift and keep
+ * frontend edits aligned with ECC's stronger design standards.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const FRONTEND_EXTENSIONS = /\.(astro|css|html|jsx|scss|svelte|tsx|vue)$/i;
+const MAX_STDIN = 1024 * 1024;
+
+const GENERIC_SIGNALS = [
+  { pattern: /\bget started\b/i, label: '"Get Started" CTA copy' },
+  { pattern: /\blearn more\b/i, label: '"Learn more" CTA copy' },
+  { pattern: /\bgrid-cols-(3|4)\b/, label: 'uniform multi-card grid' },
+  { pattern: /\bbg-gradient-to-[trbl]/, label: 'stock gradient utility usage' },
+  { pattern: /\btext-center\b/, label: 'centered default layout cues' },
+  { pattern: /\bfont-(sans|inter)\b/i, label: 'default font utility' },
+];
+
+const CHECKLIST = [
+  'visual hierarchy with real contrast',
+  'intentional spacing rhythm',
+  'depth, layering, or overlap',
+  'purposeful hover and focus states',
+  'color and typography that feel specific',
+];
+
+function getFilePaths(input) {
+  const toolInput = input?.tool_input || {};
+  if (toolInput.file_path) {
+    return [String(toolInput.file_path)];
+  }
+
+  if (Array.isArray(toolInput.edits)) {
+    return toolInput.edits
+      .map(edit => String(edit?.file_path || ''))
+      .filter(Boolean);
+  }
+
+  return [];
+}
+
+function readContent(filePath) {
+  try {
+    return fs.readFileSync(path.resolve(filePath), 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+function detectSignals(content) {
+  return GENERIC_SIGNALS.filter(signal => signal.pattern.test(content)).map(signal => signal.label);
+}
+
+function buildWarning(frontendPaths, findings) {
+  const pathLines = frontendPaths.map(fp => `  - ${fp}`).join('\n');
+  const signalLines = findings.length > 0
+    ? findings.map(item => `  - ${item}`).join('\n')
+    : '  - no obvious canned-template strings detected';
+
+  return [
+    '[Hook] DESIGN CHECK: frontend file(s) modified:',
+    pathLines,
+    '[Hook] Review for generic/template drift. Frontend should have:',
+    CHECKLIST.map(item => `  - ${item}`).join('\n'),
+    '[Hook] Heuristic signals:',
+    signalLines,
+  ].join('\n');
+}
+
+function run(inputOrRaw) {
+  let input;
+  let rawInput = inputOrRaw;
+
+  try {
+    if (typeof inputOrRaw === 'string') {
+      rawInput = inputOrRaw;
+      input = inputOrRaw.trim() ? JSON.parse(inputOrRaw) : {};
+    } else {
+      input = inputOrRaw || {};
+      rawInput = JSON.stringify(inputOrRaw ?? {});
+    }
+  } catch {
+    return { exitCode: 0, stdout: typeof rawInput === 'string' ? rawInput : '' };
+  }
+
+  const filePaths = getFilePaths(input);
+  const frontendPaths = filePaths.filter(filePath => FRONTEND_EXTENSIONS.test(filePath));
+
+  if (frontendPaths.length === 0) {
+    return { exitCode: 0, stdout: typeof rawInput === 'string' ? rawInput : '' };
+  }
+
+  const findings = [];
+  for (const filePath of frontendPaths) {
+    const content = readContent(filePath);
+    findings.push(...detectSignals(content));
+  }
+
+  return {
+    exitCode: 0,
+    stdout: typeof rawInput === 'string' ? rawInput : '',
+    stderr: buildWarning(frontendPaths, findings),
+  };
+}
+
+module.exports = { run };
+
+if (require.main === module) {
+  let raw = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => {
+    if (raw.length < MAX_STDIN) {
+      const remaining = MAX_STDIN - raw.length;
+      raw += chunk.substring(0, remaining);
+    }
+  });
+  process.stdin.on('end', () => {
+    const result = run(raw);
+    if (result.stderr) process.stderr.write(`${result.stderr}\n`);
+    process.stdout.write(typeof result.stdout === 'string' ? result.stdout : raw);
+    process.exit(Number.isInteger(result.exitCode) ? result.exitCode : 0);
+  });
+}