@karmaniverous/jeeves-server 3.0.0-0

package/src/services/mermaid.ts

@@ -0,0 +1,113 @@
+/**
+ * Mermaid diagram rendering service.
+ *
+ * Uses \@mermaid-js/mermaid-cli programmatic API with the server's configured Chrome.
+ * Falls back to execSync shell-out if the programmatic API fails to load.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { getConfig } from '../config/index.js';
+
+/**
+ * Render Mermaid source string to SVG via the mermaid-cli programmatic API.
+ *
+ * Uses the server's configured chromePath via puppeteerConfig.executablePath,
+ * avoiding a separate Chromium download.
+ *
+ * Returns null on failure.
+ */
+export async function renderMermaidFromSource(
+  source: string,
+): Promise<string | null> {
+  const config = getConfig();
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'mmd-'));
+  const inFile = path.join(tmpDir, 'diagram.mmd');
+  const outFile = path.join(tmpDir, 'diagram.svg');
+
+  try {
+    fs.writeFileSync(inFile, source, 'utf8');
+
+    // Dynamic import to avoid loading puppeteer at module parse time
+    const { run } = await import('@mermaid-js/mermaid-cli');
+
+    await run(inFile, outFile as `${string}.svg`, {
+      quiet: true,
+      outputFormat: 'svg',
+      puppeteerConfig: {
+        executablePath: config.chromePath,
+        headless: 'shell',
+        args: ['--no-sandbox', '--disable-setuid-sandbox'],
+      },
+      parseMMDOptions: {
+        backgroundColor: 'white',
+        viewport: { width: 1600, height: 1200, deviceScaleFactor: 2 },
+      },
+    });
+
+    if (!fs.existsSync(outFile)) return null;
+    return fs.readFileSync(outFile, 'utf8');
+  } catch (err) {
+    console.error('[mermaid] render failed:', (err as Error).message);
+    return null;
+  } finally {
+    try {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  }
+}
+
+/**
+ * Render a .mmd file to SVG string.
+ * Returns null on failure.
+ */
+export async function renderMermaidSvg(
+  inputPath: string,
+): Promise<string | null> {
+  const source = fs.readFileSync(inputPath, 'utf8');
+  return renderMermaidFromSource(source);
+}
+
+/**
+ * Render a .mmd file to the specified format and return the output file path.
+ * The caller is responsible for reading and cleaning up the output file.
+ * Returns null on failure.
+ */
+export async function renderMermaidToFile(
+  inputPath: string,
+  format: string,
+): Promise<string | null> {
+  const config = getConfig();
+  const resolved = path.resolve(inputPath);
+  const outFile = path.join(
+    path.dirname(resolved),
+    `${path.basename(resolved, '.mmd')}.${format}`,
+  );
+
+  try {
+    const { run } = await import('@mermaid-js/mermaid-cli');
+
+    await run(resolved, outFile as `${string}.svg`, {
+      quiet: true,
+      outputFormat: format as 'svg' | 'png' | 'pdf',
+      puppeteerConfig: {
+        executablePath: config.chromePath,
+        headless: 'shell',
+        args: ['--no-sandbox', '--disable-setuid-sandbox'],
+      },
+      parseMMDOptions: {
+        backgroundColor: 'white',
+        viewport: { width: 1600, height: 1200, deviceScaleFactor: 2 },
+      },
+    });
+
+    if (fs.existsSync(outFile)) return outFile;
+  } catch (err) {
+    console.error('[mermaid] render to file failed:', (err as Error).message);
+  }
+  return null;
+}

package/src/services/plantuml.ts

