@massu/core 0.1.0 → 0.1.2

package/src/hooks/cost-tracker.ts

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+// ============================================================
+// PostToolUse Hook: Cost Tracker
+// Estimates token usage from tool input/output sizes and
+// records cost events for per-session cost intelligence.
+// Must complete in <500ms.
+// ============================================================
+
+import { getMemoryDb } from '../memory-db.ts';
+
+interface HookInput {
+  session_id: string;
+  transcript_path: string;
+  cwd: string;
+  hook_event_name: string;
+  tool_name: string;
+  tool_input: Record<string, unknown>;
+  tool_response: string;
+}
+
+// Approximate: 4 characters per token (industry rule of thumb)
+const CHARS_PER_TOKEN = 4;
+
+function estimateTokens(text: string): number {
+  return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+
+async function main(): Promise<void> {
+  try {
+    const input = await readStdin();
+    const hookInput = JSON.parse(input) as HookInput;
+    const { session_id, tool_name, tool_input, tool_response } = hookInput;
+
+    const inputStr = JSON.stringify(tool_input);
+    const estimatedInputTokens = estimateTokens(inputStr);
+    const estimatedOutputTokens = estimateTokens(tool_response ?? '');
+
+    const db = getMemoryDb();
+    try {
+      db.prepare(`
+        INSERT INTO tool_cost_events (session_id, tool_name, estimated_input_tokens, estimated_output_tokens, model)
+        VALUES (?, ?, ?, ?, ?)
+      `).run(session_id, tool_name, estimatedInputTokens, estimatedOutputTokens, '');
+    } finally {
+      db.close();
+    }
+  } catch (_e) {
+    // Best-effort: never block Claude Code
+  }
+  process.exit(0);
+}
+
+function readStdin(): Promise<string> {
+  return new Promise((resolve) => {
+    let data = '';
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (chunk: string) => { data += chunk; });
+    process.stdin.on('end', () => resolve(data));
+    setTimeout(() => resolve(data), 3000);
+  });
+}
+
+main();

package/src/hooks/intent-suggester.ts

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+// ============================================================
+// UserPromptSubmit Hook: Intent Suggester
+// Matches prompt keywords to relevant slash commands and
+// surfaces suggestions to the user as a non-blocking hint.
+// ============================================================
+
+// Force module mode for TypeScript (no external deps needed)
+export {};
+
+interface HookInput {
+  session_id: string;
+  transcript_path: string;
+  cwd: string;
+  hook_event_name: string;
+  prompt: string;
+}
+
+interface CommandMapping {
+  keywords: string[];
+  command: string;
+  description: string;
+}
+
+const COMMAND_MAPPINGS: CommandMapping[] = [
+  {
+    keywords: ['test', 'failing'],
+    command: '/massu-test',
+    description: 'Run and analyze tests',
+  },
+  {
+    keywords: ['debug', 'bug'],
+    command: '/massu-debug',
+    description: 'Debug an issue',
+  },
+  {
+    keywords: ['refactor'],
+    command: '/massu-refactor',
+    description: 'Guided refactoring workflow',
+  },
+  {
+    keywords: ['cleanup', 'dead code', 'unused'],
+    command: '/massu-cleanup',
+    description: 'Clean up dead code and unused exports',
+  },
+  {
+    keywords: ['document', 'jsdoc', 'readme'],
+    command: '/massu-doc-gen',
+    description: 'Generate documentation',
+  },
+  {
+    keywords: ['estimate', 'effort', 'how long'],
+    command: '/massu-estimate',
+    description: 'Estimate implementation effort',
+  },
+  {
+    keywords: ['release', 'deploy'],
+    command: '/massu-release',
+    description: 'Prepare a release',
+  },
+  {
+    keywords: ['commit'],
+    command: '/massu-commit',
+    description: 'Pre-commit verification gate',
+  },
+  {
+    keywords: ['push'],
+    command: '/massu-push',
+    description: 'Pre-push full verification gate',
+  },
+  {
+    keywords: ['plan'],
+    command: '/massu-create-plan',
+    description: 'Create an implementation plan',
+  },
+];
+
+function findMatchingCommand(prompt: string): CommandMapping | null {
+  const lowerPrompt = prompt.toLowerCase();
+
+  for (const mapping of COMMAND_MAPPINGS) {
+    for (const keyword of mapping.keywords) {
+      if (lowerPrompt.includes(keyword.toLowerCase())) {
+        return mapping;
+      }
+    }
+  }
+
+  return null;
+}
+
+async function main(): Promise<void> {
+  try {
+    const input = await readStdin();
+    const hookInput = JSON.parse(input) as HookInput;
+    const { prompt } = hookInput;
+
+    if (!prompt || !prompt.trim()) {
+      process.exit(0);
+      return;
+    }
+
+    const match = findMatchingCommand(prompt);
+    if (!match) {
+      process.exit(0);
+      return;
+    }
+
+    process.stdout.write(
+      `Tip: Use ${match.command} to ${match.description}.`
+    );
+  } catch (_e) {
+    // Best-effort: never block Claude Code
+  }
+  process.exit(0);
+}
+
+function readStdin(): Promise<string> {
+  return new Promise((resolve) => {
+    let data = '';
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (chunk: string) => { data += chunk; });
+    process.stdin.on('end', () => resolve(data));
+    setTimeout(() => resolve(data), 3000);
+  });
+}
+
+main();

