@karmaniverous/jeeves-server 3.4.2 → 3.5.0

package/src/routes/api/diagramExport.ts

@@ -0,0 +1,170 @@
+/**
+ * Diagram export routes — standalone Mermaid and PlantUML file rendering.
+ *
+ * Extracted from export.ts to maintain single responsibility and stay within
+ * the 300 LOC limit. Both handlers share a common cache-then-render pattern
+ * via `serveDiagramExport()`.
+ *
+ * @packageDocumentation
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import type { FastifyPluginAsync, FastifyReply } from 'fastify';
+
+import { getConfig } from '../../config/index.js';
+import {
+  cacheDiagramBuffer,
+  getCachedDiagramBuffer,
+} from '../../services/diagramCache.js';
+import { renderMermaidToFile } from '../../services/mermaid.js';
+import {
+  getPlantUmlFormats,
+  renderPlantUmlToBuffer,
+} from '../../services/plantuml.js';
+import { DIAGRAM_CONTENT_TYPES } from '../../util/fileDetection.js';
+import { getRoots, type RootEntry, urlPathToFs } from '../../util/platform.js';
+
+/** Diagram engine identifier for cache keys. */
+type DiagramEngine = 'mermaid' | 'plantuml';
+
+/** Resolve a URL path to a validated filesystem path, or send an error reply. */
+function resolveExportPath(
+  reqPath: string | undefined,
+  roots: RootEntry[],
+  reply: FastifyReply,
+): string | null {
+  if (!reqPath) {
+    void reply.code(400).send({ error: 'Path required' });
+    return null;
+  }
+  const fsPath = urlPathToFs(reqPath, roots);
+  if (!fsPath) {
+    void reply.code(404).send({ error: 'Invalid path' });
+    return null;
+  }
+  return path.resolve(fsPath);
+}
+
+/** Send a diagram buffer with appropriate content-type and disposition. */
+function sendDiagram(
+  reply: FastifyReply,
+  buffer: Buffer | Uint8Array,
+  format: string,
+  downloadName: string,
+): void {
+  void reply
+    .header(
+      'Content-Type',
+      DIAGRAM_CONTENT_TYPES[format] ?? 'application/octet-stream',
+    )
+    .header('Content-Disposition', `attachment; filename="${downloadName}"`)
+    .send(buffer);
+}
+
+/**
+ * Serve a diagram export with cache-first semantics.
+ *
+ * Checks the diagram cache, renders on miss, caches the result, and sends
+ * the response. This eliminates the duplicated cache-then-render pattern
+ * between the Mermaid and PlantUML handlers.
+ */
+async function serveDiagramExport(
+  reply: FastifyReply,
+  engine: DiagramEngine,
+  resolved: string,
+  ext: string,
+  format: string,
+  render: (resolved: string, format: string) => Promise<Buffer | null>,
+): Promise<void> {
+  const source = fs.readFileSync(resolved, 'utf8');
+  const baseName = path.basename(resolved, ext);
+  const downloadName = `${baseName}.${format}`;
+
+  const cached = getCachedDiagramBuffer(engine, source, format);
+  if (cached) {
+    sendDiagram(reply, cached, format, downloadName);
+    return;
+  }
+
+  const buffer = await render(resolved, format);
+  if (!buffer) {
+    void reply.code(500).send({
+      error: `${engine.charAt(0).toUpperCase() + engine.slice(1)} render failed`,
+    });
+    return;
+  }
+
+  cacheDiagramBuffer(engine, source, buffer, format);
+  sendDiagram(reply, buffer, format, downloadName);
+}
+
+// eslint-disable-next-line @typescript-eslint/require-await
+export const diagramExportRoutes: FastifyPluginAsync = async (fastify) => {
+  const roots = getRoots(getConfig().roots);
+
+  // GET /api/mermaid-export/*
+  fastify.get<{ Params: { '*': string }; Querystring: { format?: string } }>(
+    '/api/mermaid-export/*',
+    async (request, reply) => {
+      const resolved = resolveExportPath(request.params['*'], roots, reply);
+      if (!resolved) return;
+
+      if (
+        !fs.existsSync(resolved) ||
+        !resolved.toLowerCase().endsWith('.mmd')
+      ) {
+        return reply.code(404).send({ error: 'Mermaid file not found' });
+      }
+
+      const mermaidFormats = ['svg', 'png', 'pdf'];
+      const format = mermaidFormats.includes(request.query.format ?? '')
+        ? request.query.format!
+        : 'svg';
+
+      await serveDiagramExport(
+        reply,
+        'mermaid',
+        resolved,
+        '.mmd',
+        format,
+        async (filePath, fmt) => {
+          const outFile = await renderMermaidToFile(filePath, fmt);
+          return outFile ? fs.readFileSync(outFile) : null;
+        },
+      );
+    },
+  );
+
+  // GET /api/plantuml-export/*
+  fastify.get<{ Params: { '*': string }; Querystring: { format?: string } }>(
+    '/api/plantuml-export/*',
+    async (request, reply) => {
+      const resolved = resolveExportPath(request.params['*'], roots, reply);
+      if (!resolved) return;
+
+      const ext = path.extname(resolved).toLowerCase();
+      if (
+        !fs.existsSync(resolved) ||
+        !['.puml', '.plantuml', '.pu'].includes(ext)
+      ) {
+        return reply.code(404).send({ error: 'PlantUML file not found' });
+      }
+
+      const supported = getPlantUmlFormats();
+      const format = supported.includes(request.query.format ?? '')
+        ? request.query.format!
+        : 'svg';
+
+      await serveDiagramExport(
+        reply,
+        'plantuml',
+        resolved,
+        ext,
+        format,
+        renderPlantUmlToBuffer,
+      );
+    },
+  );
+};

