engrm 0.1.0

package/src/capture/extractor.ts

@@ -0,0 +1,330 @@
+/**
+ * Observation extractor for PostToolUse hooks.
+ *
+ * Analyses tool use events and decides:
+ *   1. Is this worth capturing? (signal vs noise)
+ *   2. What type of observation is it?
+ *   3. What title/narrative/files to record?
+ *
+ * Design: conservative by default — better to miss some observations
+ * than flood the database with noise.
+ */
+
+// --- Types ---
+
+export interface ToolUseEvent {
+  session_id: string;
+  hook_event_name: string;
+  tool_name: string;
+  tool_input: Record<string, unknown>;
+  tool_response: string;
+  cwd: string;
+}
+
+export interface ExtractedObservation {
+  type: string;
+  title: string;
+  narrative: string;
+  files_read?: string[];
+  files_modified?: string[];
+}
+
+// --- Skip rules (noise filters) ---
+
+/**
+ * Tools that are never worth capturing on their own.
+ */
+const SKIP_TOOLS = new Set([
+  "Glob",
+  "Grep",
+  "Read",
+  "WebSearch",
+  "WebFetch",
+  "Agent",
+]);
+
+/**
+ * Bash commands that are navigational noise.
+ */
+const SKIP_BASH_PATTERNS = [
+  /^\s*(ls|pwd|cd|echo|cat|head|tail|wc|which|whoami|date|uname)\b/,
+  /^\s*git\s+(status|log|branch|diff|show|remote)\b/,
+  /^\s*(node|bun|npm|npx|yarn|pnpm)\s+--?version\b/,
+  /^\s*export\s+/,
+  /^\s*#/,
+];
+
+/**
+ * Bash responses indicating trivial success with no learning value.
+ */
+const TRIVIAL_RESPONSE_PATTERNS = [
+  /^$/,
+  /^\s*$/,
+  /^Already up to date\.$/,
+];
+
+// --- Extraction logic ---
+
+/**
+ * Determine if a tool use event is worth capturing and extract observation data.
+ * Returns null if the event should be skipped.
+ */
+export function extractObservation(
+  event: ToolUseEvent
+): ExtractedObservation | null {
+  const { tool_name, tool_input, tool_response } = event;
+
+  // Skip tools that are pure reads/navigation
+  if (SKIP_TOOLS.has(tool_name)) {
+    return null;
+  }
+
+  switch (tool_name) {
+    case "Edit":
+      return extractFromEdit(tool_input, tool_response);
+    case "Write":
+      return extractFromWrite(tool_input, tool_response);
+    case "Bash":
+      return extractFromBash(tool_input, tool_response);
+    default:
+      // MCP tool calls (mcp__server__tool) — capture if non-trivial
+      if (tool_name.startsWith("mcp__")) {
+        return extractFromMcpTool(tool_name, tool_input, tool_response);
+      }
+      return null;
+  }
+}
+
+// --- Per-tool extractors ---
+
+function extractFromEdit(
+  input: Record<string, unknown>,
+  response: string
+): ExtractedObservation | null {
+  const filePath = input["file_path"] as string | undefined;
+  if (!filePath) return null;
+
+  const oldStr = input["old_string"] as string | undefined;
+  const newStr = input["new_string"] as string | undefined;
+  if (!oldStr && !newStr) return null;
+
+  // Skip tiny cosmetic edits (whitespace, single-char changes)
+  if (oldStr && newStr) {
+    const oldTrimmed = oldStr.trim();
+    const newTrimmed = newStr.trim();
+    if (oldTrimmed === newTrimmed) return null;
+    if (Math.abs(oldTrimmed.length - newTrimmed.length) < 3 && oldTrimmed.length < 20) {
+      return null;
+    }
+  }
+
+  const fileName = filePath.split("/").pop() ?? filePath;
+  const changeSize = (newStr?.length ?? 0) - (oldStr?.length ?? 0);
+  const verb = changeSize > 50 ? "Extended" : changeSize < -50 ? "Reduced" : "Modified";
+
+  return {
+    type: "change",
+    title: `${verb} ${fileName}`,
+    narrative: buildEditNarrative(oldStr, newStr, filePath),
+    files_modified: [filePath],
+  };
+}
+
+function extractFromWrite(
+  input: Record<string, unknown>,
+  response: string
+): ExtractedObservation | null {
+  const filePath = input["file_path"] as string | undefined;
+  if (!filePath) return null;
+
+  const content = input["content"] as string | undefined;
+  const fileName = filePath.split("/").pop() ?? filePath;
+
+  // Skip very small files (likely config or trivial)
+  if (content === undefined || content.length < 50) return null;
+
+  return {
+    type: "change",
+    title: `Created ${fileName}`,
+    narrative: `New file created: ${filePath}`,
+    files_modified: [filePath],
+  };
+}
+
+function extractFromBash(
+  input: Record<string, unknown>,
+  response: string
+): ExtractedObservation | null {
+  const command = input["command"] as string | undefined;
+  if (!command) return null;
+
+  // Skip navigational commands
+  for (const pattern of SKIP_BASH_PATTERNS) {
+    if (pattern.test(command)) return null;
+  }
+
+  // Skip trivial responses
+  for (const pattern of TRIVIAL_RESPONSE_PATTERNS) {
+    if (pattern.test(response.trim())) return null;
+  }
+
+  // Detect error → potential bugfix context
+  const hasError = detectError(response);
+
+  // Detect test runs
+  const isTestRun = detectTestRun(command);
+
+  if (isTestRun) {
+    return extractTestResult(command, response);
+  }
+
+  if (hasError) {
+    return {
+      type: "bugfix",
+      title: summariseCommand(command) + " (error)",
+      narrative: `Command: ${truncate(command, 200)}\nError: ${truncate(response, 500)}`,
+    };
+  }
+
+  // Detect install/dependency changes
+  if (/\b(npm|bun|yarn|pnpm)\s+(install|add|remove|uninstall)\b/.test(command)) {
+    return {
+      type: "change",
+      title: `Dependency change: ${summariseCommand(command)}`,
+      narrative: `Command: ${truncate(command, 200)}\nOutput: ${truncate(response, 300)}`,
+    };
+  }
+
+  // Detect build commands
+  if (/\b(npm|bun|yarn)\s+(run\s+)?(build|compile|bundle)\b/.test(command)) {
+    if (hasError) {
+      return {
+        type: "bugfix",
+        title: `Build failure: ${summariseCommand(command)}`,
+        narrative: `Build command failed.\nCommand: ${truncate(command, 200)}\nOutput: ${truncate(response, 500)}`,
+      };
+    }
+    // Successful builds are low signal
+    return null;
+  }
+
+  // Generic non-trivial bash — only capture if response is substantial
+  if (response.length > 200) {
+    return {
+      type: "change",
+      title: summariseCommand(command),
+      narrative: `Command: ${truncate(command, 200)}\nOutput: ${truncate(response, 300)}`,
+    };
+  }
+
+  return null;
+}
+
+function extractFromMcpTool(
+  toolName: string,
+  input: Record<string, unknown>,
+  response: string
+): ExtractedObservation | null {
+  // Skip our own engrm tools to avoid self-referential loops
+  if (toolName.startsWith("mcp__engrm__")) return null;
+
+  // Generic MCP tool capture — only if response is substantial
+  if (response.length < 100) return null;
+
+  const parts = toolName.split("__");
+  const serverName = parts[1] ?? "unknown";
+  const toolAction = parts[2] ?? "unknown";
+
+  return {
+    type: "change",
+    title: `${serverName}: ${toolAction}`,
+    narrative: `MCP tool ${toolName} called.\nResponse: ${truncate(response, 300)}`,
+  };
+}
+
+// --- Helper functions ---
+
+function detectError(response: string): boolean {
+  const lower = response.toLowerCase();
+  return (
+    lower.includes("error:") ||
+    lower.includes("error[") ||
+    lower.includes("failed") ||
+    lower.includes("exception") ||
+    lower.includes("traceback") ||
+    lower.includes("panic:") ||
+    lower.includes("fatal:") ||
+    /exit code [1-9]/.test(lower)
+  );
+}
+
+function detectTestRun(command: string): boolean {
+  return (
+    /\b(test|spec|jest|vitest|mocha|pytest|cargo\s+test|go\s+test|bun\s+test)\b/i.test(command)
+  );
+}
+
+function extractTestResult(
+  command: string,
+  response: string
+): ExtractedObservation | null {
+  // Match "N fail" where N > 0, or standalone failure keywords
+  const hasFailure =
+    /[1-9]\d*\s+(fail|failed|failures?)\b/i.test(response) ||
+    /\bFAILED\b/.test(response) ||
+    /\berror\b/i.test(response);
+  const hasPass =
+    /\d+\s+(pass|passed|ok)\b/i.test(response) ||
+    /\bPASS\b/.test(response);
+
+  if (hasFailure) {
+    return {
+      type: "bugfix",
+      title: `Test failure: ${summariseCommand(command)}`,
+      narrative: `Test run failed.\nCommand: ${truncate(command, 200)}\nOutput: ${truncate(response, 500)}`,
+    };
+  }
+
+  if (hasPass && !hasFailure) {
+    // All-pass test runs are low signal unless coming after a failure
+    // For now, skip — Phase 2 enhancement: track error→fix sequences
+    return null;
+  }
+
+  return null;
+}
+
+function buildEditNarrative(
+  oldStr: string | undefined,
+  newStr: string | undefined,
+  filePath: string
+): string {
+  const parts = [`File: ${filePath}`];
+
+  if (oldStr && newStr) {
+    const oldLines = oldStr.split("\n").length;
+    const newLines = newStr.split("\n").length;
+    if (oldLines !== newLines) {
+      parts.push(`Lines: ${oldLines} → ${newLines}`);
+    }
+    // Include a brief diff summary
+    parts.push(`Replaced: ${truncate(oldStr, 100)}`);
+    parts.push(`With: ${truncate(newStr, 100)}`);
+  } else if (newStr) {
+    parts.push(`Added: ${truncate(newStr, 150)}`);
+  }
+
+  return parts.join("\n");
+}
+
+function summariseCommand(command: string): string {
+  // Take the first meaningful part of the command
+  const trimmed = command.trim();
+  const firstLine = trimmed.split("\n")[0] ?? trimmed;
+  return truncate(firstLine, 80);
+}
+
+function truncate(text: string, maxLen: number): string {
+  if (text.length <= maxLen) return text;
+  return text.slice(0, maxLen - 3) + "...";
+}

