@uniqbit/mate-core 0.15.1 → 0.15.2-canary.0

package/src/cli/commands/report/index.ts

@@ -1,5 +1,4 @@
-import fs from "node:fs/promises";
-import path from "node:path";
+import { readFile } from "node:fs/promises";
 
 import { resolveFrameworkContext } from "../../../lib/orchestrator/framework-context";
 import { ensureUnambiguousCompanion } from "../shared/companion-selection";
@@ -10,149 +9,211 @@ import {
   collectTokenSaveSavings,
   mergeResults,
 } from "./collector";
-import { renderJSON, renderMarkdown } from "./renderer";
 import type { CollectorDeps } from "./collector";
-import type { ReportData, ReportOptions } from "./types";
+import { reportDataToDocument } from "./adapter";
+import { parseReportDocument, type ReportValidationError } from "./contract";
+import { openReportInBrowser, writeTemporaryReport } from "./delivery";
+import { renderHTML, renderJSON } from "./renderer";
+import type { ReportData, ReportDocument, ReportOptions } from "./types";
 
 interface ReportCommandDeps extends CollectorDeps {
   ensureUnambiguousCompanion?: (cwd: string) => Promise<boolean>;
   resolveFrameworkContext?: typeof resolveFrameworkContext;
+  writeTemporaryReport?: typeof writeTemporaryReport;
+  openReportInBrowser?: typeof openReportInBrowser;
+  readInput?: (input: string) => Promise<string>;
 }
 
 function parseOptions(argv: string[]): ReportOptions {
   let days = 7;
   let json = false;
+  let input: string | undefined;
+  let daysSpecified = false;
 
   for (let i = 0; i < argv.length; i++) {
-    if (argv[i] === "--days" && argv[i + 1]) {
-      days = parseInt(argv[i + 1], 10);
-      if (isNaN(days) || days < 1) days = 7;
+    if (argv[i] === "--days") {
+      daysSpecified = true;
+      const value = argv[i + 1];
+      if (!value) throw new Error("--days requires a positive integer");
+      days = Number.parseInt(value, 10);
+      if (!Number.isInteger(days) || days < 1) {
+        throw new Error("--days requires a positive integer");
+      }
       i++;
+      continue;
     }
-    if (argv[i] === "--json") {
-      json = true;
+    if (argv[i] === "--input") {
+      const value = argv[i + 1];
+      if (!value) throw new Error("--input requires a JSON file path or - for stdin");
+      if (input !== undefined) throw new Error("--input may only be provided once");
+      input = value;
+      i++;
+      continue;
     }
+    if (argv[i] === "--json") json = true;
   }
 
-  return { days, json };
+  if (input !== undefined && daysSpecified) {
+    throw new Error("--days cannot be combined with --input; the document supplies its own period");
+  }
+  return { days, json, input };
+}
+
+async function readStdin(): Promise<string> {
+  const chunks: Uint8Array[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(typeof chunk === "string" ? new TextEncoder().encode(chunk) : chunk);
+  }
+  const size = chunks.reduce((total, chunk) => total + chunk.byteLength, 0);
+  const result = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    result.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return new TextDecoder().decode(result);
+}
+
+async function readStructuredInput(input: string, deps: ReportCommandDeps): Promise<string> {
+  if (deps.readInput) return deps.readInput(input);
+  return input === "-" ? readStdin() : readFile(input, "utf8");
+}
+
+function validationMessage(error: unknown): string {
+  if (error && typeof error === "object" && "issues" in error) {
+    const issues = (error as ReportValidationError).issues;
+    return issues.map((issue) => `${issue.path}: ${issue.message}`).join("; ");
+  }
+  return error instanceof Error ? error.message : String(error);
 }
 
 /**
- * @command mate report [--days N] [--json]
- * @description Generates a token usage report aggregating spending (via ccusage)
- * and savings (via TokenSave/Headroom), merged across working and companion repos.
- * Writes REPORT.md to companion repo by default. Use --json for machine-readable stdout.
+ * @command mate report [--days N] [--input FILE|-] [--json]
+ * @description Generates a usage report from built-in collectors or a validated JSON document.
  */
 export async function runReportCommand(
   argv: string[] = [],
   deps: ReportCommandDeps = {},
 ): Promise<void> {
-  const resolveCtx = deps.resolveFrameworkContext ?? resolveFrameworkContext;
-  const ensureCompanion = deps.ensureUnambiguousCompanion ?? ensureUnambiguousCompanion;
-  const options = parseOptions(argv);
-
-  if (!(await ensureCompanion(process.cwd()))) {
+  let options: ReportOptions;
+  try {
+    options = parseOptions(argv);
+  } catch (error) {
+    console.error(`Invalid report options: ${validationMessage(error)}`);
     process.exitCode = 1;
     return;
   }
 
-  const { companionPath, configStore, workingRepoStore, repository, contextKind } =
-    await resolveCtx(process.cwd());
-  const config = await configStore.load();
-  const working =
-    repository || contextKind === "companion-root" ? null : await workingRepoStore.load();
-
-  const workingRepoPath = repository?.path ?? working?.repos[0]?.path ?? process.cwd();
-  const companionRepoPath = companionPath;
-  const capabilities = config.capabilities ?? [];
-  const enabledCapabilities = capabilities.map((c) => c.name);
-  const activeAgents = process.env.MATE_ALLOWED_AGENTS
-    ? process.env.MATE_ALLOWED_AGENTS.split(",")
-        .map((a) => a.trim())
-        .filter(Boolean)
-    : [];
-
-  const tokensaveEnabled = enabledCapabilities.includes("tokensave");
-  const headroomEnabled = enabledCapabilities.includes("headroom");
-  const rtkEnabled = enabledCapabilities.includes("rtk");
-
-  // Collect spending via ccusage (covers all agents: Claude, OpenCode, Codex, etc.)
-  const ccusageResult = await collectCcusageSpending(options.days, deps);
-  if (ccusageResult.friendlyError) {
-    console.warn(ccusageResult.friendlyError);
-  }
-
-  // Collect savings in parallel
-  let tokensaveWorking: Awaited<ReturnType<typeof collectTokenSaveSavings>> = {
-    entry: null,
-    status: { name: "tokensave (savings)", enabled: false, status: "not enabled" },
-  };
-  let tokensaveCompanion: Awaited<ReturnType<typeof collectTokenSaveSavings>> = {
-    entry: null,
-    status: { name: "tokensave (savings)", enabled: false, status: "not enabled" },
-  };
-  let rtkResult: Awaited<ReturnType<typeof collectRTKSavings>> = {
-    entry: null,
-    status: { name: "rtk", enabled: false, status: "not enabled" },
-  };
-  let headroomResult: Awaited<ReturnType<typeof collectHeadroomSavings>> = {
-    entry: null,
-    status: { name: "headroom", enabled: false, status: "not enabled" },
-  };
-
-  if (tokensaveEnabled) {
-    [tokensaveWorking, tokensaveCompanion] = await Promise.all([
-      collectTokenSaveSavings(workingRepoPath, options.days, deps),
-      collectTokenSaveSavings(companionRepoPath, options.days, deps),
-    ]);
-  }
-
-  if (rtkEnabled) {
-    rtkResult = await collectRTKSavings(workingRepoPath, deps);
+  const ensureCompanion = deps.ensureUnambiguousCompanion ?? ensureUnambiguousCompanion;
+  if (!(await ensureCompanion(process.cwd()))) {
+    process.exitCode = 1;
+    return;
   }
 
-  if (headroomEnabled) {
-    headroomResult = await collectHeadroomSavings(options.days, deps);
+  let reportDocument: ReportDocument;
+  if (options.input !== undefined) {
+    try {
+      reportDocument = parseReportDocument(await readStructuredInput(options.input, deps));
+    } catch (error) {
+      console.error(`Invalid report input: ${validationMessage(error)}`);
+      process.exitCode = 1;
+      return;
+    }
+  } else {
+    const resolveCtx = deps.resolveFrameworkContext ?? resolveFrameworkContext;
+    const { companionPath, configStore, workingRepoStore, repository, contextKind } =
+      await resolveCtx(process.cwd());
+    const config = await configStore.load();
+    const working =
+      repository || contextKind === "companion-root" ? null : await workingRepoStore.load();
+
+    const workingRepoPath = repository?.path ?? working?.repos[0]?.path ?? process.cwd();
+    const capabilities = config.capabilities ?? [];
+    const enabledCapabilities = capabilities.map((c) => c.name);
+    const activeAgents = process.env.MATE_ALLOWED_AGENTS
+      ? process.env.MATE_ALLOWED_AGENTS.split(",")
+          .map((a) => a.trim())
+          .filter(Boolean)
+      : [];
+
+    const tokensaveEnabled = enabledCapabilities.includes("tokensave");
+    const headroomEnabled = enabledCapabilities.includes("headroom");
+    const rtkEnabled = enabledCapabilities.includes("rtk");
+
+    const ccusageResult = await collectCcusageSpending(options.days, deps);
+    if (ccusageResult.friendlyError) console.warn(ccusageResult.friendlyError);
+
+    let tokensaveWorking: Awaited<ReturnType<typeof collectTokenSaveSavings>> = {
+      entry: null,
+      status: { name: "tokensave (savings)", enabled: false, status: "not enabled" },
+    };
+    let tokensaveCompanion: Awaited<ReturnType<typeof collectTokenSaveSavings>> = {
+      entry: null,
+      status: { name: "tokensave (savings)", enabled: false, status: "not enabled" },
+    };
+    let rtkResult: Awaited<ReturnType<typeof collectRTKSavings>> = {
+      entry: null,
+      status: { name: "rtk", enabled: false, status: "not enabled" },
+    };
+    let headroomResult: Awaited<ReturnType<typeof collectHeadroomSavings>> = {
+      entry: null,
+      status: { name: "headroom", enabled: false, status: "not enabled" },
+    };
+
+    if (tokensaveEnabled) {
+      [tokensaveWorking, tokensaveCompanion] = await Promise.all([
+        collectTokenSaveSavings(workingRepoPath, options.days, deps),
+        collectTokenSaveSavings(companionPath, options.days, deps),
+      ]);
+    }
+    if (rtkEnabled) rtkResult = await collectRTKSavings(workingRepoPath, deps);
+    if (headroomEnabled) headroomResult = await collectHeadroomSavings(options.days, deps);
+
+    const merged = mergeResults(
+      ccusageResult.entries,
+      tokensaveWorking.entry,
+      tokensaveCompanion.entry,
+      rtkResult.entry,
+      headroomResult.entry,
+    );
+    const reportData: ReportData = {
+      days: options.days,
+      generatedAt: new Date().toISOString(),
+      workingRepoPath,
+      companionRepoPath: companionPath,
+      activeAgents,
+      enabledCapabilities,
+      spending: merged.spending,
+      savings: merged.savings,
+      toolStatus: [
+        ccusageResult.status,
+        tokensaveWorking.status,
+        rtkResult.status,
+        headroomResult.status,
+      ],
+      totalSpending: merged.totalSpending,
+      totalSavings: merged.totalSavings,
+      netSpend: merged.netSpend,
+    };
+    reportDocument = reportDataToDocument(reportData);
   }
 
-  // Merge results
-  const merged = mergeResults(
-    ccusageResult.entries,
-    tokensaveWorking.entry,
-    tokensaveCompanion.entry,
-    rtkResult.entry,
-    headroomResult.entry,
-  );
-
-  const allToolStatus = [
-    ccusageResult.status,
-    tokensaveWorking.status,
-    rtkResult.status,
-    headroomResult.status,
-  ];
-
-  const reportData: ReportData = {
-    days: options.days,
-    generatedAt: new Date().toISOString(),
-    workingRepoPath,
-    companionRepoPath,
-    activeAgents,
-    enabledCapabilities,
-    spending: merged.spending,
-    savings: merged.savings,
-    toolStatus: allToolStatus,
-    totalSpending: merged.totalSpending,
-    totalSavings: merged.totalSavings,
-    netSpend: merged.netSpend,
-  };
-
   if (options.json) {
-    console.log(renderJSON(reportData));
+    console.log(renderJSON(reportDocument));
     return;
   }
 
-  const markdown = renderMarkdown(reportData);
-  const reportPath = path.join(companionRepoPath, "REPORT.md");
-  await fs.writeFile(reportPath, markdown);
-  console.log(`Report written to ${reportPath}`);
+  let reportPath: string | undefined;
+  try {
+    reportPath = await (deps.writeTemporaryReport ?? writeTemporaryReport)(
+      renderHTML(reportDocument),
+    );
+    await (deps.openReportInBrowser ?? openReportInBrowser)(reportPath);
+    console.log(`Report opened from ${reportPath}`);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const location = reportPath ? ` at ${reportPath}` : "";
+    console.warn(`Unable to open HTML report${location}: ${message}`);
+    console.log(renderJSON(reportDocument));
+  }
 }

package/src/cli/commands/report/renderer.ts

@@ -1,108 +1,263 @@
-import type { ReportData } from "./types";
-import { formatCost, formatTokens } from "./formatter";
+import { reportDataToDocument } from "./adapter";
+import { validateReportDocument } from "./contract";
+import type {
+  ReportData,
+  ReportDocument,
+  ReportKeyValue,
+  ReportSection,
+  ReportValue,
+} from "./types";
+
+type RenderInput = ReportDocument | ReportData;
+
+function isReportDocument(input: RenderInput): input is ReportDocument {
+  return "version" in input;
+}
+
+function normalize(input: RenderInput): ReportDocument {
+  return validateReportDocument(isReportDocument(input) ? input : reportDataToDocument(input));
+}
+
+function valueToString(value: ReportValue): string {
+  if (value === null) return "N/A";
+  return String(value);
+}
 
 function renderTable(headers: string[], rows: string[][]): string {
-  if (rows.length === 0) {
-    return `| ${headers.join(" | ")} |\n`;
-  }
+  if (rows.length === 0) return `| ${headers.join(" | ")} |`;
 
   const widths = headers.map((header, index) =>
     Math.max(header.length, ...rows.map((row) => (row[index] ?? "").length)),
   );
-
   const renderRow = (row: string[]): string =>
     `| ${row.map((value, index) => value.padEnd(widths[index])).join(" | ")} |`;
-
   const divider = `| ${widths.map((width) => "-".repeat(width)).join(" | ")} |`;
   return [renderRow(headers), divider, ...rows.map(renderRow)].join("\n");
 }
 
-function renderKeyValueTable(rows: Array<[string, string]>): string {
-  return renderTable(["Field", "Value"], rows);
+function renderKeyValueTable(rows: ReportKeyValue[]): string {
+  return renderTable(
+    ["Field", "Value"],
+    rows.map((row) => [row.label, valueToString(row.value)]),
+  );
 }
 
 function printSection(title: string, body: string): string {
   return `${title}\n\n${body}\n`;
 }
 
-export function renderMarkdown(data: ReportData): string {
-  const sections: string[] = [];
+function emptyTableMessage(title: string): string {
+  const normalized = title.toLowerCase();
+  return normalized === "spending" || normalized === "savings"
+    ? `No ${normalized} data available.`
+    : "No data available.";
+}
 
-  // Header
-  sections.push(`# Token Usage Report\n`);
-  sections.push(
-    renderKeyValueTable([
-      ["Window", `Last ${data.days} days`],
-      ["Generated", data.generatedAt],
-      ["Capabilities", data.enabledCapabilities.join(", ") || "None"],
-    ]),
-  );
+function sectionMarkdown(section: ReportSection): string {
+  switch (section.type) {
+    case "metadata":
+    case "key-value":
+      return renderKeyValueTable(section.items);
+    case "metrics":
+      return renderTable(
+        ["Metric", "Value"],
+        section.items.map((item) => [item.label, valueToString(item.value)]),
+      );
+    case "table":
+      return section.rows.length
+        ? renderTable(
+            section.columns,
+            section.rows.map((row) => row.map(valueToString)),
+          )
+        : emptyTableMessage(section.title);
+    case "statuses":
+      return section.items.length
+        ? renderTable(
+            ["Status", "Value"],
+            section.items.map((item) => [
+              item.label,
+              item.detail ? `${item.status}: ${item.detail}` : item.status,
+            ]),
+          )
+        : "No data available.";
+    case "text":
+      return section.content;
+  }
+}
 
-  // Summary
+export function renderMarkdown(input: RenderInput): string {
+  const data = normalize(input);
+  const sections: string[] = [`# ${data.title}\n`];
+  const metadata = [...data.metadata];
+  if (data.period) metadata.unshift({ label: "Period", value: data.period });
+  if (data.context) metadata.push({ label: "Context", value: data.context });
+  sections.push(renderKeyValueTable(metadata));
   sections.push(
     "\n" +
       printSection(
         "## Summary",
-        renderKeyValueTable([
-          ["Total Spending", formatCost(data.totalSpending)],
-          ["Total Savings", formatCost(data.totalSavings)],
-          ["Net Spend", formatCost(data.netSpend)],
-        ]),
-      ),
-  );
-
-  // Spending
-  if (data.spending.length > 0) {
-    const spendingRows = data.spending.map((entry) => [
-      entry.model,
-      formatTokens(entry.inputTokens),
-      formatTokens(entry.outputTokens),
-      formatTokens(entry.cacheReadTokens),
-      formatTokens(entry.cacheWriteTokens),
-      formatCost(entry.cost),
-    ]);
-    sections.push(
-      printSection(
-        "## Spending",
         renderTable(
-          ["Model", "Input", "Output", "Cache Read", "Cache Write", "Cost (est.)"],
-          spendingRows,
+          ["Metric", "Value"],
+          data.summary.map((item) => [item.label, valueToString(item.value)]),
         ),
       ),
-    );
-  } else {
-    sections.push(printSection("## Spending", "No spending data available."));
+  );
+  for (const section of data.sections) {
+    sections.push(printSection(`## ${section.title}`, sectionMarkdown(section)));
   }
+  return sections.join("\n");
+}
 
-  // Savings
-  if (data.savings.length > 0) {
-    const savingsRows = data.savings.map((entry) => [
-      entry.tool,
-      entry.tokensSaved === 0 ? "N/A" : formatTokens(entry.tokensSaved),
-      String(entry.calls),
-      entry.costSaved === 0 ? "N/A" : formatCost(entry.costSaved),
-      entry.efficiency,
-    ]);
-    sections.push(
-      printSection(
-        "## Savings",
-        renderTable(["Tool", "Tokens Saved", "Calls", "Cost Saved", "Efficiency"], savingsRows),
-      ),
-    );
-  } else {
-    sections.push(printSection("## Savings", "No savings data available."));
-  }
+export function renderJSON(input: RenderInput): string {
+  if (!isReportDocument(input)) return JSON.stringify(input, null, 2);
+  return JSON.stringify(normalize(input), null, 2);
+}
 
-  // Tool Status
-  const toolStatusRows = data.toolStatus.map((entry) => {
-    const icon = entry.enabled ? "✅" : "⏸️";
-    return [entry.name, `${icon} ${entry.status}`];
+function escapeHTML(value: string): string {
+  return value.replace(/[&<>"']/g, (character) => {
+    switch (character) {
+      case "&":
+        return "&amp;";
+      case "<":
+        return "&lt;";
+      case ">":
+        return "&gt;";
+      case '"':
+        return "&quot;";
+      default:
+        return "&#39;";
+    }
   });
-  sections.push(printSection("## Tool Status", renderTable(["Tool", "Status"], toolStatusRows)));
+}
 
-  return sections.join("\n");
+function renderHTMLTable(headers: string[], rows: string[][]): string {
+  const headerHTML = headers.map((header) => `<th scope="col">${escapeHTML(header)}</th>`).join("");
+  const rowsHTML = rows.length
+    ? rows
+        .map((row) => `<tr>${row.map((value) => `<td>${escapeHTML(value)}</td>`).join("")}</tr>`)
+        .join("")
+    : "";
+  return `<div class="table-wrap"><table><thead><tr>${headerHTML}</tr></thead><tbody>${rowsHTML}</tbody></table></div>`;
 }
 
-export function renderJSON(data: ReportData): string {
-  return JSON.stringify(data, null, 2);
+function emptyHTML(message: string): string {
+  return `<p class="empty">${escapeHTML(message)}</p>`;
 }
+
+function renderHTMLKeyValues(items: ReportKeyValue[]): string {
+  return items.length
+    ? renderHTMLTable(
+        ["Field", "Value"],
+        items.map((item) => [item.label, valueToString(item.value)]),
+      )
+    : emptyHTML("No metadata available.");
+}
+
+function renderHTMLSectionBody(section: ReportSection): string {
+  switch (section.type) {
+    case "metadata":
+    case "key-value":
+      return renderHTMLKeyValues(section.items);
+    case "metrics":
+      return section.items.length
+        ? renderHTMLTable(
+            ["Metric", "Value"],
+            section.items.map((item) => [item.label, valueToString(item.value)]),
+          )
+        : emptyHTML("No metrics available.");
+    case "table":
+      return section.rows.length
+        ? renderHTMLTable(
+            section.columns,
+            section.rows.map((row) => row.map(valueToString)),
+          )
+        : emptyHTML(emptyTableMessage(section.title));
+    case "statuses":
+      return section.items.length
+        ? renderHTMLTable(
+            ["Status", "Value"],
+            section.items.map((item) => [
+              item.label,
+              item.detail ? `${item.status}: ${item.detail}` : item.status,
+            ]),
+          )
+        : emptyHTML("No status data available.");
+    case "text":
+      return section.content
+        ? `<p class="report-text">${escapeHTML(section.content).replaceAll("\n", "<br>")}</p>`
+        : emptyHTML("No text available.");
+  }
+}
+
+function renderHTMLSection(section: ReportSection): string {
+  return `<section id="${escapeHTML(section.id)}"><h2>${escapeHTML(section.title)}</h2>${renderHTMLSectionBody(section)}</section>`;
+}
+
+export function renderHTML(input: RenderInput): string {
+  const data = normalize(input);
+  const legacy = isReportDocument(input) ? undefined : input;
+  const metadata = [...data.metadata];
+  if (data.period) metadata.unshift({ label: "Period", value: data.period });
+  if (data.context) metadata.push({ label: "Context", value: data.context });
+  const summary: ReportMetricsSection = {
+    id: "summary",
+    title: "Summary",
+    type: "metrics",
+    items: data.summary,
+  };
+
+  const repositoryAttributes = legacy
+    ? ` data-working-repository="${escapeHTML(legacy.workingRepoPath)}" data-companion-repository="${escapeHTML(legacy.companionRepoPath)}"`
+    : "";
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>${escapeHTML(data.title)}</title>
+  <style>
+    :root { color-scheme: light; font-family: system-ui, sans-serif; background: #f4f6f8; color: #18212b; }
+    body { margin: 0; }
+    .report { max-width: 1120px; margin: 0 auto; padding: 32px 20px 56px; }
+    header, section { background: #fff; border: 1px solid #dce2e8; border-radius: 14px; margin-bottom: 20px; padding: 24px; box-shadow: 0 8px 24px rgb(24 33 43 / 6%); }
+    h1, h2 { margin-top: 0; }
+    h1 { margin-bottom: 8px; }
+    h2 { font-size: 1.15rem; }
+    .eyebrow { color: #536273; font-size: .8rem; font-weight: 700; letter-spacing: .08em; text-transform: uppercase; }
+    .print-control { background: #18212b; border: 0; border-radius: 8px; color: #fff; cursor: pointer; padding: 10px 14px; }
+    .table-wrap { overflow-x: auto; }
+    table { border-collapse: collapse; min-width: 100%; }
+    th, td { border-bottom: 1px solid #e8edf1; padding: 10px 12px; text-align: left; vertical-align: top; }
+    th { color: #536273; font-size: .8rem; text-transform: uppercase; }
+    .empty { color: #536273; margin: 0; }
+    @media (max-width: 640px) { .report { padding: 16px 12px 32px; } header, section { padding: 16px; } }
+    @media print {
+      :root, body { background: #fff; color: #000; }
+      .report { max-width: none; padding: 0; }
+      header, section { border: 0; border-radius: 0; box-shadow: none; margin-bottom: 16px; padding: 0; }
+      .print-control, .interactive-only { display: none !important; }
+      .table-wrap { overflow: visible; }
+      table { width: 100%; }
+      th, td { color: #000; }
+    }
+  </style>
+</head>
+<body>
+  <main class="report" data-report-version="${data.version}"${repositoryAttributes}>
+    <header>
+      <p class="eyebrow">Mate report</p>
+      <h1>${escapeHTML(data.title)}</h1>
+      ${renderHTMLKeyValues(metadata)}
+      <button class="print-control interactive-only" type="button" onclick="window.print()">Print / Save as PDF</button>
+    </header>
+    ${renderHTMLSection(summary)}
+    ${data.sections.map(renderHTMLSection).join("\n    ")}
+  </main>
+</body>
+</html>`;
+}
+
+type ReportMetricsSection = Extract<ReportSection, { type: "metrics" }>;
+
+export { escapeHTML };