anvil-dev-framework 0.1.6

package/global/hooks/anvil_memory_observe.ts

@@ -0,0 +1,322 @@
+#!/usr/bin/env bun
+/**
+ * PostToolUse Hook - Auto-capture observations from tool output
+ *
+ * Claude Code Hook Type: PostToolUse
+ * Purpose: Analyze tool output and create observations for significant events
+ *
+ * Input: JSON from stdin with tool_name, tool_input, tool_result
+ * Output: Empty JSON (hook doesn't modify response)
+ *
+ * Performance target: <100ms (non-blocking)
+ */
+
+import { AnvilMemoryDb, dbExists, getDefaultDbPath } from '../tools/anvil-memory/src/db.ts';
+import type { ObservationType } from '../tools/anvil-memory/src/types.ts';
+import { basename } from 'path';
+
+// Tools to skip (low-value for observation capture)
+const SKIP_TOOLS = new Set([
+  'TodoWrite',
+  'AskUserQuestion',
+  'ListMcpResourcesTool',
+  'SlashCommand',
+  'Skill',
+  'ExitPlanMode',
+  'EnterPlanMode',
+  'Glob',
+  'Grep',
+  'LS',
+  'TaskOutput',
+  'KillShell',
+]);
+
+// Keywords for classifying observation types
+const TYPE_KEYWORDS: Record<ObservationType, string[]> = {
+  bugfix: ['fix', 'bug', 'error', 'issue', 'broken', 'crash', 'fail', 'wrong'],
+  feature: ['add', 'implement', 'create', 'new feature', 'feat'],
+  refactor: ['refactor', 'restructure', 'reorganize', 'clean up', 'simplify'],
+  discovery: ['found', 'discover', 'notice', 'observe', 'see that', 'realize'],
+  decision: ['decide', 'choose', 'pick', 'select', 'option', 'approach'],
+  change: ['update', 'modify', 'change', 'edit', 'alter'],
+  checkpoint: ['checkpoint', 'save point', 'snapshot'],
+  ralph_iteration: ['ralph', 'iteration', 'loop'],
+  handoff: ['handoff', 'handover', 'transfer'],
+  shard: ['shard', 'split', 'break down'],
+  linear_sync: ['linear', 'issue', 'ticket'],
+  session_request: ['session', 'request', 'user asked'],
+};
+
+interface PostToolUseInput {
+  tool_name: string;
+  tool_input?: Record<string, unknown>;
+  tool_result?: string;
+  session_id?: string;
+}
+
+/**
+ * Determines if a tool output is significant enough to capture as an observation.
+ * Filters out low-value tools, empty results, and most Read operations.
+ * Write/Edit operations, modifying Bash commands, Task results, and web operations
+ * are considered significant.
+ *
+ * @param input - The PostToolUseInput containing tool_name, tool_input, and tool_result
+ * @returns true if the tool output should be captured as an observation, false otherwise
+ */
+function isSignificant(input: PostToolUseInput): boolean {
+  const { tool_name, tool_result } = input;
+
+  // Skip certain tools entirely
+  if (SKIP_TOOLS.has(tool_name)) {
+    return false;
+  }
+
+  // Skip if no result
+  if (!tool_result || tool_result.length < 20) {
+    return false;
+  }
+
+  // Skip Read tool for most files (too noisy)
+  if (tool_name === 'Read') {
+    // Only capture if reading a significant file type
+    const filePath = input.tool_input?.file_path as string;
+    if (filePath) {
+      const significantExtensions = ['.md', '.json', '.toml', '.yaml', '.yml'];
+      const lastDot = filePath.lastIndexOf('.');
+      const ext = lastDot >= 0 ? filePath.substring(lastDot) : '';
+      if (!significantExtensions.includes(ext)) {
+        return false;
+      }
+    }
+  }
+
+  // Write/Edit operations are always significant
+  if (['Write', 'Edit', 'MultiEdit', 'NotebookEdit'].includes(tool_name)) {
+    return true;
+  }
+
+  // Bash commands that modify things are significant
+  if (tool_name === 'Bash') {
+    const command = input.tool_input?.command as string;
+    if (command) {
+      const modifyingCommands = ['git commit', 'git push', 'npm install', 'bun install', 'mkdir', 'rm', 'mv', 'cp'];
+      return modifyingCommands.some(cmd => command.includes(cmd));
+    }
+  }
+
+  // Task tool results are significant
+  if (tool_name === 'Task') {
+    return true;
+  }
+
+  // WebFetch/WebSearch results are significant
+  if (['WebFetch', 'WebSearch'].includes(tool_name)) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Classifies the observation type based on tool name, input, and result content.
+ * Checks for type-specific keywords in the combined text and falls back to
+ * tool-based classification if no keywords match.
+ *
+ * @param input - The PostToolUseInput containing tool context
+ * @returns The classified ObservationType (e.g., 'bugfix', 'feature', 'change', 'discovery')
+ */
+function classifyType(input: PostToolUseInput): ObservationType {
+  const { tool_name, tool_input, tool_result } = input;
+  const combinedText = `${tool_name} ${JSON.stringify(tool_input || {})} ${tool_result || ''}`.toLowerCase();
+
+  // Check for type keywords
+  for (const [type, keywords] of Object.entries(TYPE_KEYWORDS)) {
+    for (const keyword of keywords) {
+      if (combinedText.includes(keyword)) {
+        return type as ObservationType;
+      }
+    }
+  }
+
+  // Default based on tool type
+  if (['Write', 'Edit', 'MultiEdit'].includes(tool_name)) {
+    return 'change';
+  }
+  if (tool_name === 'Bash') {
+    const command = input.tool_input?.command as string;
+    if (command?.includes('git commit')) return 'change';
+    if (command?.includes('git push')) return 'change';
+    if (command?.includes('test')) return 'change';
+  }
+  if (['WebFetch', 'WebSearch'].includes(tool_name)) {
+    return 'discovery';
+  }
+  if (tool_name === 'Task') {
+    return 'discovery';
+  }
+
+  return 'change';
+}
+
+/**
+ * Generates a human-readable title for an observation based on the tool operation.
+ * Extracts meaningful information from tool input to create descriptive titles
+ * like "Modified config.ts" or "Git commit operation".
+ *
+ * @param input - The PostToolUseInput containing tool_name and tool_input
+ * @returns A descriptive title string for the observation
+ */
+function generateTitle(input: PostToolUseInput): string {
+  const { tool_name, tool_input } = input;
+
+  switch (tool_name) {
+    case 'Write':
+    case 'Edit':
+    case 'MultiEdit': {
+      const filePath = tool_input?.file_path as string;
+      if (filePath) {
+        return `Modified ${basename(filePath)}`;
+      }
+      return `File ${tool_name.toLowerCase()} operation`;
+    }
+    case 'Bash': {
+      const command = tool_input?.command as string;
+      if (command) {
+        // Extract first meaningful part of command
+        const parts = command.split(/[;&|]/)[0].trim().split(' ');
+        const cmd = parts[0];
+        if (cmd === 'git' && parts.length > 1) {
+          return `Git ${parts[1]} operation`;
+        }
+        return `Executed ${cmd}`;
+      }
+      return 'Bash command executed';
+    }
+    case 'Task': {
+      const subagentType = tool_input?.subagent_type as string;
+      const description = tool_input?.description as string;
+      return description || `${subagentType} agent task`;
+    }
+    case 'WebFetch':
+    case 'WebSearch': {
+      const url = tool_input?.url as string;
+      const query = tool_input?.query as string;
+      if (url) {
+        try {
+          return `Fetched ${new URL(url).hostname}`;
+        } catch {
+          return `Fetched ${url.substring(0, 40)}`;
+        }
+      }
+      if (query) return `Searched: ${query.substring(0, 40)}`;
+      return `Web ${tool_name.toLowerCase()}`;
+    }
+    default:
+      return `${tool_name} operation`;
+  }
+}
+
+/**
+ * Extracts file paths from the tool input for associating files with the observation.
+ * Handles both single file_path and array files properties.
+ *
+ * @param input - The PostToolUseInput containing tool_input with potential file paths
+ * @returns Array of file path strings, or undefined if no files found
+ */
+function extractFiles(input: PostToolUseInput): string[] | undefined {
+  const { tool_input } = input;
+  const files: string[] = [];
+
+  if (tool_input?.file_path) {
+    files.push(tool_input.file_path as string);
+  }
+  if (tool_input?.files && Array.isArray(tool_input.files)) {
+    files.push(...(tool_input.files as string[]));
+  }
+
+  return files.length > 0 ? files : undefined;
+}
+
+/**
+ * Gets the current project name from the working directory.
+ * Uses the basename of process.cwd() as the project identifier.
+ *
+ * @returns The project directory name, or undefined on error
+ */
+function getProject(): string | undefined {
+  try {
+    const cwd = process.cwd();
+    return basename(cwd);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Main hook execution
+ */
+async function main(): Promise<void> {
+  // Read input from stdin
+  let input: PostToolUseInput | null = null;
+  try {
+    const stdin = await Bun.stdin.text();
+    if (stdin.trim()) {
+      input = JSON.parse(stdin);
+    }
+  } catch {
+    // Ignore stdin parse errors
+    console.log('{}');
+    return;
+  }
+
+  if (!input || !input.tool_name) {
+    console.log('{}');
+    return;
+  }
+
+  // Check if significant
+  if (!isSignificant(input)) {
+    console.log('{}');
+    return;
+  }
+
+  // Check if database exists
+  const dbPath = getDefaultDbPath();
+  if (!dbExists(dbPath)) {
+    console.log('{}');
+    return;
+  }
+
+  try {
+    // Create observation
+    const db = new AnvilMemoryDb(dbPath);
+
+    const type = classifyType(input);
+    const title = generateTitle(input);
+    const files = extractFiles(input);
+    const project = getProject();
+
+    // Truncate tool_result for content (keep it reasonable)
+    const content = input.tool_result
+      ? input.tool_result.substring(0, 1000)
+      : `${input.tool_name} operation`;
+
+    db.createObservation({
+      type,
+      title,
+      content,
+      project,
+      files,
+      timestamp: new Date().toISOString(),
+    });
+
+    db.close();
+  } catch {
+    // Silently fail - don't disrupt Claude Code flow
+  }
+
+  // Always output empty JSON (hook doesn't modify response)
+  console.log('{}');
+}
+
+main();

package/global/hooks/anvil_memory_session.ts

@@ -0,0 +1,166 @@
+#!/usr/bin/env bun
+/**
+ * SessionStart Hook - Inject recent context from Anvil Memory
+ *
+ * Claude Code Hook Type: SessionStart
+ * Purpose: Query recent observations and inject into session context
+ *
+ * Input: JSON from stdin with session info
+ * Output: JSON with { additionalContext: "markdown content" }
+ *
+ * Performance target: <100ms
+ */
+
+import { AnvilMemoryDb, dbExists, getDefaultDbPath } from '../tools/anvil-memory/src/db.ts';
+import type { Observation } from '../tools/anvil-memory/src/types.ts';
+
+// Configuration
+const MAX_OBSERVATIONS = 30;
+// TODO: Implement token counting/truncation in generateContext to enforce this limit
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const MAX_CONTEXT_TOKENS = 4000; // Approximate token limit for context injection
+
+// Type emoji mapping
+const TYPE_EMOJI: Record<string, string> = {
+  bugfix: '🔴',
+  feature: '🟣',
+  refactor: '🔄',
+  discovery: '🔵',
+  decision: '⚖️',
+  change: '✅',
+  checkpoint: '📍',
+  ralph_iteration: '🤖',
+  handoff: '📤',
+  shard: '🧩',
+  linear_sync: '🔗',
+  session_request: '🎯',
+};
+
+interface HookInput {
+  cwd?: string;
+  claudeMdFiles?: string[];
+}
+
+interface HookOutput {
+  additionalContext?: string;
+}
+
+/**
+ * Formats a single observation as a markdown table row.
+ * Converts the timestamp to a localized time string and maps the type to an emoji.
+ *
+ * @param obs - The Observation object with id, timestamp, type, and title fields
+ * @returns A markdown table row string in format "| #id | time | emoji | title |"
+ */
+function formatObservation(obs: Observation): string {
+  const emoji = TYPE_EMOJI[obs.type] || '📝';
+  const time = new Date(obs.timestamp).toLocaleTimeString('en-US', {
+    hour: 'numeric',
+    minute: '2-digit',
+  });
+  return `| #${obs.id} | ${time} | ${emoji} | ${obs.title} |`;
+}
+
+/**
+ * Groups observations by their project field.
+ * Observations without a project are grouped under 'General'.
+ *
+ * @param observations - Array of Observation objects to group
+ * @returns A Map where keys are project names (or 'General') and values are arrays of observations for that project
+ */
+function groupByProject(observations: Observation[]): Map<string, Observation[]> {
+  const groups = new Map<string, Observation[]>();
+  for (const obs of observations) {
+    const project = obs.project || 'General';
+    const existing = groups.get(project) || [];
+    existing.push(obs);
+    groups.set(project, existing);
+  }
+  return groups;
+}
+
+/**
+ * Generates a markdown summary of recent observations for context injection.
+ * Groups observations by project and formats them as tables with headers.
+ * Includes a legend explaining the type emojis.
+ *
+ * @param observations - Array of Observation objects to summarize
+ * @returns Markdown string suitable for context injection, or empty string if no observations
+ */
+function generateContext(observations: Observation[]): string {
+  if (observations.length === 0) {
+    return '';
+  }
+
+  const lines: string[] = [];
+  lines.push('# Recent Context from Anvil Memory');
+  lines.push('');
+  lines.push(`> ${observations.length} recent observations loaded`);
+  lines.push('');
+
+  // Group by project
+  const grouped = groupByProject(observations);
+
+  for (const [project, obs] of grouped) {
+    lines.push(`## ${project}`);
+    lines.push('');
+    lines.push('| ID | Time | Type | Title |');
+    lines.push('|----|------|------|-------|');
+    for (const o of obs) {
+      lines.push(formatObservation(o));
+    }
+    lines.push('');
+  }
+
+  // Add legend
+  lines.push('**Legend:** 🔴 bugfix | 🟣 feature | 🔄 refactor | 🔵 discovery | ⚖️ decision | ✅ change');
+  lines.push('');
+  lines.push('*Use `anvil-memory get <id>` to fetch full observation details.*');
+
+  return lines.join('\n');
+}
+
+/**
+ * Main hook execution
+ */
+async function main(): Promise<void> {
+  // Read input from stdin
+  let input: HookInput = {};
+  try {
+    const stdin = await Bun.stdin.text();
+    if (stdin.trim()) {
+      input = JSON.parse(stdin);
+    }
+  } catch {
+    // Ignore stdin parse errors
+  }
+
+  // Check if database exists
+  const dbPath = getDefaultDbPath();
+  if (!dbExists(dbPath)) {
+    // No database - output empty response
+    const output: HookOutput = {};
+    console.log(JSON.stringify(output));
+    return;
+  }
+
+  try {
+    // Query recent observations
+    const db = new AnvilMemoryDb(dbPath);
+    const observations = db.getRecentObservations(MAX_OBSERVATIONS);
+    db.close();
+
+    // Generate context
+    const context = generateContext(observations);
+
+    // Output result
+    const output: HookOutput = context ? { additionalContext: context } : {};
+    console.log(JSON.stringify(output));
+  } catch (error) {
+    // On error, output empty response (graceful degradation)
+    const output: HookOutput = {};
+    console.log(JSON.stringify(output));
+  }
+}
+
+main();

package/global/hooks/anvil_memory_stop.ts

@@ -0,0 +1,187 @@
+#!/usr/bin/env bun
+/**
+ * Stop Hook - Save session summary to Anvil Memory
+ *
+ * Claude Code Hook Type: Stop
+ * Purpose: Generate session summary and save to database
+ *
+ * Input: JSON from stdin with session stats
+ * Output: Empty JSON (hook doesn't block)
+ *
+ * Performance target: <500ms
+ */
+
+import { AnvilMemoryDb, dbExists, getDefaultDbPath } from '../tools/anvil-memory/src/db.ts';
+import { basename } from 'path';
+import { execSync } from 'child_process';
+
+interface StopInput {
+  session_id?: string;
+  transcript?: string;
+  context_used_percent?: number;
+  tool_calls?: number;
+  duration_seconds?: number;
+  started_at?: string;
+}
+
+/**
+ * Gets the current git branch name.
+ * Uses a 100ms timeout to prevent hangs when git is unresponsive.
+ *
+ * @returns The current branch name, or undefined if not in a git repo or on error/timeout
+ */
+function getGitBranch(): string | undefined {
+  try {
+    return execSync('git branch --show-current', { encoding: 'utf-8', timeout: 100 }).trim();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Gets the current git commit hash (short form).
+ * Uses a 100ms timeout to prevent hangs when git is unresponsive.
+ *
+ * @returns The short commit hash, or undefined if not in a git repo or on error/timeout
+ */
+function getGitHash(): string | undefined {
+  try {
+    return execSync('git rev-parse --short HEAD', { encoding: 'utf-8', timeout: 100 }).trim();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Gets the current project name from the working directory.
+ * Uses the basename of process.cwd() as the project identifier.
+ *
+ * @returns The project directory name, or 'unknown' if unable to determine
+ */
+function getProject(): string {
+  try {
+    return basename(process.cwd());
+  } catch {
+    return 'unknown';
+  }
+}
+
+/**
+ * Generates a session summary from recent observations in the database.
+ * Queries the 20 most recent observations and creates a summary including:
+ * - Total observation count
+ * - Breakdown by observation type
+ * - Key work titles (first 3 observations)
+ *
+ * @param db - The AnvilMemoryDb instance to query
+ * @returns A human-readable summary string describing the session's observations
+ */
+function generateSummary(db: AnvilMemoryDb): string {
+  // Get recent observations (from last hour as proxy for "this session")
+  const observations = db.getRecentObservations(20);
+
+  if (observations.length === 0) {
+    return 'No observations recorded during this session.';
+  }
+
+  // Count by type
+  const typeCounts: Record<string, number> = {};
+  for (const obs of observations) {
+    typeCounts[obs.type] = (typeCounts[obs.type] || 0) + 1;
+  }
+
+  // Build summary
+  const parts: string[] = [];
+  parts.push(`Session recorded ${observations.length} observation(s).`);
+
+  // Add type breakdown
+  const typeBreakdown = Object.entries(typeCounts)
+    .map(([type, count]) => `${count} ${type}`)
+    .join(', ');
+  if (typeBreakdown) {
+    parts.push(`Types: ${typeBreakdown}.`);
+  }
+
+  // Add key observations (first 3 titles)
+  const keyTitles = observations.slice(0, 3).map(o => o.title);
+  if (keyTitles.length > 0) {
+    parts.push(`Key work: ${keyTitles.join('; ')}.`);
+  }
+
+  return parts.join(' ');
+}
+
+/**
+ * Calculates the session start time from available input data.
+ * Uses a three-tier precedence:
+ * 1. Explicit started_at from input (if provided)
+ * 2. Calculated from duration_seconds (current time - duration)
+ * 3. Current time as fallback
+ *
+ * @param input - The StopInput containing optional started_at or duration_seconds
+ * @returns ISO 8601 formatted timestamp string
+ */
+function calculateStartedAt(input: StopInput): string {
+  // Use explicit started_at if provided
+  if (input.started_at) {
+    return input.started_at;
+  }
+
+  // Calculate from duration if available
+  if (input.duration_seconds && input.duration_seconds > 0) {
+    const startTime = Date.now() - input.duration_seconds * 1000;
+    return new Date(startTime).toISOString();
+  }
+
+  // Fallback to current time
+  return new Date().toISOString();
+}
+
+/**
+ * Main hook execution
+ */
+async function main(): Promise<void> {
+  // Read input from stdin
+  let input: StopInput = {};
+  try {
+    const stdin = await Bun.stdin.text();
+    if (stdin.trim()) {
+      input = JSON.parse(stdin);
+    }
+  } catch {
+    // Ignore stdin parse errors
+  }
+
+  // Check if database exists
+  const dbPath = getDefaultDbPath();
+  if (!dbExists(dbPath)) {
+    console.log('{}');
+    return;
+  }
+
+  try {
+    const db = new AnvilMemoryDb(dbPath);
+
+    // Generate summary
+    const summary = generateSummary(db);
+
+    // Create session record
+    db.createSession({
+      project: getProject(),
+      branch: getGitBranch(),
+      git_hash: getGitHash(),
+      context_peak_percent: input.context_used_percent,
+      summary,
+      started_at: calculateStartedAt(input),
+    });
+
+    db.close();
+  } catch {
+    // Silently fail - don't disrupt Claude Code flow
+  }
+
+  // Always output empty JSON
+  console.log('{}');
+}
+
+main();