package/src/capture/quality.test.ts

@@ -0,0 +1,168 @@
+import { describe, expect, test } from "bun:test";
+import {
+  scoreQuality,
+  meetsQualityThreshold,
+  QUALITY_THRESHOLD,
+  type QualityInput,
+} from "./quality.js";
+
+describe("scoreQuality", () => {
+  test("bugfix type scores 0.3", () => {
+    const score = scoreQuality({ type: "bugfix", title: "fix" });
+    expect(score).toBeGreaterThanOrEqual(0.3);
+  });
+
+  test("decision type scores 0.3", () => {
+    const score = scoreQuality({ type: "decision", title: "choose db" });
+    expect(score).toBeGreaterThanOrEqual(0.3);
+  });
+
+  test("change type scores lowest (0.05)", () => {
+    const score = scoreQuality({ type: "change", title: "update" });
+    expect(score).toBe(0.05);
+  });
+
+  test("unknown type scores 0", () => {
+    const score = scoreQuality({ type: "unknown", title: "test" });
+    expect(score).toBe(0.0);
+  });
+
+  test("narrative longer than 50 chars adds 0.15", () => {
+    const withNarrative = scoreQuality({
+      type: "change",
+      title: "test",
+      narrative: "a".repeat(51),
+    });
+    const without = scoreQuality({ type: "change", title: "test" });
+    expect(withNarrative - without).toBeCloseTo(0.15, 5);
+  });
+
+  test("short narrative adds nothing", () => {
+    const withShort = scoreQuality({
+      type: "change",
+      title: "test",
+      narrative: "short",
+    });
+    const without = scoreQuality({ type: "change", title: "test" });
+    expect(withShort).toBe(without);
+  });
+
+  test("2+ facts add 0.15", () => {
+    const score = scoreQuality({
+      type: "change",
+      title: "test",
+      facts: JSON.stringify(["fact one", "fact two"]),
+    });
+    expect(score).toBe(0.05 + 0.15);
+  });
+
+  test("1 fact adds 0.05", () => {
+    const score = scoreQuality({
+      type: "change",
+      title: "test",
+      facts: JSON.stringify(["one fact"]),
+    });
+    expect(score).toBe(0.05 + 0.05);
+  });
+
+  test("concepts add 0.1", () => {
+    const score = scoreQuality({
+      type: "change",
+      title: "test",
+      concepts: JSON.stringify(["auth"]),
+    });
+    expect(score).toBe(0.05 + 0.1);
+  });
+
+  test("3+ files modified adds 0.2", () => {
+    const score = scoreQuality({
+      type: "change",
+      title: "test",
+      filesModified: ["a.ts", "b.ts", "c.ts"],
+    });
+    expect(score).toBe(0.05 + 0.2);
+  });
+
+  test("1-2 files modified adds 0.1", () => {
+    const score = scoreQuality({
+      type: "change",
+      title: "test",
+      filesModified: ["a.ts"],
+    });
+    expect(score).toBe(0.05 + 0.1);
+  });
+
+  test("duplicate penalty subtracts 0.3", () => {
+    const normal = scoreQuality({ type: "bugfix", title: "fix" });
+    const dupe = scoreQuality({
+      type: "bugfix",
+      title: "fix",
+      isDuplicate: true,
+    });
+    expect(normal - dupe).toBeCloseTo(0.3, 5);
+  });
+
+  test("score clamped to 0.0 minimum", () => {
+    const score = scoreQuality({
+      type: "unknown",
+      title: "x",
+      isDuplicate: true,
+    });
+    expect(score).toBe(0.0);
+  });
+
+  test("score clamped to 1.0 maximum", () => {
+    const score = scoreQuality({
+      type: "bugfix",
+      title: "big fix",
+      narrative: "a".repeat(100),
+      facts: JSON.stringify(["a", "b", "c"]),
+      concepts: JSON.stringify(["x", "y"]),
+      filesModified: ["a.ts", "b.ts", "c.ts"],
+    });
+    expect(score).toBeLessThanOrEqual(1.0);
+  });
+
+  test("rich bugfix observation scores high", () => {
+    const score = scoreQuality({
+      type: "bugfix",
+      title: "Fix OAuth token refresh race condition",
+      narrative:
+        "The OAuth token was being refreshed by multiple concurrent requests, causing 401 errors. Added a mutex lock around the refresh logic.",
+      facts: JSON.stringify([
+        "Race condition in token refresh",
+        "Multiple concurrent requests triggered simultaneous refreshes",
+        "Fixed with mutex lock",
+      ]),
+      concepts: JSON.stringify(["oauth", "concurrency", "race-condition"]),
+      filesModified: ["src/auth/oauth.ts", "src/auth/mutex.ts"],
+    });
+    expect(score).toBeGreaterThanOrEqual(0.7);
+  });
+});
+
+describe("meetsQualityThreshold", () => {
+  test("threshold is 0.1", () => {
+    expect(QUALITY_THRESHOLD).toBe(0.1);
+  });
+
+  test("bugfix meets threshold", () => {
+    expect(meetsQualityThreshold({ type: "bugfix", title: "fix" })).toBe(true);
+  });
+
+  test("unknown type with duplicate does not meet threshold", () => {
+    expect(
+      meetsQualityThreshold({
+        type: "unknown",
+        title: "x",
+        isDuplicate: true,
+      })
+    ).toBe(false);
+  });
+
+  test("bare change type does not meet threshold (0.05 < 0.1)", () => {
+    expect(
+      meetsQualityThreshold({ type: "change", title: "minor edit" })
+    ).toBe(false);
+  });
+});