package/src/hooks/post-edit-context.ts

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+// ============================================================
+// PostToolUse Context Hook
+// Surfaces applicable CLAUDE.md rules and warnings when editing
+// src/ files. Uses matchRules() and isInMiddlewareTree() from
+// the codegraph index - no MCP server HTTP call needed.
+// Must complete in <500ms.
+// ============================================================
+
+import Database from 'better-sqlite3';
+import { matchRules } from '../rules.ts';
+import { isInMiddlewareTree } from '../middleware-tree.ts';
+import { getResolvedPaths, getProjectRoot } from '../config.ts';
+
+interface HookInput {
+  session_id: string;
+  tool_name: string;
+  tool_input: { file_path?: string };
+}
+
+async function main(): Promise<void> {
+  try {
+    const input = await readStdin();
+    const hookInput = JSON.parse(input) as HookInput;
+    const filePath = hookInput.tool_input?.file_path;
+
+    if (!filePath) {
+      process.exit(0);
+      return;
+    }
+
+    // Convert absolute path to relative
+    const root = getProjectRoot();
+    const rel = filePath.startsWith(root + '/') ? filePath.slice(root.length + 1) : filePath;
+
+    // Only process src/ files
+    if (!rel.startsWith('src/')) {
+      process.exit(0);
+      return;
+    }
+
+    const warnings: string[] = [];
+
+    // 1. Check applicable rules (uses rules.ts PATTERN_RULES)
+    const rules = matchRules(rel);
+    for (const rule of rules) {
+      if (rule.severity === 'CRITICAL' || rule.severity === 'HIGH') {
+        for (const r of rule.rules) {
+          warnings.push(`[${rule.severity}] ${r}`);
+        }
+      }
+    }
+
+    // 2. Check middleware tree membership
+    try {
+      const dataDb = new Database(getResolvedPaths().dataDbPath, { readonly: true });
+      try {
+        if (isInMiddlewareTree(dataDb, rel)) {
+          warnings.push('[CRITICAL] This file is in the middleware import tree. No Node.js deps allowed.');
+        }
+      } finally {
+        dataDb.close();
+      }
+    } catch (_e) {
+      // DB may not exist yet - skip middleware check
+    }
+
+    // 3. Output warnings if any
+    if (warnings.length > 0) {
+      console.log(`[Massu] ${warnings.join(' | ')}`);
+    }
+  } catch (_e) {
+    // Best-effort: never block Claude Code
+  }
+  process.exit(0);
+}
+
+function readStdin(): Promise<string> {
+  return new Promise((resolve) => {
+    let data = '';
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (chunk: string) => { data += chunk; });
+    process.stdin.on('end', () => resolve(data));
+    setTimeout(() => resolve(data), 3000);
+  });
+}
+
+main();

