feat: add export_report tool for markdown session reports (#5)

Adds a new MCP tool that generates markdown reports from timeline data:
- Event breakdown with type distribution percentages
- Branch activity summary
- Daily activity with visual bars
- Commit log with hashes
- Correction/error analysis
- Quality indicators (correction rate, error rate)
- Three formats: summary, detailed, weekly
- Supports relative dates (7days, 2weeks, etc.)

Closes #5

Author: TerminalGravity

src/index.ts

@@ -49,6 +49,7 @@ import { registerScanSessions } from "./tools/scan-sessions.js";
 import { registerGenerateScorecard } from "./tools/generate-scorecard.js";
 import { registerSearchContracts } from "./tools/search-contracts.js";
 import { registerEstimateCost } from "./tools/estimate-cost.js";
+import { registerExportReport } from "./tools/export-report.js";
 
 // Validate related projects from config
 function validateRelatedProjects(): void {
@@ -110,6 +111,7 @@ const toolRegistry: Array<[string, RegisterFn]> = [
   ["generate_scorecard", registerGenerateScorecard],
   ["estimate_cost", registerEstimateCost],
   ["search_contracts", registerSearchContracts],
+  ["export_report", registerExportReport],
 ];
 
 let registered = 0;

src/tools/export-report.ts

@@ -0,0 +1,339 @@
+import { z } from "zod";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { getTimeline, listIndexedProjects } from "../lib/timeline-db.js";
+import { getRelatedProjects } from "../lib/config.js";
+import type { SearchScope } from "../types.js";
+
+const RELATIVE_DATE_RE = /^(\d+)(days?|weeks?|months?|years?)$/;
+
+function parseRelativeDate(input: string): string {
+  const match = input.match(RELATIVE_DATE_RE);
+  if (!match) return input;
+  const [, numStr, unit] = match;
+  const num = parseInt(numStr, 10);
+  const d = new Date();
+  if (unit.startsWith("day")) d.setDate(d.getDate() - num);
+  else if (unit.startsWith("week")) d.setDate(d.getDate() - num * 7);
+  else if (unit.startsWith("month")) d.setMonth(d.getMonth() - num);
+  else if (unit.startsWith("year")) d.setFullYear(d.getFullYear() - num);
+  return d.toISOString();
+}
+
+const TYPE_LABELS: Record<string, string> = {
+  prompt: "Prompts",
+  assistant: "Responses",
+  tool_call: "Tool Calls",
+  correction: "Corrections",
+  commit: "Commits",
+  compaction: "Compactions",
+  sub_agent_spawn: "Sub-agent Spawns",
+  error: "Errors",
+};
+
+const TYPE_ICONS: Record<string, string> = {
+  prompt: "💬",
+  assistant: "🤖",
+  tool_call: "🔧",
+  correction: "❌",
+  commit: "📦",
+  compaction: "🗜️",
+  sub_agent_spawn: "🚀",
+  error: "⚠️",
+};
+
+async function getSearchProjects(scope: SearchScope): Promise<string[]> {
+  const currentProject = process.env.CLAUDE_PROJECT_DIR;
+  switch (scope) {
+    case "current":
+      return currentProject ? [currentProject] : [];
+    case "related": {
+      const related = getRelatedProjects();
+      return currentProject ? [currentProject, ...related] : related;
+    }
+    case "all": {
+      const projects = await listIndexedProjects();
+      return projects.map((p) => p.project);
+    }
+    default:
+      return currentProject ? [currentProject] : [];
+  }
+}
+
+interface ReportStats {
+  totalEvents: number;
+  byType: Record<string, number>;
+  byDay: Record<string, number>;
+  byBranch: Record<string, number>;
+  corrections: Array<{ timestamp: string; content: string }>;
+  errors: Array<{ timestamp: string; content: string }>;
+  commits: Array<{ timestamp: string; content: string; hash?: string }>;
+  activeDays: number;
+  dateRange: { start: string; end: string };
+}
+
+function computeStats(events: any[]): ReportStats {
+  const byType: Record<string, number> = {};
+  const byDay: Record<string, number> = {};
+  const byBranch: Record<string, number> = {};
+  const corrections: ReportStats["corrections"] = [];
+  const errors: ReportStats["errors"] = [];
+  const commits: ReportStats["commits"] = [];
+
+  for (const e of events) {
+    byType[e.type] = (byType[e.type] || 0) + 1;
+
+    const day = e.timestamp ? new Date(e.timestamp).toISOString().slice(0, 10) : "unknown";
+    byDay[day] = (byDay[day] || 0) + 1;
+
+    if (e.branch) {
+      byBranch[e.branch] = (byBranch[e.branch] || 0) + 1;
+    }
+
+    if (e.type === "correction") {
+      corrections.push({
+        timestamp: e.timestamp,
+        content: (e.content || "").slice(0, 200),
+      });
+    }
+    if (e.type === "error") {
+      errors.push({
+        timestamp: e.timestamp,
+        content: (e.content || "").slice(0, 200),
+      });
+    }
+    if (e.type === "commit") {
+      let hash: string | undefined;
+      try {
+        const meta = JSON.parse(e.metadata || "{}");
+        hash = meta.hash || e.commit_hash;
+      } catch {
+        /* ignore */
+      }
+      commits.push({
+        timestamp: e.timestamp,
+        content: (e.content || "").slice(0, 120),
+        hash: hash?.slice(0, 7),
+      });
+    }
+  }
+
+  const sortedDays = Object.keys(byDay).sort();
+  return {
+    totalEvents: events.length,
+    byType,
+    byDay,
+    byBranch,
+    corrections,
+    errors,
+    commits,
+    activeDays: sortedDays.length,
+    dateRange: {
+      start: sortedDays[0] || "N/A",
+      end: sortedDays[sortedDays.length - 1] || "N/A",
+    },
+  };
+}
+
+function generateMarkdownReport(
+  stats: ReportStats,
+  projectName: string,
+  format: "summary" | "detailed" | "weekly",
+): string {
+  const lines: string[] = [];
+  const now = new Date().toISOString().slice(0, 10);
+
+  lines.push(`# ${projectName} — Session Report`);
+  lines.push(`_Generated ${now} | ${stats.dateRange.start} → ${stats.dateRange.end}_`);
+  lines.push("");
+
+  // Summary section
+  lines.push("## Summary");
+  lines.push("");
+  lines.push(`- **Total events:** ${stats.totalEvents}`);
+  lines.push(`- **Active days:** ${stats.activeDays}`);
+  lines.push(`- **Commits:** ${stats.byType["commit"] || 0}`);
+  lines.push(`- **Corrections:** ${stats.byType["correction"] || 0}`);
+  lines.push(`- **Errors:** ${stats.byType["error"] || 0}`);
+  lines.push("");
+
+  // Event breakdown
+  lines.push("## Event Breakdown");
+  lines.push("");
+  const sortedTypes = Object.entries(stats.byType).sort((a, b) => b[1] - a[1]);
+  for (const [type, count] of sortedTypes) {
+    const icon = TYPE_ICONS[type] || "❓";
+    const label = TYPE_LABELS[type] || type;
+    const pct = ((count / stats.totalEvents) * 100).toFixed(1);
+    lines.push(`- ${icon} **${label}:** ${count} (${pct}%)`);
+  }
+  lines.push("");
+
+  // Branch activity
+  if (Object.keys(stats.byBranch).length > 0) {
+    lines.push("## Branch Activity");
+    lines.push("");
+    const sortedBranches = Object.entries(stats.byBranch).sort((a, b) => b[1] - a[1]);
+    for (const [branch, count] of sortedBranches) {
+      lines.push(`- \`${branch}\`: ${count} events`);
+    }
+    lines.push("");
+  }
+
+  // Daily activity (for weekly/detailed)
+  if (format !== "summary") {
+    lines.push("## Daily Activity");
+    lines.push("");
+    const sortedDays = Object.entries(stats.byDay).sort((a, b) => a[0].localeCompare(b[0]));
+    for (const [day, count] of sortedDays) {
+      const bar = "█".repeat(Math.min(Math.ceil(count / 5), 20));
+      lines.push(`- **${day}:** ${count} events ${bar}`);
+    }
+    lines.push("");
+  }
+
+  // Commits log
+  if (stats.commits.length > 0 && format !== "summary") {
+    lines.push("## Commits");
+    lines.push("");
+    for (const c of stats.commits) {
+      const time = c.timestamp ? new Date(c.timestamp).toISOString().slice(0, 16).replace("T", " ") : "??";
+      const hash = c.hash ? `\`${c.hash}\` ` : "";
+      lines.push(`- ${time} — ${hash}${c.content}`);
+    }
+    lines.push("");
+  }
+
+  // Corrections & errors (quality signals)
+  if (stats.corrections.length > 0) {
+    lines.push("## Corrections");
+    lines.push(`_${stats.corrections.length} correction(s) logged — review for recurring patterns._`);
+    lines.push("");
+    for (const c of stats.corrections.slice(0, 10)) {
+      const time = c.timestamp ? new Date(c.timestamp).toISOString().slice(0, 16).replace("T", " ") : "??";
+      lines.push(`- ${time}: ${c.content}`);
+    }
+    if (stats.corrections.length > 10) {
+      lines.push(`- _...and ${stats.corrections.length - 10} more_`);
+    }
+    lines.push("");
+  }
+
+  if (stats.errors.length > 0) {
+    lines.push("## Errors");
+    lines.push(`_${stats.errors.length} error(s) captured._`);
+    lines.push("");
+    for (const e of stats.errors.slice(0, 10)) {
+      const time = e.timestamp ? new Date(e.timestamp).toISOString().slice(0, 16).replace("T", " ") : "??";
+      lines.push(`- ${time}: ${e.content}`);
+    }
+    if (stats.errors.length > 10) {
+      lines.push(`- _...and ${stats.errors.length - 10} more_`);
+    }
+    lines.push("");
+  }
+
+  // Prompt quality trends (ratio of corrections to prompts)
+  const prompts = stats.byType["prompt"] || 0;
+  const correctionCount = stats.byType["correction"] || 0;
+  if (prompts > 0) {
+    lines.push("## Quality Indicators");
+    lines.push("");
+    const correctionRate = ((correctionCount / prompts) * 100).toFixed(1);
+    const errorRate = (((stats.byType["error"] || 0) / stats.totalEvents) * 100).toFixed(1);
+    lines.push(`- **Correction rate:** ${correctionRate}% of prompts needed correction`);
+    lines.push(`- **Error rate:** ${errorRate}% of events were errors`);
+    if (correctionCount === 0) {
+      lines.push("- ✅ No corrections needed — clean session!");
+    } else if (parseFloat(correctionRate) > 20) {
+      lines.push("- ⚠️ High correction rate — consider refining prompts or using `preflight_check`");
+    }
+    lines.push("");
+  }
+
+  lines.push("---");
+  lines.push("_Report generated by preflight `export_report` tool._");
+
+  return lines.join("\n");
+}
+
+export function registerExportReport(server: McpServer) {
+  server.tool(
+    "export_report",
+    "Generate a markdown report from session timeline data. Includes event breakdown, commit log, correction/error analysis, and quality indicators. Use for weekly summaries, sprint reviews, or prompt quality audits.",
+    {
+      scope: z
+        .enum(["current", "related", "all"])
+        .default("current")
+        .describe("Search scope: current project, related projects, or all indexed"),
+      project: z
+        .string()
+        .optional()
+        .describe("Filter to a specific project (overrides scope)"),
+      since: z
+        .string()
+        .optional()
+        .describe("Start date (ISO or relative like '7days', '2weeks')"),
+      until: z
+        .string()
+        .optional()
+        .describe("End date (ISO or relative)"),
+      branch: z.string().optional().describe("Filter to a specific branch"),
+      format: z
+        .enum(["summary", "detailed", "weekly"])
+        .default("weekly")
+        .describe(
+          "Report format: summary (brief overview), detailed (full log), weekly (balanced default)",
+        ),
+    },
+    async (params) => {
+      const since = params.since ? parseRelativeDate(params.since) : undefined;
+      const until = params.until ? parseRelativeDate(params.until) : undefined;
+
+      let projectDirs: string[];
+      if (params.project) {
+        projectDirs = [params.project];
+      } else {
+        projectDirs = await getSearchProjects(params.scope);
+      }
+
+      if (projectDirs.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `## Export Report\n_No projects found for scope "${params.scope}". Onboard a project first with \`onboard_project\`._`,
+            },
+          ],
+        };
+      }
+
+      // Fetch all events (high limit for report generation)
+      const events = await getTimeline({
+        project_dirs: projectDirs,
+        branch: params.branch,
+        since,
+        until,
+        limit: 5000,
+      });
+
+      if (events.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "## Export Report\n_No events found for the given filters. Try broadening your date range or scope._",
+            },
+          ],
+        };
+      }
+
+      const projectName =
+        params.project || (projectDirs.length === 1 ? projectDirs[0].split("/").pop() : "Multi-project");
+
+      const stats = computeStats(events);
+      const report = generateMarkdownReport(stats, projectName!, params.format);
+
+      return { content: [{ type: "text", text: report }] };
+    },
+  );
+}