@massu/core 0.1.0 → 0.1.2

package/src/audit-trail.ts

@@ -0,0 +1,450 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+import type Database from 'better-sqlite3';
+import type { ToolDefinition, ToolResult } from './tools.ts';
+import { getConfig } from './config.ts';
+
+// ============================================================
+// Compliance Audit Trail
+// ============================================================
+
+/** Prefix a base tool name with the configured tool prefix. */
+function p(baseName: string): string {
+  return `${getConfig().toolPrefix}_${baseName}`;
+}
+
+export interface AuditEntry {
+  eventType: 'code_change' | 'rule_enforced' | 'approval' | 'review' | 'commit' | 'compaction';
+  actor: 'ai' | 'human' | 'hook' | 'agent';
+  filePath?: string;
+  changeType?: 'create' | 'edit' | 'delete';
+  evidence?: string;
+  metadata?: Record<string, unknown>;
+  sessionId?: string;
+  modelId?: string;
+  approvalStatus?: 'auto_approved' | 'human_approved' | 'pending' | 'denied';
+  rulesInEffect?: string;
+}
+
+/** Default audit formats */
+const DEFAULT_FORMATS = ['summary', 'detailed', 'soc2'];
+
+/** Default retention days */
+const DEFAULT_RETENTION_DAYS = 365;
+
+/**
+ * Get configured audit formats.
+ */
+function getAuditFormats(): string[] {
+  return getConfig().governance?.audit?.formats ?? DEFAULT_FORMATS;
+}
+
+/**
+ * Log an audit entry.
+ */
+export function logAuditEntry(
+  db: Database.Database,
+  entry: AuditEntry
+): void {
+  db.prepare(`
+    INSERT INTO audit_log (session_id, event_type, actor, model_id, file_path, change_type, rules_in_effect, approval_status, evidence, metadata)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    entry.sessionId ?? null,
+    entry.eventType,
+    entry.actor,
+    entry.modelId ?? null,
+    entry.filePath ?? null,
+    entry.changeType ?? null,
+    entry.rulesInEffect ?? null,
+    entry.approvalStatus ?? null,
+    entry.evidence ?? null,
+    entry.metadata ? JSON.stringify(entry.metadata) : null
+  );
+}
+
+/**
+ * Query audit log with filters.
+ */
+export function queryAuditLog(
+  db: Database.Database,
+  options: {
+    eventType?: string;
+    actor?: string;
+    days?: number;
+    limit?: number;
+    filePath?: string;
+    changeType?: string;
+  }
+): Array<Record<string, unknown>> {
+  let sql = 'SELECT * FROM audit_log WHERE 1=1';
+  const params: (string | number)[] = [];
+
+  if (options.eventType) {
+    sql += ' AND event_type = ?';
+    params.push(options.eventType);
+  }
+  if (options.actor) {
+    sql += ' AND actor = ?';
+    params.push(options.actor);
+  }
+  if (options.days) {
+    sql += ' AND timestamp >= datetime(\'now\', ?)';
+    params.push(`-${options.days} days`);
+  }
+  if (options.filePath) {
+    sql += ' AND file_path = ?';
+    params.push(options.filePath);
+  }
+  if (options.changeType) {
+    sql += ' AND change_type = ?';
+    params.push(options.changeType);
+  }
+
+  sql += ' ORDER BY timestamp DESC';
+
+  if (options.limit) {
+    sql += ' LIMIT ?';
+    params.push(options.limit);
+  }
+
+  return db.prepare(sql).all(...params) as Array<Record<string, unknown>>;
+}
+
+/**
+ * Get audit chain for a file - chronological audit history.
+ */
+export function getFileChain(
+  db: Database.Database,
+  filePath: string
+): Array<Record<string, unknown>> {
+  return db.prepare(
+    'SELECT * FROM audit_log WHERE file_path = ? ORDER BY timestamp ASC'
+  ).all(filePath) as Array<Record<string, unknown>>;
+}
+
+/**
+ * Backfill audit log from session observations.
+ */
+export function backfillAuditLog(db: Database.Database): number {
+  const observations = db.prepare(`
+    SELECT o.id, o.type, o.detail, o.files_involved, o.session_id, o.created_at
+    FROM observations o
+    LEFT JOIN audit_log a ON a.evidence = o.detail AND a.session_id = o.session_id
+    WHERE a.id IS NULL
+    AND o.type IN ('bugfix', 'cr_violation', 'vr_check', 'incident', 'decision')
+    ORDER BY o.created_at ASC
+    LIMIT 1000
+  `).all() as Array<Record<string, unknown>>;
+
+  let backfilled = 0;
+  for (const obs of observations) {
+    const files = obs.files_involved ? JSON.parse(obs.files_involved as string) : [];
+    const eventType = (obs.type === 'cr_violation') ? 'rule_enforced' as const
+      : (obs.type === 'vr_check') ? 'review' as const
+      : 'code_change' as const;
+
+    logAuditEntry(db, {
+      eventType,
+      actor: 'ai',
+      filePath: files[0] ?? undefined,
+      changeType: 'edit',
+      evidence: obs.detail as string,
+      sessionId: obs.session_id as string,
+      metadata: { original_type: obs.type, backfilled: true },
+    });
+    backfilled++;
+  }
+
+  return backfilled;
+}
+
+// ============================================================
+// MCP Tool Definitions & Handlers
+// ============================================================
+
+export function getAuditToolDefinitions(): ToolDefinition[] {
+  return [
+    {
+      name: p('audit_log'),
+      description: 'Query the audit log. Filter by event type, actor, file, or time range.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          event_type: { type: 'string', description: 'Filter by event type: code_change, rule_enforced, approval, review, commit, compaction' },
+          actor: { type: 'string', description: 'Filter by actor: ai, human, hook, agent' },
+          file_path: { type: 'string', description: 'Filter by file path' },
+          change_type: { type: 'string', description: 'Filter by change type: create, edit, delete' },
+          days: { type: 'number', description: 'Days to look back (default: 30)' },
+          limit: { type: 'number', description: 'Max results (default: 50)' },
+        },
+        required: [],
+      },
+    },
+    {
+      name: p('audit_report'),
+      description: 'Generate an audit report in a specified format (summary, detailed, soc2).',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          format: { type: 'string', description: 'Report format: summary, detailed, soc2 (default: summary)' },
+          days: { type: 'number', description: 'Days to cover (default: 30)' },
+        },
+        required: [],
+      },
+    },
+    {
+      name: p('audit_chain'),
+      description: 'Get the complete audit trail for a specific file. Shows all changes, reviews, and decisions chronologically.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          file: { type: 'string', description: 'File path to trace' },
+        },
+        required: ['file'],
+      },
+    },
+  ];
+}
+
+const AUDIT_BASE_NAMES = new Set(['audit_log', 'audit_report', 'audit_chain']);
+
+export function isAuditTool(name: string): boolean {
+  const pfx = getConfig().toolPrefix + '_';
+  const baseName = name.startsWith(pfx) ? name.slice(pfx.length) : name;
+  return AUDIT_BASE_NAMES.has(baseName);
+}
+
+export function handleAuditToolCall(
+  name: string,
+  args: Record<string, unknown>,
+  memoryDb: Database.Database
+): ToolResult {
+  try {
+    const pfx = getConfig().toolPrefix + '_';
+    const baseName = name.startsWith(pfx) ? name.slice(pfx.length) : name;
+
+    switch (baseName) {
+      case 'audit_log':
+        return handleAuditLog(args, memoryDb);
+      case 'audit_report':
+        return handleAuditReport(args, memoryDb);
+      case 'audit_chain':
+        return handleAuditChain(args, memoryDb);
+      default:
+        return text(`Unknown audit tool: ${name}`);
+    }
+  } catch (error) {
+    return text(`Error in ${name}: ${error instanceof Error ? error.message : String(error)}\n\nUsage: ${p('audit_log')} { severity: "critical" }, ${p('audit_report')} { format: "soc2" }`);
+  }
+}
+
+function handleAuditLog(args: Record<string, unknown>, db: Database.Database): ToolResult {
+  const entries = queryAuditLog(db, {
+    eventType: args.event_type as string | undefined,
+    actor: args.actor as string | undefined,
+    filePath: args.file_path as string | undefined,
+    changeType: args.change_type as string | undefined,
+    days: (args.days as number) ?? 30,
+    limit: (args.limit as number) ?? 50,
+  });
+
+  if (entries.length === 0) {
+    return text(`No audit log entries found matching the filters. Audit entries are recorded automatically during code changes, rule checks, and commits. Try broadening your search: ${p('audit_log')} { days: 90 } for a longer time range, or ${p('audit_log')} {} with no filters.`);
+  }
+
+  const lines = [
+    `## Audit Log (${entries.length} entries)`,
+    '',
+    '| Timestamp | Event | Actor | Change | File | Evidence |',
+    '|-----------|-------|-------|--------|------|----------|',
+  ];
+
+  for (const entry of entries) {
+    const file = entry.file_path ? (entry.file_path as string).split('/').pop() : '-';
+    const evidence = entry.evidence ? (entry.evidence as string).slice(0, 50) : '-';
+    lines.push(
+      `| ${(entry.timestamp as string).slice(0, 16)} | ${entry.event_type} | ${entry.actor} | ${entry.change_type ?? '-'} | ${file} | ${evidence} |`
+    );
+  }
+
+  return text(lines.join('\n'));
+}
+
+function handleAuditReport(args: Record<string, unknown>, db: Database.Database): ToolResult {
+  const format = (args.format as string) ?? 'summary';
+  const days = (args.days as number) ?? 30;
+
+  const availableFormats = getAuditFormats();
+  if (!availableFormats.includes(format)) {
+    return text(`Unknown report format: "${format}". Available formats: ${availableFormats.join(', ')}. Example: ${p('audit_report')} { format: "soc2", days: 30 }. Configure additional formats via the governance.audit.formats config key.`);
+  }
+
+  const entries = queryAuditLog(db, { days });
+
+  if (entries.length === 0) {
+    return text(`No audit entries found in the last ${days} days. Audit entries are recorded automatically during code changes, reviews, and commits. Try: ${p('audit_log')} { days: 90 } for a longer time range.`);
+  }
+
+  // Count by event type and actor
+  const byEventType: Record<string, number> = {};
+  const byActor: Record<string, number> = {};
+  for (const e of entries) {
+    const et = e.event_type as string;
+    byEventType[et] = (byEventType[et] ?? 0) + 1;
+    const actor = e.actor as string;
+    byActor[actor] = (byActor[actor] ?? 0) + 1;
+  }
+
+  if (format === 'soc2') {
+    return generateSoc2Report(entries, byEventType, byActor, days);
+  }
+
+  if (format === 'detailed') {
+    return generateDetailedReport(entries, byEventType, byActor, days);
+  }
+
+  // Summary format
+  const lines = [
+    `## Audit Summary Report (${days} days)`,
+    `Generated: ${new Date().toISOString().slice(0, 16)}`,
+    '',
+    '### By Event Type',
+    `| Event Type | Count |`,
+    `|------------|-------|`,
+  ];
+
+  for (const [et, count] of Object.entries(byEventType).sort((a, b) => b[1] - a[1])) {
+    lines.push(`| ${et} | ${count} |`);
+  }
+
+  lines.push(`| **Total** | **${entries.length}** |`);
+  lines.push('');
+  lines.push('### By Actor');
+  lines.push(`| Actor | Count |`);
+  lines.push(`|-------|-------|`);
+
+  for (const [actor, count] of Object.entries(byActor).sort((a, b) => b[1] - a[1])) {
+    lines.push(`| ${actor} | ${count} |`);
+  }
+
+  return text(lines.join('\n'));
+}
+
+function generateSoc2Report(
+  entries: Array<Record<string, unknown>>,
+  byEventType: Record<string, number>,
+  byActor: Record<string, number>,
+  days: number
+): ToolResult {
+  const lines = [
+    `# SOC 2 Compliance Report`,
+    `Period: Last ${days} days`,
+    `Generated: ${new Date().toISOString()}`,
+    '',
+    '## 1. Control Environment',
+    `Total audit events: ${entries.length}`,
+    `Human-initiated: ${byActor['human'] ?? 0}`,
+    `AI-initiated: ${byActor['ai'] ?? 0}`,
+    `Hook-triggered: ${byActor['hook'] ?? 0}`,
+    '',
+    '## 2. Change Management',
+    `Code changes logged: ${byEventType['code_change'] ?? 0}`,
+    `Rule enforcements: ${byEventType['rule_enforced'] ?? 0}`,
+    `Approvals recorded: ${byEventType['approval'] ?? 0}`,
+    `Reviews: ${byEventType['review'] ?? 0}`,
+    `Commits: ${byEventType['commit'] ?? 0}`,
+    '',
+    '## 3. Approval Status',
+  ];
+
+  const pendingApprovals = entries.filter(e => e.approval_status === 'pending');
+  const deniedApprovals = entries.filter(e => e.approval_status === 'denied');
+  lines.push(`Pending approvals: ${pendingApprovals.length}`);
+  lines.push(`Denied approvals: ${deniedApprovals.length}`);
+  lines.push('');
+  lines.push('## 4. Events Requiring Review');
+
+  const reviewEntries = entries.filter(e => e.approval_status === 'denied' || e.event_type === 'rule_enforced');
+  if (reviewEntries.length > 0) {
+    for (const e of reviewEntries.slice(0, 20)) {
+      lines.push(`- [${(e.timestamp as string).slice(0, 16)}] ${e.event_type}: ${((e.evidence as string) ?? '').slice(0, 100)}`);
+    }
+  } else {
+    lines.push('No events requiring review in this period.');
+  }
+
+  return text(lines.join('\n'));
+}
+
+function generateDetailedReport(
+  entries: Array<Record<string, unknown>>,
+  byEventType: Record<string, number>,
+  byActor: Record<string, number>,
+  days: number
+): ToolResult {
+  const lines = [
+    `## Detailed Audit Report (${days} days)`,
+    `Total events: ${entries.length}`,
+    '',
+    '### Event Type Distribution',
+  ];
+
+  for (const [et, count] of Object.entries(byEventType).sort((a, b) => b[1] - a[1])) {
+    lines.push(`- ${et}: ${count}`);
+  }
+
+  lines.push('');
+  lines.push('### Actor Distribution');
+  for (const [actor, count] of Object.entries(byActor).sort((a, b) => b[1] - a[1])) {
+    lines.push(`- ${actor}: ${count}`);
+  }
+
+  lines.push('');
+  lines.push('### All Events');
+
+  for (const e of entries.slice(0, 100)) {
+    lines.push(`#### ${(e.timestamp as string).slice(0, 16)} [${e.event_type}]`);
+    lines.push(`Actor: ${e.actor} | Change: ${e.change_type ?? '-'} | Approval: ${e.approval_status ?? '-'}`);
+    if (e.file_path) lines.push(`File: ${e.file_path}`);
+    if (e.evidence) lines.push(`Evidence: ${e.evidence}`);
+    lines.push('');
+  }
+
+  if (entries.length > 100) {
+    lines.push(`... and ${entries.length - 100} more entries`);
+  }
+
+  return text(lines.join('\n'));
+}
+
+function handleAuditChain(args: Record<string, unknown>, db: Database.Database): ToolResult {
+  const filePath = args.file as string;
+  if (!filePath) return text(`Usage: ${p('audit_chain')} { file: "src/path/to/file.ts" } - Get complete audit history for a file.`);
+
+  const chain = getFileChain(db, filePath);
+
+  if (chain.length === 0) {
+    return text(`No audit entries found for "${filePath}". Audit entries are recorded automatically when files are modified, reviewed, or validated. Try: ${p('audit_log')} {} to see all recent audit entries across all files.`);
+  }
+
+  const lines = [
+    `## Audit Chain: ${filePath}`,
+    `Total events: ${chain.length}`,
+    '',
+  ];
+
+  for (const entry of chain) {
+    lines.push(`### ${(entry.timestamp as string).slice(0, 16)} [${entry.event_type}]`);
+    lines.push(`**${entry.actor}** (${entry.change_type ?? 'unknown'})`);
+    if (entry.evidence) lines.push(entry.evidence as string);
+    lines.push('');
+  }
+
+  return text(lines.join('\n'));
+}
+
+function text(content: string): ToolResult {
+  return { content: [{ type: 'text', text: content }] };
+}

