@karmaniverous/jeeves-server 3.0.0-0

package/src/server.ts

@@ -0,0 +1,104 @@
+/**
+ * Jeeves Server - Main entry point
+ * Fastify server for webhooks, file serving, and markdown rendering
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import cookie from '@fastify/cookie';
+import fastifyStatic from '@fastify/static';
+import Fastify from 'fastify';
+
+import { getConfig, initConfig, isConfigInitialized } from './config/index.js';
+import { apiRoute } from './routes/api/index.js';
+import { authRoute } from './routes/auth.js';
+import { eventRoute } from './routes/event.js';
+import { healthRoute } from './routes/health.js';
+import { keysRoute } from './routes/keys.js';
+import { pathRoute } from './routes/path/index.js';
+import { staticRoutes } from './routes/static.js';
+import { initDiagramCache } from './services/diagramCache.js';
+import { startQueueProcessor } from './services/eventQueue.js';
+import { initExportCache } from './services/exportCache.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+async function start() {
+  try {
+    const config = isConfigInitialized() ? getConfig() : await initConfig();
+
+    const fastify = Fastify({
+      logger: true,
+    });
+
+    // Register plugins
+    await fastify.register(cookie);
+
+    // X-Robots-Tag on all responses — invisible to search engines
+    fastify.addHook('onSend', async (_request, reply) => {
+      void reply.header('X-Robots-Tag', 'noindex, nofollow');
+    });
+
+    // Register routes
+    await fastify.register(staticRoutes);
+    await fastify.register(healthRoute);
+    await fastify.register(authRoute);
+    await fastify.register(keysRoute);
+    await fastify.register(eventRoute);
+    await fastify.register(apiRoute);
+    await fastify.register(pathRoute);
+
+    // Serve React SPA (if built)
+    const clientDir = path.join(__dirname, '..', 'client');
+    if (fs.existsSync(clientDir)) {
+      await fastify.register(fastifyStatic, {
+        root: clientDir,
+        prefix: '/app/',
+      });
+
+      // SPA fallback for React routes
+      fastify.get('/', async (_request, reply) => {
+        return reply.sendFile('index.html', clientDir);
+      });
+      fastify.get('/browse', async (_request, reply) => {
+        return reply.sendFile('index.html', clientDir);
+      });
+      fastify.get('/browse/*', async (_request, reply) => {
+        return reply.sendFile('index.html', clientDir);
+      });
+      fastify.get('/runner', async (_request, reply) => {
+        return reply.sendFile('index.html', clientDir);
+      });
+      fastify.get('/runner/*', async (_request, reply) => {
+        return reply.sendFile('index.html', clientDir);
+      });
+    }
+
+    // Initialize caches
+    initDiagramCache(config.diagramCachePath);
+    initExportCache();
+
+    // Start queue processor
+    startQueueProcessor();
+
+    await fastify.listen({ port: config.port, host: '0.0.0.0' });
+    console.log(`Jeeves server listening on port ${String(config.port)}`);
+    console.log(`Endpoints:`);
+    console.log(`  GET  /browse/* - File browser SPA`);
+    console.log(`  GET  /api/raw/*    - Raw file serving`);
+    console.log(`  GET  /api/export/* - PDF/DOCX/ZIP export`);
+    console.log(`  POST /event    - Event Gateway (key auth)`);
+    console.log(`  GET  /key      - Compute path key (X-API-Key auth)`);
+    console.log(`  GET  /health   - Health check (no auth)`);
+  } catch (err) {
+    console.error('Fatal startup error:', err);
+    process.exit(1);
+  }
+}
+
+start().catch((err: unknown) => {
+  console.error('Unhandled startup error:', err);
+  process.exit(1);
+});

package/src/services/deepShareLinks.ts

@@ -0,0 +1,203 @@
+/**
+ * Deep share link rewriting for outsider access with depth traversal.
+ *
+ * Rewrites outgoing links in rendered HTML with computed sub-keys,
+ * enabling outsiders to follow links up to N levels deep.
+ */
+
+import * as cheerio from 'cheerio';
+import LZString from 'lz-string';
+
+import { computeDeepShareKey, type DeepShareParams } from '../util/crypto.js';
+
+/**
+ * Parse a compressed stack string into an array of paths.
+ */
+export function decodeStack(compressed: string): string[] {
+  if (!compressed) return [];
+  const json = LZString.decompressFromEncodedURIComponent(compressed);
+  if (!json) return [];
+  try {
+    const parsed: unknown = JSON.parse(json);
+    return Array.isArray(parsed) ? (parsed as string[]) : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Encode a path stack array into a compressed string.
+ */
+export function encodeStack(stack: string[]): string {
+  return LZString.compressToEncodedURIComponent(JSON.stringify(stack));
+}
+
+/**
+ * Compute the remaining depth for a given stack.
+ */
+export function remainingDepth(maxDepth: number, stack: string[]): number {
+  return maxDepth - (stack.length - 1);
+}
+
+/**
+ * Compute a sub-link URL for an outgoing link target.
+ * Returns null if the link should be stripped (depth exhausted or type not allowed).
+ */
+export function computeSubLink(
+  seed: string,
+  targetUrlPath: string,
+  currentStack: string[],
+  maxDepth: number,
+  dirs: boolean,
+  exp: string | undefined,
+  isDirectory: boolean,
+): string | null {
+  // Check if directories are allowed
+  if (isDirectory && !dirs) return null;
+
+  // Compute new stack
+  const existingIndex = currentStack.indexOf(targetUrlPath);
+  let newStack: string[];
+  if (existingIndex >= 0) {
+    // Revisiting — truncate stack to that point
+    newStack = currentStack.slice(0, existingIndex + 1);
+  } else {
+    // New page — append
+    newStack = [...currentStack, targetUrlPath];
+  }
+
+  // Check remaining depth
+  const remaining = remainingDepth(maxDepth, newStack);
+  if (remaining < 0) return null;
+
+  const compressedStack = encodeStack(newStack);
+
+  // Compute key for the target
+  const params: DeepShareParams = {
+    depth: maxDepth,
+    dirs,
+    stack: compressedStack,
+    exp,
+  };
+  const key = computeDeepShareKey(seed, targetUrlPath, params);
+
+  // Build URL
+  let url = `/browse${targetUrlPath}?key=${key}&d=${String(maxDepth)}&dirs=${dirs ? '1' : '0'}&s=${compressedStack}`;
+  if (exp) url += `&exp=${exp}`;
+  return url;
+}
+
+/**
+ * Rewrite outgoing links in rendered HTML for deep share access.
+ *
+ * For outsiders with depth \> 0:
+ * - Internal links get rewritten with sub-keys
+ * - Links beyond depth get stripped (text preserved, link removed)
+ * - External links (http/https) are left unchanged
+ * - Anchor links (#) are left unchanged
+ */
+export function rewriteLinksForDeepShare(
+  html: string,
+  seed: string,
+  currentPath: string,
+  maxDepth: number,
+  dirs: boolean,
+  stackCompressed: string,
+  exp: string | undefined,
+): string {
+  const currentStack = decodeStack(stackCompressed);
+  // Ensure current path is in the stack
+  if (
+    currentStack.length === 0 ||
+    currentStack[currentStack.length - 1] !== currentPath
+  ) {
+    currentStack.push(currentPath);
+  }
+
+  const remaining = remainingDepth(maxDepth, currentStack);
+
+  const $ = cheerio.load(html, null, false);
+
+  // Rewrite <a> tags
+  $('a').each((_i, el) => {
+    const $el = $(el);
+    const href = $el.attr('href');
+    if (!href) return;
+
+    // Skip external links, anchors, and data URLs
+    if (
+      href.startsWith('http://') ||
+      href.startsWith('https://') ||
+      href.startsWith('#') ||
+      href.startsWith('//') ||
+      href.startsWith('data:') ||
+      href.startsWith('mailto:')
+    ) {
+      return;
+    }
+
+    // If no remaining depth, strip the link (keep text)
+    if (remaining <= 0) {
+      $el.replaceWith($el.html() ?? '');
+      return;
+    }
+
+    // Raw file links — leave as-is (these are for images/downloads)
+    if (href.startsWith('/api/raw/')) return;
+
+    // Determine target path
+    let targetPath: string;
+    if (href.startsWith('/browse/')) {
+      targetPath = '/' + href.replace('/browse/', '').split('?')[0];
+    } else if (href.startsWith('/')) {
+      targetPath = href.split('?')[0];
+    } else {
+      // Relative link — resolve against current path directory
+      const dir = currentPath.substring(0, currentPath.lastIndexOf('/'));
+      targetPath = dir
+        ? `${dir}/${href.split('?')[0]}`
+        : `/${href.split('?')[0]}`;
+    }
+
+    // Normalize
+    targetPath = targetPath.replace(/\/+/g, '/');
+
+    const isDirectory = targetPath.endsWith('/');
+    const subLink = computeSubLink(
+      seed,
+      targetPath,
+      currentStack,
+      maxDepth,
+      dirs,
+      exp,
+      isDirectory,
+    );
+
+    if (subLink === null) {
+      // Strip link, keep text
+      $el.replaceWith($el.html() ?? '');
+    } else {
+      $el.attr('href', subLink);
+    }
+  });
+
+  // Rewrite <img> src for images that use /api/raw/ — add key auth
+  $('img').each((_i, el) => {
+    const $el = $(el);
+    const src = $el.attr('src');
+    if (!src || !src.startsWith('/api/raw/')) return;
+
+    const params: DeepShareParams = {
+      depth: maxDepth,
+      dirs,
+      stack: stackCompressed,
+      exp,
+    };
+    const rawPath = '/' + src.replace('/api/raw/', '').split('?')[0];
+    const key = computeDeepShareKey(seed, rawPath, params);
+    const authSrc = `${src}${src.includes('?') ? '&' : '?'}key=${key}&d=${String(maxDepth)}&dirs=${dirs ? '1' : '0'}&s=${stackCompressed}${exp ? `&exp=${exp}` : ''}`;
+    $el.attr('src', authSrc);
+  });
+
+  return $.html();
+}

package/src/services/diagramCache.ts

@@ -0,0 +1,128 @@
+/**
+ * Content-addressed diagram render cache.
+ *
+ * Cache key = sha256(type + '\\0' + source). Cached artifacts are SVG strings
+ * stored as files in a single directory. No timestamp comparison needed:
+ * if the source changes, the hash changes → automatic cache miss.
+ */
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+let cacheDir: string | null = null;
+
+/**
+ * Initialize the cache directory. Call once at startup.
+ * Defaults to `.diagram-cache` in the current working directory.
+ */
+export function initDiagramCache(dir?: string): void {
+  cacheDir = dir ?? path.resolve('.diagram-cache');
+  fs.mkdirSync(cacheDir, { recursive: true });
+}
+
+/**
+ * Get the cache directory path (for diagnostics / health endpoint).
+ */
+export function getDiagramCacheDir(): string | null {
+  return cacheDir;
+}
+
+/**
+ * Compute the cache key for a diagram.
+ */
+function cacheKey(type: string, source: string): string {
+  return crypto.createHash('sha256').update(`${type}\0${source}`).digest('hex');
+}
+
+/**
+ * Look up a cached diagram. Returns the content as a string or null on miss.
+ * @param format - Output format extension (e.g. 'svg', 'png', 'pdf'). Defaults to 'svg'.
+ */
+export function getCachedDiagram(
+  type: string,
+  source: string,
+  format: string = 'svg',
+): string | null {
+  if (!cacheDir) return null;
+  const file = path.join(cacheDir, `${cacheKey(type, source)}.${format}`);
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Look up a cached diagram as a Buffer (for binary formats like PNG/PDF).
+ * @param format - Output format extension (e.g. 'png', 'pdf').
+ */
+export function getCachedDiagramBuffer(
+  type: string,
+  source: string,
+  format: string,
+): Buffer | null {
+  if (!cacheDir) return null;
+  const file = path.join(cacheDir, `${cacheKey(type, source)}.${format}`);
+  try {
+    return fs.readFileSync(file);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Store a rendered diagram in the cache (string content).
+ * @param format - Output format extension. Defaults to 'svg'.
+ */
+export function cacheDiagram(
+  type: string,
+  source: string,
+  content: string,
+  format: string = 'svg',
+): void {
+  if (!cacheDir) return;
+  const file = path.join(cacheDir, `${cacheKey(type, source)}.${format}`);
+  try {
+    fs.writeFileSync(file, content, 'utf8');
+  } catch (err) {
+    console.error('[diagramCache] write failed:', (err as Error).message);
+  }
+}
+
+/**
+ * Store a rendered diagram in the cache (binary content).
+ * @param format - Output format extension (e.g. 'png', 'pdf').
+ */
+export function cacheDiagramBuffer(
+  type: string,
+  source: string,
+  buffer: Buffer,
+  format: string,
+): void {
+  if (!cacheDir) return;
+  const file = path.join(cacheDir, `${cacheKey(type, source)}.${format}`);
+  try {
+    fs.writeFileSync(file, buffer);
+  } catch (err) {
+    console.error('[diagramCache] write failed:', (err as Error).message);
+  }
+}
+
+/**
+ * Get a cached diagram or render it and cache the result.
+ * Eliminates the repeated getCachedDiagram → render → cacheDiagram pattern.
+ */
+export async function getOrRenderDiagram(
+  type: string,
+  source: string,
+  renderFn: () => string | null | Promise<string | null>,
+  format: string = 'svg',
+): Promise<string | null> {
+  const cached = getCachedDiagram(type, source, format);
+  if (cached) return cached;
+
+  const result = await renderFn();
+  if (result) cacheDiagram(type, source, result, format);
+  return result;
+}

package/src/services/embeddedDiagrams.ts

@@ -0,0 +1,168 @@
+/**
+ * Embedded diagram support for Mermaid and PlantUML code blocks in markdown.
+ *
+ * Strategy: parseMarkdown() calls registerDiagram() which stores the source
+ * and returns a placeholder div. The client lazily fetches rendered SVGs
+ * via GET /api/diagram/:type/:hash.svg, which renders on-demand and caches.
+ *
+ * For PDF/DOCX export (server-side rendering), renderEmbeddedDiagrams()
+ * replaces placeholders with inline SVGs synchronously.
+ */
+
+import crypto from 'node:crypto';
+
+import { getOrRenderDiagram } from './diagramCache.js';
+import { renderMermaidFromSource } from './mermaid.js';
+import { renderPlantUmlFromSource } from './plantuml.js';
+
+/** Placeholder format used by the markdown renderer */
+const PLACEHOLDER_RE = /<!--DIAGRAM:(mermaid|plantuml):([a-f0-9]{64})-->/g;
+
+/**
+ * In-flight diagram sources, keyed by content hash.
+ * Entries are cleaned up after a TTL to prevent unbounded growth.
+ */
+const diagramSources = new Map<
+  string,
+  { source: string; contextDir?: string; createdAt: number }
+>();
+
+/** TTL for source map entries (10 minutes) */
+const SOURCE_TTL_MS = 10 * 60 * 1000;
+
+/** Periodic cleanup interval */
+let cleanupInterval: ReturnType<typeof setInterval> | null = null;
+
+function startCleanup(): void {
+  if (cleanupInterval) return;
+  cleanupInterval = setInterval(() => {
+    const now = Date.now();
+    for (const [hash, entry] of diagramSources) {
+      if (now - entry.createdAt > SOURCE_TTL_MS) {
+        diagramSources.delete(hash);
+      }
+    }
+  }, 60_000);
+  // Don't keep process alive just for cleanup
+  cleanupInterval.unref();
+}
+
+/**
+ * Compute content hash matching the cache key format.
+ */
+export function diagramHash(type: string, source: string): string {
+  return crypto.createHash('sha256').update(`${type}\0${source}`).digest('hex');
+}
+
+/** Module-level context directory for the current markdown parse. */
+let currentContextDir: string | undefined;
+
+/**
+ * Set the context directory for diagram registration.
+ * Call before parseMarkdown() so registered diagrams know their !include context.
+ */
+export function setDiagramContext(contextDir?: string): void {
+  currentContextDir = contextDir;
+}
+
+/**
+ * Register a diagram source and return a placeholder HTML div.
+ * Called synchronously from the marked renderer.
+ */
+export function registerDiagram(
+  type: 'mermaid' | 'plantuml',
+  source: string,
+): string {
+  const hash = diagramHash(type, source);
+  diagramSources.set(hash, {
+    source,
+    contextDir: currentContextDir,
+    createdAt: Date.now(),
+  });
+  startCleanup();
+
+  // Emit a client-side placeholder that the LazyDiagram component will hydrate
+  return `<div class="embedded-diagram-lazy" data-diagram-type="${type}" data-diagram-hash="${hash}"><!--DIAGRAM:${type}:${hash}--></div>\n`;
+}
+
+/**
+ * Look up a registered diagram source by hash.
+ * Used by the /api/diagram endpoint for on-demand rendering.
+ */
+export function getDiagramSource(
+  hash: string,
+): { type: string; source: string; contextDir?: string } | null {
+  const entry = diagramSources.get(hash);
+  if (!entry) return null;
+  return { type: '', source: entry.source, contextDir: entry.contextDir };
+}
+
+/**
+ * Render a diagram to SVG (with cache). Used by the /api/diagram endpoint.
+ */
+export async function renderDiagramToSvg(
+  type: string,
+  source: string,
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  _contextDir?: string,
+): Promise<string | null> {
+  try {
+    return await getOrRenderDiagram(type, source, () => {
+      if (type === 'mermaid') return renderMermaidFromSource(source);
+      if (type === 'plantuml') return renderPlantUmlFromSource(source);
+      return null;
+    });
+  } catch (err) {
+    console.error(
+      `[embeddedDiagrams] ${type} render failed:`,
+      (err as Error).message,
+    );
+    return null;
+  }
+}
+
+/**
+ * Replace all diagram placeholders in rendered HTML with inline SVGs.
+ * Used for PDF/DOCX export where client-side lazy loading isn't available.
+ */
+export async function renderEmbeddedDiagrams(
+  html: string,
+  contextDir?: string,
+): Promise<string> {
+  const matches = [...html.matchAll(PLACEHOLDER_RE)];
+  if (matches.length === 0) return html;
+
+  let result = html;
+  for (const match of matches) {
+    const [placeholder, type, hash] = match;
+    const entry = diagramSources.get(hash);
+    if (!entry) continue;
+    const source = entry.source;
+    if (!source) continue;
+
+    const svg = await renderDiagramToSvg(
+      type,
+      source,
+      contextDir ?? entry.contextDir,
+    );
+
+    if (svg) {
+      const wrapped = `<div class="embedded-diagram-rendered" data-type="${type}">${svg}</div>`;
+      result = result.replace(placeholder, wrapped);
+    } else {
+      const escaped = escapeHtml(source);
+      const errorBlock = `<div class="embedded-diagram-error" data-type="${type}"><div class="diagram-error-label">${type} render failed</div><pre class="hljs"><code>${escaped}</code></pre></div>`;
+      result = result.replace(placeholder, errorBlock);
+    }
+  }
+
+  return result;
+}
+
+function escapeHtml(str: string): string {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}