package/src/hooks/post-tool-use.ts

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+// ============================================================
+// P3-002: PostToolUse Observation Hook
+// Captures tool usage as observations (lightweight, no AI needed).
+// Must complete in <500ms.
+// ============================================================
+
+import { getMemoryDb, addObservation, createSession, deduplicateFailedAttempt, addSummary } from '../memory-db.ts';
+import { classifyRealTimeToolCall, detectPlanProgress } from '../observation-extractor.ts';
+import { logAuditEntry } from '../audit-trail.ts';
+import { trackModification } from '../regression-detector.ts';
+import { validateFile, storeValidationResult } from '../validation-engine.ts';
+import { scoreFileSecurity, storeSecurityScore } from '../security-scorer.ts';
+
+interface HookInput {
+  session_id: string;
+  transcript_path: string;
+  cwd: string;
+  hook_event_name: string;
+  tool_name: string;
+  tool_input: Record<string, unknown>;
+  tool_response: string;
+}
+
+// In-memory dedup for Read calls within this session
+const seenReads = new Set<string>();
+let currentSessionId: string | null = null;
+
+async function main(): Promise<void> {
+  try {
+    const input = await readStdin();
+    const hookInput = JSON.parse(input) as HookInput;
+    const { session_id, tool_name, tool_input, tool_response } = hookInput;
+
+    // Reset seen reads if session changed
+    if (currentSessionId !== session_id) {
+      seenReads.clear();
+      currentSessionId = session_id;
+    }
+
+    const db = getMemoryDb();
+    try {
+      // Ensure session exists
+      createSession(db, session_id);
+
+      // Classify and filter
+      const observation = classifyRealTimeToolCall(tool_name, tool_input, tool_response, seenReads);
+      if (!observation) {
+        process.exit(0);
+        return;
+      }
+
+      // Deduplicate failed attempts
+      if (observation.type === 'failed_attempt') {
+        deduplicateFailedAttempt(db, session_id, observation.title, observation.detail, observation.opts);
+      } else {
+        addObservation(db, session_id, observation.type, observation.title, observation.detail, observation.opts);
+      }
+
+      // Auto-detect plan progress
+      if (tool_response) {
+        const progress = detectPlanProgress(tool_response);
+        if (progress.length > 0) {
+          // Update plan_progress in session summary
+          updatePlanProgress(db, session_id, progress);
+        }
+      }
+
+      // Audit trail logging for file changes
+      try {
+        if (tool_name === 'Edit' || tool_name === 'Write') {
+          const filePath = (tool_input.file_path as string) ?? '';
+          logAuditEntry(db, {
+            sessionId: session_id,
+            eventType: 'code_change',
+            actor: 'ai',
+            filePath,
+            changeType: tool_name === 'Write' ? 'create' : 'edit',
+          });
+
+          // Track modification for regression detection
+          if (filePath) {
+            const featureMatch = filePath.match(/(?:routers|components|app\/\(([^)]+)\))\/([^/.]+)/);
+            if (featureMatch) {
+              const featureKey = featureMatch[1] ?? featureMatch[2];
+              trackModification(db, featureKey);
+            }
+          }
+        }
+      } catch (_auditErr) {
+        // Best-effort: never block post-tool-use
+      }
+
+      // Real-time validation for Edit/Write
+      try {
+        if (tool_name === 'Edit' || tool_name === 'Write') {
+          const filePath = (tool_input.file_path as string) ?? '';
+          if (filePath && (filePath.endsWith('.ts') || filePath.endsWith('.tsx'))) {
+            const projectRoot = hookInput.cwd;
+            const checks = validateFile(filePath, projectRoot);
+            const violations = checks.filter(c => c.severity === 'error' || c.severity === 'critical');
+            if (violations.length > 0) {
+              storeValidationResult(db, filePath, checks, session_id);
+            }
+          }
+        }
+      } catch (_validationErr) {
+        // Best-effort: never block post-tool-use
+      }
+
+      // Auto-security scoring for router/API files
+      try {
+        if (tool_name === 'Edit' || tool_name === 'Write') {
+          const filePath = (tool_input.file_path as string) ?? '';
+          if (filePath && (filePath.includes('routers/') || filePath.includes('api/'))) {
+            const projectRoot = hookInput.cwd;
+            const { riskScore, findings } = scoreFileSecurity(filePath, projectRoot);
+            if (findings.length > 0) {
+              storeSecurityScore(db, session_id, filePath, riskScore, findings);
+            }
+          }
+        }
+      } catch (_securityErr) {
+        // Best-effort: never block post-tool-use
+      }
+    } finally {
+      db.close();
+    }
+  } catch (_e) {
+    // Best-effort: never block Claude Code
+  }
+  process.exit(0);
+}
+
+function updatePlanProgress(db: import('better-sqlite3').Database, sessionId: string, progress: Array<{ planItem: string; status: string }>): void {
+  // Get or create latest summary's plan_progress
+  const existing = db.prepare(
+    'SELECT id, plan_progress FROM session_summaries WHERE session_id = ? ORDER BY created_at_epoch DESC LIMIT 1'
+  ).get(sessionId) as { id: number; plan_progress: string } | undefined;
+
+  if (existing) {
+    try {
+      const currentProgress = JSON.parse(existing.plan_progress) as Record<string, string>;
+      for (const p of progress) {
+        currentProgress[p.planItem] = p.status;
+      }
+      db.prepare('UPDATE session_summaries SET plan_progress = ? WHERE id = ?')
+        .run(JSON.stringify(currentProgress), existing.id);
+    } catch (_e) {
+      // Skip if JSON parse fails
+    }
+  } else {
+    // Create a minimal summary with plan progress
+    const progressMap: Record<string, string> = {};
+    for (const p of progress) {
+      progressMap[p.planItem] = p.status;
+    }
+    addSummary(db, sessionId, { planProgress: progressMap });
+  }
+}
+
+function readStdin(): Promise<string> {
+  return new Promise((resolve) => {
+    let data = '';
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (chunk: string) => { data += chunk; });
+    process.stdin.on('end', () => resolve(data));
+    setTimeout(() => resolve(data), 3000);
+  });
+}
+
+main();