package/src/capture/quality.ts

@@ -0,0 +1,104 @@
+/**
+ * Observation quality scoring (0.0 — 1.0).
+ *
+ * Phase 1: Scoring based on available fields (type, content richness, files).
+ * Phase 2: Extended with hook context (error→fix sequences, test results, etc.)
+ *
+ * Observations scoring below QUALITY_THRESHOLD are not saved.
+ * See SPEC §2 for the scoring table.
+ */
+
+export const QUALITY_THRESHOLD = 0.1;
+
+export interface QualityInput {
+  type: string;
+  title: string;
+  narrative?: string | null;
+  facts?: string | null;
+  concepts?: string | null;
+  filesRead?: string[] | null;
+  filesModified?: string[] | null;
+  isDuplicate?: boolean;
+}
+
+/**
+ * Score an observation's quality based on available signals.
+ * Returns a value between 0.0 and 1.0.
+ */
+export function scoreQuality(input: QualityInput): number {
+  let score = 0.0;
+
+  // Type-based scoring
+  switch (input.type) {
+    case "bugfix":
+      score += 0.3;
+      break;
+    case "decision":
+      score += 0.3;
+      break;
+    case "discovery":
+      score += 0.2;
+      break;
+    case "pattern":
+      score += 0.2;
+      break;
+    case "feature":
+      score += 0.15;
+      break;
+    case "refactor":
+      score += 0.15;
+      break;
+    case "change":
+      score += 0.05;
+      break;
+    case "digest":
+      // Digests inherit quality from source observations, not scored here
+      score += 0.3;
+      break;
+  }
+
+  // Content richness signals
+  if (input.narrative && input.narrative.length > 50) {
+    score += 0.15;
+  }
+
+  if (input.facts) {
+    try {
+      const factsArray = JSON.parse(input.facts) as unknown[];
+      if (factsArray.length >= 2) score += 0.15;
+      else if (factsArray.length === 1) score += 0.05;
+    } catch {
+      // facts is a string, not JSON array — still has some value
+      if (input.facts.length > 20) score += 0.05;
+    }
+  }
+
+  if (input.concepts) {
+    try {
+      const conceptsArray = JSON.parse(input.concepts) as unknown[];
+      if (conceptsArray.length >= 1) score += 0.1;
+    } catch {
+      if (input.concepts.length > 10) score += 0.05;
+    }
+  }
+
+  // Files modified indicates non-trivial work
+  const modifiedCount = input.filesModified?.length ?? 0;
+  if (modifiedCount >= 3) score += 0.2;
+  else if (modifiedCount >= 1) score += 0.1;
+
+  // Deduplication penalty
+  if (input.isDuplicate) {
+    score -= 0.3;
+  }
+
+  // Clamp to [0.0, 1.0]
+  return Math.max(0.0, Math.min(1.0, score));
+}
+
+/**
+ * Check if an observation meets the minimum quality threshold.
+ */
+export function meetsQualityThreshold(input: QualityInput): boolean {
+  return scoreQuality(input) >= QUALITY_THRESHOLD;
+}