package/src/routes/api/events.ts

@@ -0,0 +1,22 @@
+/**
+ * GET /api/events — returns recent event log entries.
+ */
+
+import type { FastifyPluginAsync } from 'fastify';
+
+import { getRecentEvents } from '../../services/eventLog.js';
+
+// eslint-disable-next-line @typescript-eslint/require-await
+export const eventsRoutes: FastifyPluginAsync = async (fastify) => {
+  fastify.get<{ Querystring: { limit?: string } }>(
+    '/events',
+    // eslint-disable-next-line @typescript-eslint/require-await
+    async (request) => {
+      const limit = Math.min(
+        Math.max(parseInt(request.query.limit ?? '20', 10) || 20, 1),
+        100,
+      );
+      return getRecentEvents(limit);
+    },
+  );
+};

package/src/routes/api/export.ts

@@ -1,7 +1,10 @@
 /**
- * Export API routes.
+ * Document and directory export routes.
  *
- * Handles: /api/export/*, /api/mermaid-export/*, /api/plantuml-export/*
+ * Handles: /api/export/* (PDF/DOCX/ZIP), /api/export-cache/* (cache clearing).
+ * Diagram export routes (Mermaid/PlantUML) are in diagramExport.ts.
+ *
+ * @packageDocumentation
  */
 
 import fs from 'node:fs';
@@ -11,10 +14,6 @@ import archiver from 'archiver';
 import type { FastifyPluginAsync } from 'fastify';
 
 import { getConfig } from '../../config/index.js';
-import {
-  cacheDiagramBuffer,
-  getCachedDiagramBuffer,
-} from '../../services/diagramCache.js';
 import { appendEvent } from '../../services/eventQueue.js';
 import { type ExportFormat, exportPage } from '../../services/export.js';
 import {
@@ -24,12 +23,6 @@ import {
   clearStandaloneDiagramCache,
   getCachedExport,
 } from '../../services/exportCache.js';
-import { renderMermaidToFile } from '../../services/mermaid.js';
-import {
-  getPlantUmlFormats,
-  renderPlantUmlToBuffer,
-} from '../../services/plantuml.js';
-import { DIAGRAM_CONTENT_TYPES } from '../../util/fileDetection.js';
 import { getDirSize, getRoots, urlPathToFs } from '../../util/platform.js';
 
 // eslint-disable-next-line @typescript-eslint/require-await
@@ -109,7 +102,7 @@ export const exportRoutes: FastifyPluginAsync = async (fastify) => {
           .code(500)
           .send({ error: 'Export unavailable — no internal key configured' });
 
-      const exportUrl = `http://localhost:${String(port)}/browse/${reqPath}?key=${exportKey}&render_diagrams=1&plain_code=1`;
+      const exportUrl = `http://127.0.0.1:${String(port)}/browse/${reqPath}?key=${exportKey}&render_diagrams=1&plain_code=1`;
       const fileName = path.basename(resolved);
       const baseName = fileName.replace(/\.md$/i, '');
 
@@ -193,122 +186,4 @@ export const exportRoutes: FastifyPluginAsync = async (fastify) => {
       });
     },
   );