@@ -0,0 +1,172 @@
+/**
+ * PlantUML rendering with fallback pipeline:
+ * 1. Local Java jar (if configured) — supports !include directives
+ * 2. Configured PlantUML servers (in order)
+ * 3. Public community server (always last resort)
+ */
+
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import plantumlEncoder from 'plantuml-encoder';
+
+import { getConfig } from '../config/index.js';
+
+/**
+ * Try rendering via local PlantUML jar.
+ * Output goes to a temp directory to avoid writing in the source tree.
+ * Returns the output buffer, or null on failure.
+ */
+function renderViaJar(filePath: string, format: string): Buffer | null {
+  const { plantuml } = getConfig();
+  if (!plantuml.jarPath) return null;
+
+  const dir = path.dirname(filePath);
+  const ext = path.extname(filePath);
+  const base = path.basename(filePath, ext);
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'puml-'));
+  const outFile = path.join(tmpDir, `${base}.${format}`);
+
+  try {
+    const java = plantuml.javaPath ?? 'java';
+    // UNSECURE profile allows remote !include directives (e.g. AWS PuML from GitHub)
+    execSync(
+      `"${java}" -DPLANTUML_SECURITY_PROFILE=UNSECURE -jar "${plantuml.jarPath}" -t${format} -o "${tmpDir}" "${filePath}"`,
+      { timeout: 60_000, stdio: 'pipe', cwd: dir },
+    );
+    if (!fs.existsSync(outFile)) return null;
+    const buffer = fs.readFileSync(outFile);
+    return buffer;
+  } catch (err) {
+    // PlantUML may produce output even on non-zero exit (e.g. partial render with warnings).
+    // Check for output before giving up.
+    if (fs.existsSync(outFile)) {
+      console.warn('[PlantUML jar] render completed with warnings');
+      if (err && typeof err === 'object' && 'stderr' in err) {
+        console.warn(
+          '[PlantUML jar] stderr:',
+          String((err as { stderr: unknown }).stderr),
+        );
+      }
+      return fs.readFileSync(outFile);
+    }
+    console.error('[PlantUML jar] render failed:', (err as Error).message);
+    if (err && typeof err === 'object' && 'stderr' in err) {
+      console.error(
+        '[PlantUML jar] stderr:',
+        String((err as { stderr: unknown }).stderr),
+      );
+    }
+    return null;
+  } finally {
+    // Clean up temp dir
+    try {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  }
+}
+
+/**
+ * Try rendering via a PlantUML server endpoint.
+ * Returns the output buffer, or null on failure.
+ */
+async function renderViaServer(
+  source: string,
+  format: string,
+  serverUrl: string,
+): Promise<Buffer | null> {
+  try {
+    const encoded = plantumlEncoder.encode(source);
+    const url = `${serverUrl.replace(/\/+$/, '')}/${format}/${encoded}`;
+    const resp = await fetch(url, { signal: AbortSignal.timeout(15_000) });
+    if (!resp.ok) return null;
+    return Buffer.from(await resp.arrayBuffer());
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Render a PlantUML file with the full fallback pipeline.
+ * Returns \{ buffer, method \} or null if all methods fail.
+ */
+export async function renderPlantUml(
+  filePath: string,
+  format: string = 'svg',
+): Promise<{ buffer: Buffer; method: string } | null> {
+  // 1. Try local jar (supports includes)
+  const jarResult = renderViaJar(filePath, format);
+  if (jarResult) return { buffer: jarResult, method: 'jar' };
+
+  // 2. Try configured servers in order
+  const { plantuml } = getConfig();
+  const source = fs.readFileSync(filePath, 'utf8');
+
+  for (const server of plantuml.servers) {
+    const serverResult = await renderViaServer(source, format, server);
+    if (serverResult) return { buffer: serverResult, method: server };
+  }
+
+  return null;
+}
+
+/**
+ * Render PlantUML source string to SVG.
+ * Writes to a temp file, renders via the full pipeline, cleans up.
+ */
+export async function renderPlantUmlFromSource(
+  source: string,
+): Promise<string | null> {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'puml-src-'));
+  const inFile = path.join(tmpDir, 'diagram.puml');
+
+  try {
+    fs.writeFileSync(inFile, source, 'utf8');
+    return await renderPlantUmlSvg(inFile);
+  } finally {
+    try {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  }
+}
+
+/**
+ * Render PlantUML to SVG string (convenience for file API).
+ */
+export async function renderPlantUmlSvg(
+  filePath: string,
+): Promise<string | null> {
+  const result = await renderPlantUml(filePath, 'svg');
+  if (!result) return null;
+  return result.buffer.toString('utf8');
+}
+
+/**
+ * Render PlantUML to buffer for export.
+ */
+export async function renderPlantUmlToBuffer(
+  filePath: string,
+  format: string,
+): Promise<Buffer | null> {
+  const result = await renderPlantUml(filePath, format);
+  return result?.buffer ?? null;
+}
+
+/**
+ * Get all export formats supported by PlantUML.
+ */
+export function getPlantUmlFormats(): string[] {
+  // PlantUML jar supports all these; server supports svg/png/txt
+  const { plantuml } = getConfig();
+  if (plantuml.jarPath) {
+    return ['svg', 'png', 'pdf', 'eps'];
+  }
+  // Server-only: limited formats
+  return ['svg', 'png'];
+}

package/src/services/puppeteer.ts

@@ -0,0 +1,188 @@
+/**
+ * Puppeteer browser management and page preparation utilities.
+ * Shared by PDF and DOCX export paths.
+ */
+
+import type { Browser, Page } from 'puppeteer-core';
+import puppeteer from 'puppeteer-core';
+
+import { getConfig } from '../config/index.js';
+
+/**
+ * Launch Puppeteer browser with configured Chrome path.
+ */
+export async function launchBrowser(): Promise<Browser> {
+  const { chromePath } = getConfig();
+  return await puppeteer.launch({
+    executablePath: chromePath,
+    headless: true,
+    args: ['--no-sandbox', '--disable-setuid-sandbox'],
+  });
+}
+
+/** Print CSS — hides chrome, normalizes layout for clean export. */
+const PRINT_CSS = `
+  /* Hide chrome — works for both legacy server-rendered and SPA */
+  .header, .header-actions, .panzoom-container, .panzoom-hint,
+  header, nav, .toc-sidebar, [class*="sticky"], [class*="fixed"] { display: none !important; }
+  .toc { position: static !important; height: auto !important; page-break-after: always; }
+  .toc-spacer { display: none !important; }
+  .layout { display: block !important; }
+  body { background: #fff !important; font-size: 10pt !important; line-height: 1.5 !important; color: #000 !important; }
+  /* SPA layout: remove scroll containers so body grows to full content height */
+  html, body, #root { height: auto !important; overflow: visible !important; }
+  main, [class*="overflow-y"] { overflow: visible !important; height: auto !important; }
+  /* SPA article.prose */
+  article.prose { max-width: none !important; border: none !important; padding: 0 !important; }
+  .content, article.prose { font-size: 10pt !important; }
+  /* Hide tab bar and other SPA controls */
+  [role="tablist"], button { display: none !important; }
+  main { padding-top: 0 !important; }
+  /* Inline SVG Panzoom & Embedded Diagrams: strip container chrome, show SVGs cleanly */
+  .inline-svg-panzoom, .embedded-diagram-panzoom, .embedded-diagram-rendered { 
+    position: static !important; 
+    background: white !important; 
+    border: none !important; 
+    overflow: visible !important;
+    cursor: default !important;
+    padding: 0 !important;
+    margin: 1em 0 !important;
+  }
+  .inline-svg-panzoom button, .embedded-diagram-panzoom button { display: none !important; }
+  .inline-svg-panzoom .text-xs, .embedded-diagram-panzoom .text-xs { display: none !important; }
+  .inline-svg-panzoom svg, .embedded-diagram-panzoom svg, .embedded-diagram-rendered svg {
+    max-width: 190mm !important;
+    max-height: 250mm !important;
+    width: auto !important;
+    height: auto !important;
+    display: block !important;
+    page-break-inside: avoid !important;
+  }
+  h1 { font-size: 18pt !important; }
+  h2 { font-size: 14pt !important; }
+  h3 { font-size: 12pt !important; }
+  h4, h5, h6 { font-size: 10pt !important; }
+  code { font-size: 9pt !important; }
+  pre { font-size: 8pt !important; background: #f5f5f5 !important; border: 1px solid #e0e0e0 !important; border-radius: 4px !important; padding: 8px !important; overflow-wrap: break-word !important; white-space: pre-wrap !important; }
+  pre code { font-size: 8pt !important; }
+  table { font-size: 10pt !important; }
+  a.anchor { display: none !important; }
+  img, svg, .svg-container, .zoomable-svg { 
+    max-width: 190mm !important; 
+    max-height: 250mm !important; 
+    width: auto !important; 
+    height: auto !important;
+    display: block !important;
+    page-break-inside: avoid !important; 
+  }
+  img { object-fit: contain !important; }
+`;
+
+/**
+ * Add print styles to a Puppeteer page.
+ */
+export async function addPrintStyles(page: Page): Promise<void> {
+  await page.addStyleTag({ content: PRINT_CSS });
+}
+
+/**
+ * Wait for SPA content to fully render, including async SVG fetches.
+ */
+export async function waitForSpaContent(page: Page): Promise<void> {
+  await page
+    .waitForSelector('article.prose', { timeout: 15_000 })
+    .catch(() => {});
+  await page
+    .waitForFunction(
+      () => {
+        const containers = document.querySelectorAll('.inline-svg-panzoom');
+        if (containers.length === 0) return true;
+        return Array.from(containers).every(
+          (c) => !c.textContent.includes('Loading SVG'),
+        );
+      },
+      { timeout: 15_000 },
+    )
+    .catch(() => {});
+  // Wait for CM6 code blocks to mount
+  await page
+    .waitForFunction(
+      () => {
+        const article = document.querySelector('article.prose');
+        if (!article) return true;
+        // If there are no code blocks, or CM6 has signaled ready
+        const codeBlocks = article.querySelectorAll('.cm6-embedded-code');
+        if (codeBlocks.length === 0) return true;
+        return article.getAttribute('data-cm6-ready') === 'true';
+      },
+      { timeout: 15_000 },
+    )
+    .catch(() => {});
+  await new Promise((r) => setTimeout(r, 1000));
+}
+
+/** SVG container selectors used across export paths. */
+export const SVG_CONTAINER_SELECTORS =
+  '.svg-container, .zoomable-svg, .inline-svg-panzoom, .embedded-diagram-panzoom, .embedded-diagram-rendered';
+
+/**
+ * Capture each SVG in a page as a high-quality PNG screenshot.
+ * Returns array of \{ index, dataUrl, width, height \}.
+ */
+export async function captureSvgsAsPng(
+  browser: Browser,
+  page: Page,
+): Promise<
+  { index: number; dataUrl: string; width: number; height: number }[]
+> {
+  const svgContents = await page.evaluate((selectors: string) => {
+    const containers = document.querySelectorAll(selectors);
+    return Array.from(containers).map((container, i) => {
+      const svg = container.querySelector('svg');
+      return { index: i, svgHtml: svg ? svg.outerHTML : null };
+    });
+  }, SVG_CONTAINER_SELECTORS);
+
+  const results: {
+    index: number;
+    dataUrl: string;
+    width: number;
+    height: number;
+  }[] = [];
+
+  for (const { index, svgHtml } of svgContents) {
+    if (!svgHtml) continue;
+
+    const svgPage = await browser.newPage();
+    await svgPage.setViewport({
+      width: 1200,
+      height: 2000,
+      deviceScaleFactor: 2,
+    });
+    await svgPage.setContent(
+      `<!DOCTYPE html>
+<html><head><style>
+  body { margin: 0; padding: 0; background: #fff; }
+  svg { width: 1152px; height: auto; display: block; }
+</style></head><body>${svgHtml}</body></html>`,
+      { waitUntil: 'networkidle0' },
+    );
+
+    const svgHandle = await svgPage.$('svg');
+    if (svgHandle) {
+      const screenshot = await svgHandle.screenshot({ type: 'png' });
+      const box = await svgHandle.boundingBox();
+      if (box && box.width > 0 && box.height > 0) {
+        results.push({
+          index,
+          dataUrl: `data:image/png;base64,${Buffer.from(screenshot).toString('base64')}`,
+          width: Math.ceil(box.width),
+          height: Math.ceil(box.height),
+        });
+      }
+    }
+    await svgPage.close();
+  }
+
+  return results;
+}

package/src/types/fastify.d.ts

@@ -0,0 +1,13 @@
+import type { AccessMode, NormalizedScopes } from '../config/types.js';
+
+declare module 'fastify' {
+  interface FastifyRequest {
+    accessMode?: AccessMode;
+    authSeed?: string;
+    insiderScopes?: NormalizedScopes | null;
+    insiderEmail?: string;
+    keyAge?: string | null;
+    deepShareParams?: { d: string; dirs: string; s: string };
+    authMatchedPath?: string | null;
+  }
+}

package/src/types/jsonmap.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Type declarations for karmaniverous/jsonmap package
+ */
+
+declare module '@karmaniverous/jsonmap' {
+  export class JsonMap {
+    constructor(map?: object, lib?: Record<string, unknown>, ignore?: string);
+    transform(input: unknown): Promise<unknown>;
+  }
+}

package/src/types/plantuml-encoder.d.ts

@@ -0,0 +1,4 @@
+declare module 'plantuml-encoder' {
+  export function encode(source: string): string;
+  export function decode(encoded: string): string;
+}

package/src/util/breadcrumbs.ts

@@ -0,0 +1,33 @@
+/**
+ * Breadcrumb filtering utilities.
+ */
+
+export interface Breadcrumb {
+  label: string;
+  path: string;
+}
+
+/**
+ * Filter breadcrumbs for outsiders:
+ * - File shares: no breadcrumbs (the page stands alone)
+ * - Directory shares: trim to the share root (matchedPath)
+ */
+export function filterBreadcrumbsForOutsider(
+  breadcrumbs: Breadcrumb[],
+  isInsider: boolean,
+  matchedPath: string | null,
+  isDirectoryView: boolean,
+): Breadcrumb[] {
+  if (isInsider) return breadcrumbs;
+  if (!isDirectoryView)
+    return breadcrumbs.length > 0 ? [breadcrumbs[breadcrumbs.length - 1]] : [];
+  // For directory views, trim breadcrumbs to the matched (shared) path root
+  if (matchedPath) {
+    const normalizedMatch = matchedPath.replace(/^\/+|\/+$/g, '').toLowerCase();
+    const matchIdx = breadcrumbs.findIndex(
+      (b) => b.path.replace(/^\/+|\/+$/g, '').toLowerCase() === normalizedMatch,
+    );
+    if (matchIdx >= 0) return breadcrumbs.slice(matchIdx);
+  }
+  return breadcrumbs;
+}

package/src/util/crypto.test.ts

@@ -0,0 +1,132 @@
+/**
+ * Tests for cryptographic utilities
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import {
+  computeInsiderKey,
+  computeOutsiderKeyWithExpiry,
+  computePathKey,
+  timingSafeEqual,
+} from './crypto.js';
+
+describe('crypto utilities', () => {
+  const testApiKey = 'test-api-key-12345';
+
+  describe('computePathKey', () => {
+    it('should compute a 32-character hex key', () => {
+      const key = computePathKey(testApiKey, '/foo/bar');
+      expect(key).toMatch(/^[a-f0-9]{32}$/);
+    });
+
+    it('should normalize paths (case-insensitive)', () => {
+      const key1 = computePathKey(testApiKey, '/Foo/Bar');
+      const key2 = computePathKey(testApiKey, '/foo/bar');
+      expect(key1).toBe(key2);
+    });
+
+    it('should normalize paths (trim slashes)', () => {
+      const key1 = computePathKey(testApiKey, '/foo/bar/');
+      const key2 = computePathKey(testApiKey, 'foo/bar');
+      expect(key1).toBe(key2);
+    });
+
+    it('should produce different keys for different paths', () => {
+      const key1 = computePathKey(testApiKey, '/foo/bar');
+      const key2 = computePathKey(testApiKey, '/baz/qux');
+      expect(key1).not.toBe(key2);
+    });
+
+    it('should produce different keys for different API keys', () => {
+      const key1 = computePathKey('api-key-1', '/foo/bar');
+      const key2 = computePathKey('api-key-2', '/foo/bar');
+      expect(key1).not.toBe(key2);
+    });
+  });
+
+  describe('computeInsiderKey', () => {
+    it('should compute a 32-character hex key', () => {
+      const key = computeInsiderKey(testApiKey);
+      expect(key).toMatch(/^[a-f0-9]{32}$/);
+    });
+
+    it('should be deterministic (same API key = same insider key)', () => {
+      const key1 = computeInsiderKey(testApiKey);
+      const key2 = computeInsiderKey(testApiKey);
+      expect(key1).toBe(key2);
+    });
+
+    it('should produce different keys for different API keys', () => {
+      const key1 = computeInsiderKey('api-key-1');
+      const key2 = computeInsiderKey('api-key-2');
+      expect(key1).not.toBe(key2);
+    });
+  });
+
+  describe('computeOutsiderKeyWithExpiry', () => {
+    it('should compute a 32-character hex key', () => {
+      const expiry = Date.now() + 3600000;
+      const key = computeOutsiderKeyWithExpiry(testApiKey, '/foo/bar', expiry);
+      expect(key).toMatch(/^[a-f0-9]{32}$/);
+    });
+
+    it('should normalize paths (case-insensitive)', () => {
+      const expiry = Date.now() + 3600000;
+      const key1 = computeOutsiderKeyWithExpiry(testApiKey, '/Foo/Bar', expiry);
+      const key2 = computeOutsiderKeyWithExpiry(testApiKey, '/foo/bar', expiry);
+      expect(key1).toBe(key2);
+    });
+
+    it('should produce different keys for different expiries', () => {
+      const expiry1 = Date.now() + 3600000;
+      const expiry2 = Date.now() + 7200000;
+      const key1 = computeOutsiderKeyWithExpiry(
+        testApiKey,
+        '/foo/bar',
+        expiry1,
+      );
+      const key2 = computeOutsiderKeyWithExpiry(
+        testApiKey,
+        '/foo/bar',
+        expiry2,
+      );
+      expect(key1).not.toBe(key2);
+    });
+
+    it('should accept string expiry', () => {
+      const expiry = String(Date.now() + 3600000);
+      const key = computeOutsiderKeyWithExpiry(testApiKey, '/foo/bar', expiry);
+      expect(key).toMatch(/^[a-f0-9]{32}$/);
+    });
+  });
+
+  describe('timingSafeEqual', () => {
+    it('should return true for equal strings', () => {
+      const a = 'abc123';
+      const b = 'abc123';
+      expect(timingSafeEqual(a, b)).toBe(true);
+    });
+
+    it('should return false for different strings', () => {
+      const a = 'abc123';
+      const b = 'def456';
+      expect(timingSafeEqual(a, b)).toBe(false);
+    });
+
+    it('should return false for strings of different lengths', () => {
+      const a = 'abc';
+      const b = 'abcdef';
+      expect(timingSafeEqual(a, b)).toBe(false);
+    });
+
+    it('should return false for empty strings vs non-empty', () => {
+      expect(timingSafeEqual('', 'abc')).toBe(false);
+      expect(timingSafeEqual('abc', '')).toBe(false);
+    });
+
+    it('should return true for empty strings', () => {
+      expect(timingSafeEqual('', '')).toBe(true);
+    });
+  });
+});