package/src/backfill-sessions.ts

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+// ============================================================
+// P6-001: Backfill Tool
+// One-time script to parse existing transcript JSONL files and
+// populate the memory DB with historical session data.
+// ============================================================
+
+import { readdirSync, statSync, existsSync } from 'fs';
+import { resolve, basename } from 'path';
+import { getMemoryDb, createSession, addObservation, addSummary, addUserPrompt, deduplicateFailedAttempt } from './memory-db.ts';
+import { parseTranscript, extractUserMessages, getLastAssistantMessage } from './transcript-parser.ts';
+import { extractObservationsFromEntries } from './observation-extractor.ts';
+import { getProjectRoot } from './config.ts';
+
+/**
+ * Auto-detect the Claude Code project transcript directory.
+ * Claude Code stores transcripts at ~/.claude/projects/-<escaped-path>/
+ */
+function findTranscriptDir(): string {
+  const home = process.env.HOME ?? '~';
+  const projectRoot = getProjectRoot();
+  // Claude Code escapes the path by replacing / with -
+  const escapedPath = projectRoot.replace(/\//g, '-');
+  const candidate = resolve(home, '.claude/projects', escapedPath);
+  if (existsSync(candidate)) return candidate;
+  // Fallback: scan .claude/projects/ for directories matching the project name
+  const projectsDir = resolve(home, '.claude/projects');
+  if (existsSync(projectsDir)) {
+    try {
+      const entries = readdirSync(projectsDir);
+      const projectName = basename(projectRoot);
+      const match = entries.find(e => e.includes(projectName));
+      if (match) return resolve(projectsDir, match);
+    } catch {
+      // Ignore
+    }
+  }
+  return candidate;
+}
+
+const MAX_SESSIONS = 20;
+
+async function main(): Promise<void> {
+  console.log('=== Massu Memory Backfill ===');
+  const TRANSCRIPT_DIR = findTranscriptDir();
+  console.log(`Transcript directory: ${TRANSCRIPT_DIR}`);
+
+  // 1. List JSONL files
+  let files: string[];
+  try {
+    files = readdirSync(TRANSCRIPT_DIR)
+      .filter(f => f.endsWith('.jsonl'))
+      .map(f => ({
+        name: f,
+        path: resolve(TRANSCRIPT_DIR, f),
+        mtime: statSync(resolve(TRANSCRIPT_DIR, f)).mtimeMs,
+      }))
+      .sort((a, b) => b.mtime - a.mtime)  // Most recent first
+      .slice(0, MAX_SESSIONS)
+      .map(f => f.path);
+  } catch (error) {
+    console.error(`Failed to read transcript directory: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+    return;
+  }
+
+  console.log(`Found ${files.length} transcript files (processing most recent ${MAX_SESSIONS})`);
+
+  const db = getMemoryDb();
+  let totalObservations = 0;
+  let totalSessions = 0;
+
+  try {
+    for (const filePath of files) {
+      const sessionId = filePath.split('/').pop()?.replace('.jsonl', '') ?? 'unknown';
+      console.log(`\nProcessing: ${sessionId.slice(0, 8)}...`);
+
+      try {
+        // Parse transcript
+        const entries = await parseTranscript(filePath);
+        if (entries.length === 0) {
+          console.log('  Skipped: empty transcript');
+          continue;
+        }
+
+        // Extract session metadata
+        const firstEntry = entries.find(e => e.sessionId);
+        const gitBranch = firstEntry?.gitBranch;
+        const startTimestamp = firstEntry?.timestamp;
+
+        // Create session (INSERT OR IGNORE for idempotency)
+        createSession(db, sessionId, { branch: gitBranch });
+
+        // Update started_at if we have a timestamp
+        if (startTimestamp) {
+          db.prepare('UPDATE sessions SET started_at = ?, started_at_epoch = ? WHERE session_id = ? AND started_at_epoch = 0')
+            .run(startTimestamp, Math.floor(new Date(startTimestamp).getTime() / 1000), sessionId);
+        }
+
+        // Extract user prompts
+        const userMessages = extractUserMessages(entries);
+        for (let i = 0; i < Math.min(userMessages.length, 50); i++) {
+          try {
+            addUserPrompt(db, sessionId, userMessages[i].text.slice(0, 5000), i + 1);
+          } catch (_e) {
+            // Skip duplicate prompts
+          }
+        }
+
+        // Extract observations (with noise filtering applied)
+        const observations = extractObservationsFromEntries(entries);
+        let sessionObsCount = 0;
+
+        for (const obs of observations) {
+          try {
+            if (obs.type === 'failed_attempt') {
+              deduplicateFailedAttempt(db, sessionId, obs.title, obs.detail, obs.opts);
+            } else {
+              addObservation(db, sessionId, obs.type, obs.title, obs.detail, obs.opts);
+            }
+            sessionObsCount++;
+          } catch (_e) {
+            // Skip on error
+          }
+        }
+
+        totalObservations += sessionObsCount;
+        totalSessions++;
+        console.log(`  Extracted: ${sessionObsCount} observations, ${Math.min(userMessages.length, 50)} prompts`);
+
+        // Generate summary from observations
+        const completed = observations
+          .filter(o => ['feature', 'bugfix', 'refactor'].includes(o.type))
+          .map(o => `- ${o.title}`)
+          .join('\n');
+
+        const decisions = observations
+          .filter(o => o.type === 'decision')
+          .map(o => `- ${o.title}`)
+          .join('\n');
+
+        const failedAttempts = observations
+          .filter(o => o.type === 'failed_attempt')
+          .map(o => `- ${o.title}`)
+          .join('\n');
+
+        if (observations.length > 0) {
+          try {
+            addSummary(db, sessionId, {
+              request: userMessages[0]?.text?.slice(0, 500),
+              completed: completed || undefined,
+              decisions: decisions || undefined,
+              failedAttempts: failedAttempts || undefined,
+            });
+          } catch (_e) {
+            // Skip summary errors
+          }
+        }
+
+        // Mark as completed
+        db.prepare("UPDATE sessions SET status = 'completed' WHERE session_id = ? AND status = 'active'")
+          .run(sessionId);
+
+      } catch (error) {
+        console.log(`  Error: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+  } finally {
+    db.close();
+  }
+
+  console.log('\n=== Backfill Complete ===');
+  console.log(`Sessions processed: ${totalSessions}`);
+  console.log(`Total observations: ${totalObservations}`);
+}
+
+main().catch(console.error);