-
-  // GET /api/mermaid-export/*
-  fastify.get<{ Params: { '*': string }; Querystring: { format?: string } }>(
-    '/api/mermaid-export/*',
-    async (request, reply) => {
-      const reqPath = request.params['*'];
-      if (!reqPath) return reply.code(400).send({ error: 'Path required' });
-
-      const mmdFsPath = urlPathToFs(reqPath, roots);
-      if (!mmdFsPath) return reply.code(404).send({ error: 'Invalid path' });
-      const resolved = path.resolve(mmdFsPath);
-
-      if (
-        !fs.existsSync(resolved) ||
-        !resolved.toLowerCase().endsWith('.mmd')
-      ) {
-        return reply.code(404).send({ error: 'Mermaid file not found' });
-      }
-
-      const mermaidFormats = ['svg', 'png', 'pdf'];
-      const format = mermaidFormats.includes(request.query.format ?? '')
-        ? request.query.format!
-        : 'svg';
-      const source = fs.readFileSync(resolved, 'utf8');
-
-      // Check cache
-      const cachedBuffer = getCachedDiagramBuffer('mermaid', source, format);
-      if (cachedBuffer) {
-        const downloadName = `${path.basename(resolved, '.mmd')}.${format}`;
-        return reply
-          .header(
-            'Content-Type',
-            DIAGRAM_CONTENT_TYPES[format] ?? 'application/octet-stream',
-          )
-          .header(
-            'Content-Disposition',
-            `attachment; filename="${downloadName}"`,
-          )
-          .send(cachedBuffer);
-      }
-
-      const outFile = await renderMermaidToFile(resolved, format);
-      if (!outFile)
-        return reply.code(500).send({ error: 'Mermaid render failed' });
-
-      const content = fs.readFileSync(outFile);
-      cacheDiagramBuffer('mermaid', source, content, format);
-      const downloadName = path.basename(outFile);
-
-      return reply
-        .header(
-          'Content-Type',
-          DIAGRAM_CONTENT_TYPES[format] ?? 'application/octet-stream',
-        )
-        .header('Content-Disposition', `attachment; filename="${downloadName}"`)
-        .send(content);
-    },
-  );
-
-  // GET /api/plantuml-export/*
-  fastify.get<{ Params: { '*': string }; Querystring: { format?: string } }>(
-    '/api/plantuml-export/*',
-    async (request, reply) => {
-      const reqPath = request.params['*'];
-      if (!reqPath) return reply.code(400).send({ error: 'Path required' });
-
-      const pumlFsPath = urlPathToFs(reqPath, roots);
-      if (!pumlFsPath) return reply.code(404).send({ error: 'Invalid path' });
-      const resolved = path.resolve(pumlFsPath);
-
-      const ext = path.extname(resolved).toLowerCase();
-      if (
-        !fs.existsSync(resolved) ||
-        !['.puml', '.plantuml', '.pu'].includes(ext)
-      ) {
-        return reply.code(404).send({ error: 'PlantUML file not found' });
-      }
-
-      const supported = getPlantUmlFormats();
-      const format = supported.includes(request.query.format ?? '')
-        ? request.query.format!
-        : 'svg';
-      const source = fs.readFileSync(resolved, 'utf8');
-
-      const cachedBuffer = getCachedDiagramBuffer('plantuml', source, format);
-      if (cachedBuffer) {
-        const baseName = path.basename(resolved, ext);
-        return reply
-          .header(
-            'Content-Type',
-            DIAGRAM_CONTENT_TYPES[format] ?? 'application/octet-stream',
-          )
-          .header(
-            'Content-Disposition',
-            `attachment; filename="${baseName}.${format}"`,
-          )
-          .send(cachedBuffer);
-      }
-
-      const buffer = await renderPlantUmlToBuffer(resolved, format);
-      if (!buffer)
-        return reply.code(500).send({ error: 'PlantUML render failed' });
-
-      cacheDiagramBuffer('plantuml', source, buffer, format);
-      const baseName = path.basename(resolved, ext);
-
-      return reply
-        .header(
-          'Content-Type',
-          DIAGRAM_CONTENT_TYPES[format] ?? 'application/octet-stream',
-        )
-        .header(
-          'Content-Disposition',
-          `attachment; filename="${baseName}.${format}"`,
-        )
-        .send(buffer);
-    },
-  );
 };

