kodelyth-ecc 1.2.0

package/dashboard/server.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+// Kodelyth Lens — AI Coding Agent Dashboard
+// Part of Kodelyth ECC — github.com/sifxprime/kodelyth-ecc
+// Tracks usage across Claude Code, Cursor, Windsurf, Codex, Antigravity
+
+import http      from 'node:http';
+import fs        from 'node:fs';
+import path      from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { aggregateAll } from './lib/aggregator.js';
+
+// Load .env if present
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const envFile   = path.join(__dirname, '.env');
+if (fs.existsSync(envFile)) {
+  for (const line of fs.readFileSync(envFile, 'utf-8').split('\n')) {
+    const m = line.match(/^([^#=\s]+)\s*=\s*(.*)$/);
+    if (m && !process.env[m[1]]) process.env[m[1]] = m[2].trim().replace(/^["']|["']$/g, '');
+  }
+}
+
+const PORT    = parseInt(process.env.PORT || '3456', 10);
+const PUBLIC  = path.join(__dirname, 'public');
+const CACHE_TTL = 30_000; // 30 seconds
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.css':  'text/css',
+  '.js':   'application/javascript',
+  '.json': 'application/json',
+  '.svg':  'image/svg+xml',
+  '.ico':  'image/x-icon',
+};
+
+// Simple in-memory cache
+let _cache = { data: null, ts: 0 };
+
+async function getData(force = false) {
+  const now = Date.now();
+  if (!force && _cache.data && now - _cache.ts < CACHE_TTL) return _cache.data;
+  _cache.data = await aggregateAll();
+  _cache.ts   = now;
+  return _cache.data;
+}
+
+const server = http.createServer(async (req, res) => {
+  const url = new URL(req.url, `http://localhost:${PORT}`);
+
+  // ── API ──────────────────────────────────────────────────────────────────
+  if (url.pathname.startsWith('/api/')) {
+    res.setHeader('Content-Type', 'application/json');
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Cache-Control', 'no-cache');
+
+    try {
+      const force = url.searchParams.get('refresh') === '1';
+      const data  = await getData(force);
+
+      const routes = {
+        '/api/all':       () => data,
+        '/api/stats':     () => data.stats,
+        '/api/agents':    () => data.agents,
+        '/api/sessions':  () => data.sessions,
+        '/api/costs':     () => data.costs,
+        '/api/platforms': () => data.platforms,
+      };
+
+      const handler = routes[url.pathname];
+      if (handler) {
+        res.end(JSON.stringify(handler()));
+      } else {
+        res.statusCode = 404;
+        res.end(JSON.stringify({ error: 'Not found' }));
+      }
+    } catch (err) {
+      res.statusCode = 500;
+      res.end(JSON.stringify({ error: err.message }));
+    }
+    return;
+  }
+
+  // ── Static files ─────────────────────────────────────────────────────────
+  let file = url.pathname === '/' ? 'index.html' : url.pathname.slice(1);
+  const filePath = path.resolve(PUBLIC, file);
+
+  // Prevent path traversal attacks
+  if (!filePath.startsWith(PUBLIC + path.sep) && filePath !== path.resolve(PUBLIC, 'index.html')) {
+    res.writeHead(403, { 'Content-Type': 'text/plain' });
+    res.end('Forbidden');
+    return;
+  }
+
+  if (fs.existsSync(filePath) && fs.statSync(filePath).isFile()) {
+    const ext = path.extname(filePath);
+    res.setHeader('Content-Type', MIME[ext] || 'text/plain');
+    res.end(fs.readFileSync(filePath));
+  } else {
+    // SPA fallback
+    res.setHeader('Content-Type', 'text/html; charset=utf-8');
+    res.end(fs.readFileSync(path.join(PUBLIC, 'index.html')));
+  }
+});
+
+server.listen(PORT, () => {
+  console.log('');
+  console.log('  \x1b[36m\x1b[1m██╗  ██╗ ██████╗ ██████╗ ███████╗██╗  ██╗   ██╗████████╗██╗  ██╗\x1b[0m');
+  console.log('  \x1b[36m\x1b[1m██║ ██╔╝██╔═══██╗██╔══██╗██╔════╝██║  ╚██╗ ██╔╝╚══██╔══╝██║  ██║\x1b[0m');
+  console.log('  \x1b[36m\x1b[1m█████╔╝ ██║   ██║██║  ██║█████╗  ██║   ╚████╔╝    ██║   ███████║\x1b[0m');
+  console.log('  \x1b[36m\x1b[1m██╔═██╗ ██║   ██║██║  ██║██╔══╝  ██║    ╚██╔╝     ██║   ██╔══██║\x1b[0m');
+  console.log('  \x1b[36m\x1b[1m██║  ██╗╚██████╔╝██████╔╝███████╗███████╗██║       ██║   ██║  ██║\x1b[0m');
+  console.log('  \x1b[36m\x1b[1m╚═╝  ╚═╝ ╚═════╝ ╚═════╝ ╚══════╝╚══════╝╚═╝       ╚═╝   ╚═╝  ╚═╝\x1b[0m');
+  console.log('');
+  console.log('  \x1b[1mKodelyth Lens\x1b[0m — AI Coding Agent Dashboard');
+  console.log(`  \x1b[32m\x1b[1m→ http://localhost:${PORT}\x1b[0m`);
+  console.log('');
+  console.log('  Tracking: Claude Code · Cursor · Windsurf · Codex · OpenCode · Antigravity');
+  console.log('  Press Ctrl+C to stop.');
+  console.log('');
+});

package/hooks/README.md

@@ -0,0 +1,220 @@
+# Hooks
+
+Hooks are event-driven automations that fire before or after Claude Code tool executions. They enforce code quality, catch mistakes early, and automate repetitive checks.
+
+## How Hooks Work
+
+```
+User request → Claude picks a tool → PreToolUse hook runs → Tool executes → PostToolUse hook runs
+```
+
+- **PreToolUse** hooks run before the tool executes. They can **block** (exit code 2) or **warn** (stderr without blocking).
+- **PostToolUse** hooks run after the tool completes. They can analyze output but cannot block.
+- **Stop** hooks run after each Claude response.
+- **SessionStart/SessionEnd** hooks run at session lifecycle boundaries.
+- **PreCompact** hooks run before context compaction, useful for saving state.
+
+## Hooks in This Plugin
+
+### PreToolUse Hooks
+
+| Hook | Matcher | Behavior | Exit Code |
+|------|---------|----------|-----------|
+| **Dev server blocker** | `Bash` | Blocks `npm run dev` etc. outside tmux — ensures log access | 2 (blocks) |
+| **Tmux reminder** | `Bash` | Suggests tmux for long-running commands (npm test, cargo build, docker) | 0 (warns) |
+| **Git push reminder** | `Bash` | Reminds to review changes before `git push` | 0 (warns) |
+| **Pre-commit quality check** | `Bash` | Runs quality checks before `git commit`: lints staged files, validates commit message format when provided via `-m/--message`, detects console.log/debugger/secrets | 2 (blocks critical) / 0 (warns) |
+| **Doc file warning** | `Write` | Warns about non-standard `.md`/`.txt` files (allows README, CLAUDE, CONTRIBUTING, CHANGELOG, LICENSE, SKILL, docs/, skills/); cross-platform path handling | 0 (warns) |
+| **Strategic compact** | `Edit\|Write` | Suggests manual `/compact` at logical intervals (every ~50 tool calls) | 0 (warns) |
+### PostToolUse Hooks
+
+| Hook | Matcher | What It Does |
+|------|---------|-------------|
+| **PR logger** | `Bash` | Logs PR URL and review command after `gh pr create` |
+| **Build analysis** | `Bash` | Background analysis after build commands (async, non-blocking) |
+| **Quality gate** | `Edit\|Write\|MultiEdit` | Runs fast quality checks after edits |
+| **Design quality check** | `Edit\|Write\|MultiEdit` | Warns when frontend edits drift toward generic template-looking UI |
+| **Prettier format** | `Edit` | Auto-formats JS/TS files with Prettier after edits |
+| **TypeScript check** | `Edit` | Runs `tsc --noEmit` after editing `.ts`/`.tsx` files |
+| **console.log warning** | `Edit` | Warns about `console.log` statements in edited files |
+
+### Lifecycle Hooks
+
+| Hook | Event | What It Does |
+|------|-------|-------------|
+| **Session start** | `SessionStart` | Loads previous context and detects package manager |
+| **Pre-compact** | `PreCompact` | Saves state before context compaction |
+| **Console.log audit** | `Stop` | Checks all modified files for `console.log` after each response |
+| **Session summary** | `Stop` | Persists session state when transcript path is available |
+| **Pattern extraction** | `Stop` | Evaluates session for extractable patterns (continuous learning) |
+| **Cost tracker** | `Stop` | Emits lightweight run-cost telemetry markers |
+| **Desktop notify** | `Stop` | Sends macOS desktop notification with task summary (standard+) |
+| **Session end marker** | `SessionEnd` | Lifecycle marker and cleanup log |
+
+## Customizing Hooks
+
+### Disabling a Hook
+
+Remove or comment out the hook entry in `hooks.json`. If installed as a plugin, override in your `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write",
+        "hooks": [],
+        "description": "Override: allow all .md file creation"
+      }
+    ]
+  }
+}
+```
+
+### Runtime Hook Controls (Recommended)
+
+Use environment variables to control hook behavior without editing `hooks.json`:
+
+```bash
+# minimal | standard | strict (default: standard)
+export ECC_HOOK_PROFILE=standard
+
+# Disable specific hook IDs (comma-separated)
+export ECC_DISABLED_HOOKS="pre:bash:tmux-reminder,post:edit:typecheck"
+```
+
+Profiles:
+- `minimal` — keep essential lifecycle and safety hooks only.
+- `standard` — default; balanced quality + safety checks.
+- `strict` — enables additional reminders and stricter guardrails.
+
+### Writing Your Own Hook
+
+Hooks are shell commands that receive tool input as JSON on stdin and must output JSON on stdout.
+
+**Basic structure:**
+
+```javascript
+// my-hook.js
+let data = '';
+process.stdin.on('data', chunk => data += chunk);
+process.stdin.on('end', () => {
+  const input = JSON.parse(data);
+
+  // Access tool info
+  const toolName = input.tool_name;        // "Edit", "Bash", "Write", etc.
+  const toolInput = input.tool_input;      // Tool-specific parameters
+  const toolOutput = input.tool_output;    // Only available in PostToolUse
+
+  // Warn (non-blocking): write to stderr
+  console.error('[Hook] Warning message shown to Claude');
+
+  // Block (PreToolUse only): exit with code 2
+  // process.exit(2);
+
+  // Always output the original data to stdout
+  console.log(data);
+});
+```
+
+**Exit codes:**
+- `0` — Success (continue execution)
+- `2` — Block the tool call (PreToolUse only)
+- Other non-zero — Error (logged but does not block)
+
+### Hook Input Schema
+
+```typescript
+interface HookInput {
+  tool_name: string;          // "Bash", "Edit", "Write", "Read", etc.
+  tool_input: {
+    command?: string;         // Bash: the command being run
+    file_path?: string;       // Edit/Write/Read: target file
+    old_string?: string;      // Edit: text being replaced
+    new_string?: string;      // Edit: replacement text
+    content?: string;         // Write: file content
+  };
+  tool_output?: {             // PostToolUse only
+    output?: string;          // Command/tool output
+  };
+}
+```
+
+### Async Hooks
+
+For hooks that should not block the main flow (e.g., background analysis):
+
+```json
+{
+  "type": "command",
+  "command": "node my-slow-hook.js",
+  "async": true,
+  "timeout": 30
+}
+```
+
+Async hooks run in the background. They cannot block tool execution.
+
+## Common Hook Recipes
+
+### Warn about TODO comments
+
+```json
+{
+  "matcher": "Edit",
+  "hooks": [{
+    "type": "command",
+    "command": "node -e \"let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const i=JSON.parse(d);const ns=i.tool_input?.new_string||'';if(/TODO|FIXME|HACK/.test(ns)){console.error('[Hook] New TODO/FIXME added - consider creating an issue')}console.log(d)})\""
+  }],
+  "description": "Warn when adding TODO/FIXME comments"
+}
+```
+
+### Block large file creation
+
+```json
+{
+  "matcher": "Write",
+  "hooks": [{
+    "type": "command",
+    "command": "node -e \"let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const i=JSON.parse(d);const c=i.tool_input?.content||'';const lines=c.split('\\n').length;if(lines>800){console.error('[Hook] BLOCKED: File exceeds 800 lines ('+lines+' lines)');console.error('[Hook] Split into smaller, focused modules');process.exit(2)}console.log(d)})\""
+  }],
+  "description": "Block creation of files larger than 800 lines"
+}
+```
+
+### Auto-format Python files with ruff
+
+```json
+{
+  "matcher": "Edit",
+  "hooks": [{
+    "type": "command",
+    "command": "node -e \"let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const i=JSON.parse(d);const p=i.tool_input?.file_path||'';if(/\\.py$/.test(p)){const{execFileSync}=require('child_process');try{execFileSync('ruff',['format',p],{stdio:'pipe'})}catch(e){}}console.log(d)})\""
+  }],
+  "description": "Auto-format Python files with ruff after edits"
+}
+```
+
+### Require test files alongside new source files
+
+```json
+{
+  "matcher": "Write",
+  "hooks": [{
+    "type": "command",
+    "command": "node -e \"const fs=require('fs');let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const i=JSON.parse(d);const p=i.tool_input?.file_path||'';if(/src\\/.*\\.(ts|js)$/.test(p)&&!/\\.test\\.|\\.spec\\./.test(p)){const testPath=p.replace(/\\.(ts|js)$/,'.test.$1');if(!fs.existsSync(testPath)){console.error('[Hook] No test file found for: '+p);console.error('[Hook] Expected: '+testPath);console.error('[Hook] Consider writing tests first (/tdd)')}}console.log(d)})\""
+  }],
+  "description": "Remind to create tests when adding new source files"
+}
+```
+
+## Cross-Platform Notes
+
+Hook logic is implemented in Node.js scripts for cross-platform behavior on Windows, macOS, and Linux. A small number of shell wrappers are retained for continuous-learning observer hooks; those wrappers are profile-gated and have Windows-safe fallback behavior.
+
+## Related
+
+- [rules/common/hooks.md](../rules/common/hooks.md) — Hook architecture guidelines
+- [skills/strategic-compact/](../skills/strategic-compact/) — Strategic compaction skill
+- [scripts/hooks/](../scripts/hooks/) — Hook script implementations