@karmaniverous/jeeves-server 3.0.0-0

package/src/services/export.ts

@@ -0,0 +1,267 @@
+/**
+ * Export service for PDF and DOCX generation.
+ *
+ * Orchestrates Puppeteer page loading, print styling, and format-specific
+ * export logic. Heavy lifting delegated to puppeteer.ts utilities.
+ */
+
+import HtmlToDocx from '@turbodocx/html-to-docx';
+
+import {
+  addPrintStyles,
+  captureSvgsAsPng,
+  launchBrowser,
+  SVG_CONTAINER_SELECTORS,
+  waitForSpaContent,
+} from './puppeteer.js';
+
+export type ExportFormat = 'pdf' | 'docx';
+
+export interface ExportOptions {
+  url: string;
+  fileName: string;
+  format: ExportFormat;
+}
+
+// Max bounds for images in DOCX (6 inches × 8 inches at 96dpi)
+const MAX_WIDTH_PX = 576;
+const MAX_HEIGHT_PX = 768;
+
+/**
+ * Export page as PDF.
+ */
+export async function exportPDF(options: ExportOptions): Promise<Buffer> {
+  const browser = await launchBrowser();
+  try {
+    const page = await browser.newPage();
+    await page.goto(options.url, { waitUntil: 'networkidle0' });
+    await waitForSpaContent(page);
+    await addPrintStyles(page);
+
+    const pdfBuffer = await page.pdf({
+      format: 'A4',
+      margin: { top: '1cm', right: '1cm', bottom: '1cm', left: '1cm' },
+      printBackground: true,
+    });
+
+    return Buffer.from(pdfBuffer);
+  } finally {
+    await browser.close();
+  }
+}
+
+/**
+ * Export page as DOCX.
+ */
+export async function exportDOCX(options: ExportOptions): Promise<Buffer> {
+  const browser = await launchBrowser();
+  try {
+    const page = await browser.newPage();
+    await page.setViewport({ width: 1200, height: 800 });
+    await page.goto(options.url, { waitUntil: 'networkidle0' });
+    await waitForSpaContent(page);
+    await addPrintStyles(page);
+
+    // Capture SVGs as PNGs for DOCX embedding
+    const svgPngDataUrls = await captureSvgsAsPng(browser, page);
+
+    // Get processed HTML with SVGs replaced by PNGs
+    const processedHtml = await page.evaluate(
+      (
+        pngUrls: typeof svgPngDataUrls,
+        maxW: number,
+        maxH: number,
+        selectors: string,
+      ) => {
+        function calcScaled(
+          origW: number,
+          origH: number,
+        ): { width: number; height: number } {
+          let w = origW,
+            h = origH;
+          if (w > maxW) {
+            const s = maxW / w;
+            w = maxW;
+            h = Math.round(h * s);
+          }
+          if (h > maxH) {
+            const s = maxH / h;
+            h = maxH;
+            w = Math.round(w * s);
+          }
+          return { width: w, height: h };
+        }
+
+        const content =
+          document.querySelector('article.prose') ??
+          document.querySelector('.content');
+        if (!content) return '<p>No content</p>';
+
+        const contentClone = content.cloneNode(true) as HTMLElement;
+        contentClone.querySelectorAll('a.anchor').forEach((el) => {
+          el.remove();
+        });
+
+        // Replace SVG containers with PNG images
+        const svgContainers = contentClone.querySelectorAll(selectors);
+        svgContainers.forEach((container, i) => {
+          const pngInfo = pngUrls.find((p) => p.index === i);
+          if (pngInfo) {
+            const img = document.createElement('img');
+            img.src = pngInfo.dataUrl;
+            img.alt = 'Diagram';
+            const dims = calcScaled(pngInfo.width, pngInfo.height);
+            img.setAttribute('width', String(dims.width));
+            img.setAttribute('height', String(dims.height));
+            container.replaceWith(img);
+          } else {
+            const p = document.createElement('p');
+            p.textContent = '[Diagram]';
+            p.style.fontStyle = 'italic';
+            container.replaceWith(p);
+          }
+        });
+
+        // Fix image URLs and set explicit dimensions
+        contentClone.querySelectorAll('img').forEach((img) => {
+          if (img.src && !img.src.startsWith('data:')) {
+            img.src = new URL(img.src, window.location.origin).href;
+          }
+          const origW = img.naturalWidth || img.width || 400;
+          const origH = img.naturalHeight || img.height || 300;
+          const dims = calcScaled(origW, origH);
+          img.setAttribute('width', String(dims.width));
+          img.setAttribute('height', String(dims.height));
+          img.style.maxWidth = '';
+          img.style.maxHeight = '';
+        });
+
+        // Inline styles for tables
+        contentClone.querySelectorAll('table').forEach((t) => {
+          t.setAttribute('border', '1');
+          (t as HTMLElement).style.borderCollapse = 'collapse';
+          (t as HTMLElement).style.width = '100%';
+        });
+        contentClone.querySelectorAll('th').forEach((th) => {
+          (th as HTMLElement).style.backgroundColor = '#f0f0f0';
+          (th as HTMLElement).style.fontWeight = 'bold';
+          (th as HTMLElement).style.padding = '8px';
+          (th as HTMLElement).style.border = '1px solid #999';
+        });
+        contentClone.querySelectorAll('td').forEach((td) => {
+          (td as HTMLElement).style.padding = '8px';
+          (td as HTMLElement).style.border = '1px solid #999';
+        });
+
+        // Inline styles for code blocks — wrap in single-cell table for
+        // consistent block background in DOCX (html-to-docx doesn't support
+        // background-color on pre as a block fill)
+        contentClone.querySelectorAll('pre').forEach((pre) => {
+          const text = pre.textContent || '';
+          const table = document.createElement('table');
+          table.setAttribute('border', '1');
+          table.style.borderCollapse = 'collapse';
+          table.style.width = '100%';
+          table.style.marginTop = '8px';
+          table.style.marginBottom = '8px';
+          const tr = document.createElement('tr');
+          const td = document.createElement('td');
+          td.style.backgroundColor = '#f5f5f5';
+          td.style.border = '1px solid #ddd';
+          td.style.padding = '12px';
+          // Build one <p> per line with monospace styling and &nbsp; for
+          // indentation. html-to-docx converts each <p> to a Word paragraph
+          // cleanly, without the double-spacing that <br> causes.
+          const lines = text.split('\n');
+          lines.forEach((line) => {
+            const p = document.createElement('p');
+            p.style.fontFamily = 'Consolas, monospace';
+            p.style.fontSize = '9pt';
+            p.style.margin = '0';
+            p.style.lineHeight = '1.3';
+            // Preserve leading whitespace with &nbsp;
+            const leadingSpaces = line.match(/^( +)/);
+            if (leadingSpaces) {
+              const nbsp = '\u00A0'.repeat(leadingSpaces[1].length);
+              p.textContent = nbsp + line.slice(leadingSpaces[1].length);
+            } else {
+              p.textContent = line || '\u00A0'; // empty lines need content
+            }
+            td.appendChild(p);
+          });
+          tr.appendChild(td);
+          table.appendChild(tr);
+          pre.replaceWith(table);
+        });
+
+        return contentClone.innerHTML;
+      },
+      svgPngDataUrls,
+      MAX_WIDTH_PX,
+      MAX_HEIGHT_PX,
+      SVG_CONTAINER_SELECTORS,
+    );
+
+    await browser.close();
+
+    const fullHtml = buildDocxHtml(processedHtml);
+    const baseName = options.fileName.replace(/\.md$/i, '');
+
+    const docxBuffer = await HtmlToDocx(fullHtml, null, {
+      title: baseName,
+      creator: 'Jeeves Server',
+      table: { row: { cantSplit: true } },
+      imageProcessing: {
+        svgHandling: 'native',
+        maxRetries: 2,
+        downloadTimeout: 15000,
+      },
+    });
+
+    return Buffer.isBuffer(docxBuffer)
+      ? docxBuffer
+      : Buffer.from(docxBuffer as ArrayBuffer);
+  } finally {
+    await browser.close();
+  }
+}
+
+/**
+ * Export page based on format.
+ */
+export async function exportPage(options: ExportOptions): Promise<Buffer> {
+  return options.format === 'pdf' ? exportPDF(options) : exportDOCX(options);
+}
+
+/** Build a clean HTML document for DOCX conversion. */
+function buildDocxHtml(bodyContent: string): string {
+  return `<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <style>
+    body { font-family: Calibri, Arial, sans-serif; font-size: 10pt; line-height: 1.6; }
+    h1 { font-size: 18pt; font-weight: bold; color: #1a1a1a; margin-top: 20pt; margin-bottom: 10pt; }
+    h2 { font-size: 14pt; font-weight: bold; color: #2a2a2a; margin-top: 16pt; margin-bottom: 8pt; }
+    h3 { font-size: 12pt; font-weight: bold; color: #3a3a3a; margin-top: 12pt; margin-bottom: 6pt; }
+    h4 { font-size: 10pt; font-weight: bold; color: #4a4a4a; margin-top: 10pt; margin-bottom: 5pt; }
+    p { margin: 5pt 0; }
+    code { font-family: Consolas, 'Courier New', monospace; font-size: 9pt; background-color: #f4f4f4; padding: 2pt 4pt; }
+    pre { font-family: Consolas, 'Courier New', monospace; font-size: 8pt; background-color: #f8f8f8; border: 1pt solid #ddd; padding: 10pt; margin: 10pt 0; white-space: pre-wrap; word-wrap: break-word; }
+    pre code { background-color: transparent; padding: 0; }
+    table { border-collapse: collapse; width: 100%; margin: 12pt 0; }
+    th { background-color: #f0f0f0; font-weight: bold; border: 1pt solid #999; padding: 8pt; text-align: left; }
+    td { border: 1pt solid #999; padding: 8pt; text-align: left; }
+    tr:nth-child(even) td { background-color: #fafafa; }
+    blockquote { border-left: 4pt solid #ddd; margin: 12pt 0; padding: 6pt 12pt; color: #666; }
+    ul, ol { margin: 6pt 0; padding-left: 24pt; }
+    li { margin: 4pt 0; }
+    a { color: #0066cc; }
+    img, svg { margin: 12pt 0; display: block; }
+  </style>
+</head>
+<body>
+${bodyContent}
+</body>
+</html>`;
+}