package/src/hooks/pre-compact.ts

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+// ============================================================
+// P3-006: PreCompact State Snapshot Hook
+// Captures current session state into DB before compaction destroys context.
+// ============================================================
+
+import { getMemoryDb, addSummary, createSession } from '../memory-db.ts';
+import { logAuditEntry } from '../audit-trail.ts';
+import type { SessionSummary } from '../memory-db.ts';
+
+interface HookInput {
+  session_id: string;
+  transcript_path: string;
+  cwd: string;
+  hook_event_name: string;
+}
+
+async function main(): Promise<void> {
+  try {
+    const input = await readStdin();
+    const hookInput = JSON.parse(input) as HookInput;
+    const { session_id } = hookInput;
+
+    const db = getMemoryDb();
+    try {
+      // Ensure session exists
+      createSession(db, session_id);
+
+      // 1. Get all observations for this session
+      const observations = db.prepare(
+        'SELECT * FROM observations WHERE session_id = ? ORDER BY created_at_epoch ASC'
+      ).all(session_id) as Array<Record<string, unknown>>;
+
+      // 2. Get user prompts
+      const prompts = db.prepare(
+        'SELECT prompt_text FROM user_prompts WHERE session_id = ? ORDER BY prompt_number ASC'
+      ).all(session_id) as Array<{ prompt_text: string }>;
+
+      // 3. Generate mid-session summary snapshot
+      const summary = buildSnapshotSummary(observations, prompts);
+
+      // 4. Store with pre_compact marker in plan_progress
+      addSummary(db, session_id, summary);
+
+      // Log compaction event for audit trail continuity
+      try {
+        logAuditEntry(db, {
+          sessionId: session_id,
+          eventType: 'compaction',
+          actor: 'hook',
+          metadata: { observations_count: observations.length, prompts_count: prompts.length },
+        });
+      } catch (_auditErr) {
+        // Best-effort: never block compaction
+      }
+    } finally {
+      db.close();
+    }
+  } catch (_e) {
+    // Best-effort: never block Claude Code
+  }
+  process.exit(0);
+}
+
+function buildSnapshotSummary(
+  observations: Array<Record<string, unknown>>,
+  prompts: Array<{ prompt_text: string }>
+): SessionSummary {
+  const request = prompts[0]?.prompt_text?.slice(0, 500) ?? undefined;
+
+  const completed = observations
+    .filter(o => ['feature', 'bugfix', 'refactor'].includes(o.type as string))
+    .map(o => `- ${o.title}`)
+    .join('\n');
+
+  const failedAttempts = observations
+    .filter(o => o.type === 'failed_attempt')
+    .map(o => `- ${o.title}`)
+    .join('\n');
+
+  const decisions = observations
+    .filter(o => o.type === 'decision')
+    .map(o => `- ${o.title}`)
+    .join('\n');
+
+  // Collect file changes
+  const filesCreated: string[] = [];
+  const filesModified: string[] = [];
+  for (const o of observations) {
+    if (o.type !== 'file_change') continue;
+    const files = safeParseJson(o.files_involved as string, []) as string[];
+    const title = o.title as string;
+    if (title.startsWith('Created')) filesCreated.push(...files);
+    else if (title.startsWith('Edited')) filesModified.push(...files);
+  }
+
+  // Collect plan progress
+  const planProgress: Record<string, string> = { snapshot_type: 'pre_compact' };
+  for (const o of observations) {
+    if (!o.plan_item) continue;
+    planProgress[o.plan_item as string] = 'in_progress';
+  }
+
+  // Verification results
+  const verificationResults: Record<string, string> = {};
+  for (const o of observations) {
+    if (o.type !== 'vr_check') continue;
+    const vrType = o.vr_type as string;
+    const passed = (o.title as string).includes('PASS');
+    if (vrType) verificationResults[vrType] = passed ? 'PASS' : 'FAIL';
+  }
+
+  return {
+    request,
+    completed: completed || undefined,
+    failedAttempts: failedAttempts || undefined,
+    decisions: decisions || undefined,
+    filesCreated: [...new Set(filesCreated)],
+    filesModified: [...new Set(filesModified)],
+    verificationResults,
+    planProgress,
+  };
+}
+
+function safeParseJson(json: string, fallback: unknown): unknown {
+  try {
+    return JSON.parse(json);
+  } catch (_e) {
+    return fallback;
+  }
+}
+
+function readStdin(): Promise<string> {
+  return new Promise((resolve) => {
+    let data = '';
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (chunk: string) => { data += chunk; });
+    process.stdin.on('end', () => resolve(data));
+    setTimeout(() => resolve(data), 3000);
+  });
+}
+
+main();