package/src/routes/api/index.ts

@@ -5,9 +5,11 @@
 import type { FastifyPluginAsync } from 'fastify';
 
 import { authStatusRoutes } from './auth-status.js';
+import { diagramExportRoutes } from './diagramExport.js';
 import { diagramsRoutes } from './diagrams.js';
 import { directoryRoutes } from './directory.js';
 import { drivesRoutes } from './drives.js';
+import { eventsRoutes } from './events.js';
 import { exportRoutes } from './export.js';
 import { fileContentRoutes } from './fileContent.js';
 import { linkInfoRoutes } from './linkInfo.js';
@@ -26,9 +28,11 @@ export const apiRoute: FastifyPluginAsync = async (fastify) => {
   await fastify.register(linkInfoRoutes);
   await fastify.register(rawRoutes);
   await fastify.register(exportRoutes);
+  await fastify.register(diagramExportRoutes);
   await fastify.register(diagramsRoutes);
   await fastify.register(runnerRoutes);
   await fastify.register(searchRoutes);
   await fastify.register(sharingRoutes);
   await fastify.register(authStatusRoutes);
+  await fastify.register(eventsRoutes);
 };

package/src/routes/api/search.ts

@@ -1,18 +1,20 @@
 /**
  * Search API route — proxies to jeeves-watcher for semantic search.
  *
- * Handles: POST /api/search
+ * Handles: POST /api/search, GET /api/search/facets.
  * Insider-only. Results filtered by insider's scope.
+ *
+ * @packageDocumentation
  */
 
 import { stat } from 'node:fs/promises';
-import path from 'node:path';
 
 import type { FastifyPluginAsync } from 'fastify';
 import picomatch from 'picomatch';
 
 import { getConfig } from '../../config/index.js';
 import type { NormalizedScopes } from '../../config/types.js';
+import { fsPathToUrl, getRoots, urlPathToFs } from '../../util/platform.js';
 
 /** Check if a path passes the insider's scope rules. */
 function pathAllowedByScope(
@@ -69,62 +71,6 @@ interface GroupedResult {
   }>;
 }
 