package/src/services/exportCache.ts

@@ -0,0 +1,216 @@
+/**
+ * Export cache for PDF/DOCX renders.
+ *
+ * Cache key = sha256(normalizedFsPath + NUL + format).
+ * Invalidation: source file mtime greater than cache file mtime = miss.
+ * Also maintains a reverse index (fsPath to diagram cache hashes) so
+ * "Clear Cache" can purge both export and diagram caches for a file.
+ */
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+let cacheDir: string | null = null;
+
+/** Diagram type for a given file extension. */
+const DIAGRAM_EXT_MAP: Record<string, string> = {
+  '.mmd': 'mermaid',
+  '.puml': 'plantuml',
+  '.plantuml': 'plantuml',
+  '.pu': 'plantuml',
+};
+
+/** Initialize the export cache directory. Call once at startup. */
+export function initExportCache(dir?: string): void {
+  cacheDir = dir ?? path.resolve('.export-cache');
+  fs.mkdirSync(cacheDir, { recursive: true });
+}
+
+function cacheKey(fsPath: string, format: string): string {
+  const normalized = fsPath.replace(/\\/g, '/').toLowerCase();
+  return crypto
+    .createHash('sha256')
+    .update(`${normalized}\0${format}`)
+    .digest('hex');
+}
+
+function cacheFilePath(fsPath: string, format: string): string | null {
+  if (!cacheDir) return null;
+  return path.join(cacheDir, `${cacheKey(fsPath, format)}.${format}`);
+}
+
+/**
+ * Get a cached export buffer if it exists and is fresh.
+ * Returns null on miss or stale cache.
+ */
+export function getCachedExport(fsPath: string, format: string): Buffer | null {
+  const file = cacheFilePath(fsPath, format);
+  if (!file) return null;
+
+  try {
+    const sourceStat = fs.statSync(fsPath);
+    const cacheStat = fs.statSync(file);
+    if (cacheStat.mtimeMs >= sourceStat.mtimeMs) {
+      return fs.readFileSync(file);
+    }
+    // Stale
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/** Store an export buffer in the cache. */
+export function cacheExport(
+  fsPath: string,
+  format: string,
+  buffer: Buffer,
+): void {
+  const file = cacheFilePath(fsPath, format);
+  if (!file) return;
+
+  try {
+    fs.writeFileSync(file, buffer);
+  } catch (err) {
+    console.error('[exportCache] write failed:', (err as Error).message);
+  }
+}
+
+/**
+ * Clear all cached exports for a given file path.
+ * Returns the number of files deleted.
+ */
+export function clearExportCache(fsPath: string): number {
+  if (!cacheDir) return 0;
+
+  let count = 0;
+  for (const format of ['pdf', 'docx']) {
+    const file = cacheFilePath(fsPath, format);
+    if (file) {
+      try {
+        fs.unlinkSync(file);
+        count++;
+      } catch {
+        // Not cached, that's fine
+      }
+    }
+  }
+  return count;
+}
+
+/**
+ * Clear standalone diagram cache entries for a diagram source file.
+ * Reads the file, computes the content-addressed hash, and removes
+ * all format variants (svg, png, pdf, eps) from the diagram cache.
+ */
+export function clearStandaloneDiagramCache(
+  fsPath: string,
+  diagramCacheDir: string | null,
+): number {
+  if (!diagramCacheDir) return 0;
+
+  const ext = path.extname(fsPath).toLowerCase();
+  const diagramType = DIAGRAM_EXT_MAP[ext];
+  if (!diagramType) return 0;
+
+  let source: string;
+  try {
+    source = fs.readFileSync(fsPath, 'utf8');
+  } catch {
+    return 0;
+  }
+
+  const hash = crypto
+    .createHash('sha256')
+    .update(`${diagramType}\0${source}`)
+    .digest('hex');
+
+  let count = 0;
+  for (const fmt of ['svg', 'png', 'pdf', 'eps']) {
+    try {
+      fs.unlinkSync(path.join(diagramCacheDir, `${hash}.${fmt}`));
+      count++;
+    } catch {
+      // Not present
+    }
+  }
+  return count;
+}
+
+// --- Reverse index: fsPath → diagram cache hashes ---
+
+const reverseIndexFile = (): string | null =>
+  cacheDir ? path.join(cacheDir, '_diagram-index.json') : null;
+
+type DiagramIndex = Record<string, string[]>;
+
+function loadDiagramIndex(): DiagramIndex {
+  const file = reverseIndexFile();
+  if (!file) return {};
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8')) as DiagramIndex;
+  } catch {
+    return {};
+  }
+}
+
+function saveDiagramIndex(index: DiagramIndex): void {
+  const file = reverseIndexFile();
+  if (!file) return;
+  try {
+    fs.writeFileSync(file, JSON.stringify(index, null, 2), 'utf8');
+  } catch (err) {
+    console.error('[exportCache] index write failed:', (err as Error).message);
+  }
+}
+
+/**
+ * Register diagram cache hashes associated with a file.
+ * Called during diagram rendering to build the reverse index.
+ */
+export function registerDiagramHashes(fsPath: string, hashes: string[]): void {
+  if (!cacheDir || hashes.length === 0) return;
+  const key = fsPath.replace(/\\/g, '/').toLowerCase();
+  const index = loadDiagramIndex();
+  const existing = new Set(index[key] ?? []);
+  for (const h of hashes) existing.add(h);
+  index[key] = [...existing];
+  saveDiagramIndex(index);
+}
+
+/**
+ * Clear diagram cache entries associated with a file.
+ * Returns the number of diagram cache files deleted.
+ */
+export function clearDiagramCacheForFile(
+  fsPath: string,
+  diagramCacheDir: string | null,
+): number {
+  if (!cacheDir || !diagramCacheDir) return 0;
+
+  const key = fsPath.replace(/\\/g, '/').toLowerCase();
+  const index = loadDiagramIndex();
+  const hashes = index[key] as string[] | undefined;
+  if (!hashes || hashes.length === 0) return 0;
+
+  let count = 0;
+  for (const hash of hashes) {
+    // Diagram cache files can be .svg, .png, or .pdf
+    for (const ext of ['svg', 'png', 'pdf']) {
+      try {
+        fs.unlinkSync(path.join(diagramCacheDir, `${hash}.${ext}`));
+        count++;
+      } catch {
+        // Not present
+      }
+    }
+  }
+
+  // Remove from index
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  const { [key]: _removed, ...rest } = index;
+  saveDiagramIndex(rest);
+
+  return count;
+}

package/src/services/markdown.ts

@@ -0,0 +1,189 @@
+/**
+ * Markdown rendering with TOC generation, Windows path linking, and syntax highlighting
+ */
+
+import fs from 'node:fs';
+
+import { marked } from 'marked';
+
+import { registerDiagram } from './embeddedDiagrams.js';
+
+interface Heading {
+  level: number;
+  text: string;
+  slug: string;
+}
+
+/**
+ * Resolve a filesystem path for linking (skip non-existent and templated paths)
+ */
+function resolvePathForLink(fsPath: string): string | null {
+  // Skip templated paths
+  if (fsPath.includes('{') || fsPath.includes('}')) return null;
+
+  if (!fs.existsSync(fsPath)) return null;
+
+  return fsPath;
+}
+
+const IS_WINDOWS = process.platform === 'win32';
+
+/**
+ * Convert platform-native filesystem paths in markdown text to clickable browse links.
+ * Windows: C:\\foo\\bar → [C:\\foo\\bar](/browse/c/foo/bar)
+ * Linux: /home/user/docs → [/home/user/docs](/browse/home/user/docs)
+ */
+function linkifyFilesystemPaths(markdown: string): string {
+  // Platform-specific path regex
+  const pathRegex = IS_WINDOWS
+    ? /([A-Z]):\\(?:[^\s"'`<>\\]+\\)*[^\s"'`<>\\]+/g
+    : /(?<=\s|^)(\/(?:home|opt|var|tmp|etc|usr|srv|mnt|media)\/[^\s"'`<>]+)/gm;
+
+  const linkifyPath = (fsPath: string): string => {
+    const resolved = resolvePathForLink(fsPath);
+    if (!resolved) return fsPath;
+
+    let urlPath: string;
+    if (IS_WINDOWS) {
+      urlPath =
+        '/' +
+        resolved
+          .replace(/\\/g, '/')
+          .replace(/^([A-Z]):/, (_m: string, d: string) => d.toLowerCase());
+    } else {
+      urlPath = resolved;
+    }
+    return `[${fsPath}](/browse${urlPath})`;
+  };
+
+  // Split by code blocks and inline code
+  const codeBlockRegex = /(```[\s\S]*?```|`[^`\n]+`)/g;
+  const parts = markdown.split(codeBlockRegex);
+
+  return parts
+    .map((part) => {
+      if (part.startsWith('```') || part.startsWith('`')) {
+        return part; // Don't modify code
+      }
+      return part.replace(pathRegex, linkifyPath);
+    })
+    .join('');
+}
+
+/**
+ * Extract YAML frontmatter from markdown if present.
+ * Returns the frontmatter content (without delimiters) and the remaining markdown.
+ */
+function extractFrontmatter(markdown: string): {
+  frontmatter: string | null;
+  body: string;
+} {
+  const match = markdown.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/);
+  if (!match) return { frontmatter: null, body: markdown };
+  return { frontmatter: match[1], body: markdown.slice(match[0].length) };
+}
+
+/**
+ * Parse markdown to HTML with heading extraction
+ */
+export function parseMarkdown(
+  markdown: string,
+  options: { linkWindowsPaths?: boolean; basePath?: string } = {},
+): { html: string; headings: Heading[] } {
+  // Extract frontmatter before processing
+  const { frontmatter, body } = extractFrontmatter(markdown);
+  let processedMarkdown = body;
+
+  // Optionally linkify Windows paths
+  if (options.linkWindowsPaths) {
+    processedMarkdown = linkifyFilesystemPaths(processedMarkdown);
+  }
+
+  const headings: Heading[] = [];
+
+  // Custom renderer to extract headings and add anchors
+  const renderer = new marked.Renderer();
+
+  renderer.heading = function (
+    args: string | { text: string; raw?: string; depth: number },
+  ) {
+    const text = typeof args === 'object' ? args.text : args;
+    const raw = typeof args === 'object' && args.raw ? args.raw : text;
+    const level = typeof args === 'object' ? args.depth : 1;
+
+    const slug = raw
+      .toLowerCase()
+      .replace(/<[^>]+>/g, '')
+      .replace(/[^\w\s-]/g, '')
+      .replace(/\s+/g, '-')
+      .replace(/-+/g, '-')
+      .replace(/^-|-$/g, '');
+
+    headings.push({ level, text: text.replace(/<[^>]+>/g, ''), slug });
+
+    return `<h${String(level)} id="${slug}">${text} <a href="#${slug}" class="anchor">#</a></h${String(level)}>\n`;
+  };
+
+  // Rewrite relative image src to /path/ URLs
+  if (options.basePath) {
+    const base = options.basePath;
+    renderer.image = function (
+      args: string | { href: string; title: string | null; text: string },
+    ) {
+      const href = typeof args === 'object' ? args.href : args;
+      const title = typeof args === 'object' ? args.title : '';
+      const text = typeof args === 'object' ? args.text : '';
+      let src = href;
+      if (src && !src.startsWith('http') && !src.startsWith('data:')) {
+        // Rewrite relative paths to /api/raw/ for file serving
+        if (!src.startsWith('/')) {
+          src = `/api/raw/${base}/${src}`;
+        } else if (src.startsWith('/path/')) {
+          // Legacy /path/ references → /api/raw/
+          src = src.replace('/path/', '/api/raw/');
+        }
+      }
+      const titleAttr = title ? ` title="${title}"` : '';
+      return `<img src="${src}" alt="${text}"${titleAttr} />`;
+    };
+  }
+
+  // Syntax-highlight fenced code blocks; render mermaid/plantuml as diagrams
+  renderer.code = function (
+    args: string | { text: string; lang?: string; escaped?: boolean },
+  ) {
+    const text = typeof args === 'object' ? args.text : args;
+    const lang = (
+      typeof args === 'object' ? args.lang : undefined
+    )?.toLowerCase();
+
+    // Diagram code blocks → register for async rendering (GitHub convention)
+    if (lang === 'mermaid') {
+      return registerDiagram('mermaid', text);
+    }
+    if (lang === 'plantuml' || lang === 'puml') {
+      return registerDiagram('plantuml', text);
+    }
+
+    const escaped = text
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;');
+    const langClass = lang ? ` class="language-${lang}"` : '';
+    return `<pre><code${langClass}>${escaped}</code></pre>\n`;
+  };
+
+  marked.setOptions({ renderer });
+  let html = marked(processedMarkdown) as string;
+
+  // Prepend frontmatter as a rendered YAML code block
+  if (frontmatter) {
+    const escaped = frontmatter
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;');
+    html = `<div class="frontmatter-block"><pre><code class="language-yaml">${escaped}</code></pre></div>\n${html}`;
+  }
+
+  return { html, headings };
+}