-/**
- * Resolve a browse path back to a filesystem path using roots config.
- * Inverse of fsPathToBrowsePath.
- */
-function browsePathToFsPath(
-  browsePath: string,
-  roots: Record<string, string>,
-): string | null {
-  const parts = browsePath.split('/');
-  const label = parts[0];
-  const rest = parts.slice(1).join('/');
-
-  // Check if label matches a root
-  if (roots[label]) {
-    return path.join(roots[label], rest);
-  }
-
-  // Windows drive letter: j/foo/bar → J:\foo\bar
-  if (/^[a-zA-Z]$/.test(label)) {
-    return `${label.toUpperCase()}:\\${rest.replace(/\//g, '\\')}`;
-  }
-
-  return null;
-}
-
-/**
- * Convert an absolute filesystem path to a browse URL path.
- * Maps drive letters and root mounts back to the URL scheme.
- */
-function fsPathToBrowsePath(
-  fsPath: string,
-  roots: Record<string, string>,
-): string | null {
-  const normalized = fsPath.replace(/\\/g, '/');
-
-  // Windows drive letter: j:/foo/bar → j/foo/bar
-  const driveMatch = normalized.match(/^([a-zA-Z]):\/(.*)$/);
-  if (driveMatch) {
-    return `${driveMatch[1].toLowerCase()}/${driveMatch[2]}`;
-  }
-
-  // Linux roots: find matching root prefix
-  for (const [label, rootPath] of Object.entries(roots)) {
-    const normalizedRoot = rootPath.replace(/\\/g, '/').replace(/\/$/, '');
-    if (normalized.startsWith(normalizedRoot + '/')) {
-      const relative = normalized.slice(normalizedRoot.length + 1);
-      return `${label}/${relative}`;
-    }
-    if (normalized === normalizedRoot) {
-      return label;
-    }
-  }
-
-  return null;
-}
-
 // eslint-disable-next-line @typescript-eslint/require-await
 export const searchRoutes: FastifyPluginAsync = async (fastify) => {
   fastify.post<{
@@ -150,7 +96,7 @@ export const searchRoutes: FastifyPluginAsync = async (fastify) => {
     }
 
     const insiderScopes = request.insiderScopes;
-    const roots = config.roots ?? {};
+    const roots = getRoots(config.roots);
 
     // Over-fetch to account for scope filtering
     const fetchLimit = Math.min(limit * 5, 200);
@@ -177,11 +123,11 @@ export const searchRoutes: FastifyPluginAsync = async (fastify) => {
         const fp = r.payload.file_path;
         if (!fp) continue;
 
-        const browsePath = fsPathToBrowsePath(fp, roots);
-        if (!browsePath) continue;
+        const urlPath = fsPathToUrl(fp, roots);
+        // fsPathToUrl returns "/drive/path"; strip leading slash for browsePath
+        const browsePath = urlPath.replace(/^\//, '');
 
         // Check insider scope
-        const urlPath = `/${browsePath}`;
         if (!pathAllowedByScope(urlPath, insiderScopes ?? null)) continue;
 
         permitted.push({ ...r, browsePath });
@@ -248,7 +194,7 @@ export const searchRoutes: FastifyPluginAsync = async (fastify) => {
       await Promise.all(
         grouped.map(async (g) => {
           g.chunks.sort((a, b) => a.index - b.index);
-          const fsPath = browsePathToFsPath(g.browsePath, roots);
+          const fsPath = urlPathToFs(g.browsePath, roots);
           if (fsPath) {
             try {
               const s = await stat(fsPath);

package/src/routes/api/sharing.test.ts

@@ -0,0 +1,66 @@
+/**
+ * Tests for sharing route helpers.
+ *
+ * @packageDocumentation
+ */
+
+import { describe, expect, it } from 'vitest';
+
+// buildDeepShareUrl is not exported from the module, so we test it via
+// the module's internal behavior. Since it's a pure function, we extract
+// and test the URL construction logic directly.
+
+/** Inline copy of buildDeepShareUrl for unit testing. */
+function buildDeepShareUrl(
+  targetPath: string,
+  key: string,
+  params: { depth: number; dirs: boolean; stack: string; exp?: string },
+): string {
+  let url = `/browse${targetPath}?key=${key}&d=${String(params.depth)}&dirs=${params.dirs ? '1' : '0'}&s=${params.stack}`;
+  if (params.exp) url += `&exp=${params.exp}`;
+  return url;
+}
+
+describe('buildDeepShareUrl', () => {
+  it('builds a basic deep share URL without expiry', () => {
+    const url = buildDeepShareUrl('/j/docs/readme.md', 'abc123', {
+      depth: 2,
+      dirs: false,
+      stack: 'encoded-stack',
+    });
+    expect(url).toBe(
+      '/browse/j/docs/readme.md?key=abc123&d=2&dirs=0&s=encoded-stack',
+    );
+  });
+
+  it('includes expiry when provided', () => {
+    const url = buildDeepShareUrl('/j/docs/readme.md', 'abc123', {
+      depth: 1,
+      dirs: true,
+      stack: 'stk',
+      exp: '1700000000000',
+    });
+    expect(url).toBe(
+      '/browse/j/docs/readme.md?key=abc123&d=1&dirs=1&s=stk&exp=1700000000000',
+    );
+  });
+
+  it('handles zero depth', () => {
+    const url = buildDeepShareUrl('/j/file.md', 'key', {
+      depth: 0,
+      dirs: false,
+      stack: 's',
+    });
+    expect(url).toContain('d=0');
+    expect(url).toContain('dirs=0');
+  });
+
+  it('encodes dirs=1 when dirs is true', () => {
+    const url = buildDeepShareUrl('/j/dir', 'key', {
+      depth: 3,
+      dirs: true,
+      stack: 'stk',
+    });
+    expect(url).toContain('dirs=1');
+  });
+});