@karmaniverous/jeeves-server 3.0.0-0

package/src/routes/api/diagrams.ts

@@ -0,0 +1,53 @@
+/**
+ * Diagram rendering API route.
+ *
+ * Handles: /api/diagram/:type/:hash
+ */
+
+import type { FastifyPluginAsync } from 'fastify';
+
+import {
+  getDiagramSource,
+  renderDiagramToSvg,
+} from '../../services/embeddedDiagrams.js';
+
+// eslint-disable-next-line @typescript-eslint/require-await
+export const diagramsRoutes: FastifyPluginAsync = async (fastify) => {
+  fastify.get<{ Params: { type: string; hash: string } }>(
+    '/api/diagram/:type/:hash',
+    async (request, reply) => {
+      const { type, hash: hashWithExt } = request.params;
+      const hash = hashWithExt.replace(/\.svg$/, '');
+
+      if (!['mermaid', 'plantuml'].includes(type)) {
+        return reply.code(400).send({ error: 'Invalid diagram type' });
+      }
+      if (!/^[a-f0-9]{64}$/.test(hash)) {
+        return reply.code(400).send({ error: 'Invalid hash' });
+      }
+
+      const entry = getDiagramSource(hash);
+      if (!entry) {
+        return reply
+          .code(404)
+          .send({ error: 'Diagram source not found (may have expired)' });
+      }
+
+      const svg = await renderDiagramToSvg(
+        type,
+        entry.source,
+        entry.contextDir,
+      );
+      if (!svg) {
+        return reply
+          .code(500)
+          .send({ error: 'Renderer returned empty result' });
+      }
+
+      return reply
+        .header('Content-Type', 'image/svg+xml')
+        .header('Cache-Control', 'public, max-age=86400, immutable')
+        .send(svg);
+    },
+  );
+};

package/src/routes/api/directory.ts

@@ -0,0 +1,123 @@
+/**
+ * Directory listing API route.
+ *
+ * Handles: GET /api/path/*
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import type { FastifyPluginAsync } from 'fastify';
+
+import {
+  _directoryVisibleUnderScopes,
+  _pathMatchesPatterns,
+  _pathMatchesScopes,
+} from '../../auth/keys.js';
+import { getConfig } from '../../config/index.js';
+import { filterBreadcrumbsForOutsider } from '../../util/breadcrumbs.js';
+import {
+  breadcrumbParts,
+  fsPathToUrl,
+  getRoots,
+  urlPathToFs,
+} from '../../util/platform.js';
+
+// eslint-disable-next-line @typescript-eslint/require-await
+export const directoryRoutes: FastifyPluginAsync = async (fastify) => {
+  const roots = getRoots(getConfig().roots);
+
+  fastify.get<{ Params: { '*': string } }>(
+    '/api/path/*',
+    async (request, reply) => {
+      const reqPath = request.params['*'];
+      if (!reqPath) return reply.redirect('/api/drives');
+
+      const fsPath = urlPathToFs(reqPath, roots);
+      if (!fsPath) return reply.code(404).send({ error: 'Invalid path' });
+      const resolved = path.resolve(fsPath);
+
+      if (!fs.existsSync(resolved)) {
+        return reply.code(404).send({ error: 'Not found', path: resolved });
+      }
+
+      const stats = fs.statSync(resolved);
+      if (!stats.isDirectory()) {
+        const ext = path.extname(resolved).toLowerCase();
+        return reply.send({
+          type: 'file',
+          path: reqPath,
+          ext,
+          size: stats.size,
+          mtime: stats.mtime.toISOString().split('T')[0],
+        });
+      }
+
+      const isInsider = request.accessMode === 'insider';
+      const insiderScopes = request.insiderScopes ?? null;
+
+      const allEntries = fs.readdirSync(resolved, { withFileTypes: true });
+
+      const entries = insiderScopes
+        ? allEntries.filter((entry) => {
+            const entryPath = path.join(resolved, entry.name);
+            const entryUrlPath = fsPathToUrl(entryPath, roots);
+            if (insiderScopes.deny.length > 0) {
+              if (_pathMatchesPatterns(entryUrlPath, insiderScopes.deny))
+                return false;
+            }
+            if (entry.isDirectory()) {
+              return _directoryVisibleUnderScopes(
+                entryUrlPath,
+                insiderScopes.allow,
+              );
+            }
+            return _pathMatchesScopes(entryUrlPath, insiderScopes);
+          })
+        : allEntries;
+
+      const sorted = entries.sort((a, b) => {
+        if (a.isDirectory() && !b.isDirectory()) return -1;
+        if (!a.isDirectory() && b.isDirectory()) return 1;
+        return a.name.localeCompare(b.name);
+      });
+
+      const result = sorted.map((entry) => {
+        const entryPath = path.join(resolved, entry.name);
+        let size: number | null = null;
+        let mtime: string | null = null;
+        const ext = path.extname(entry.name).toLowerCase();
+        try {
+          const entryStats = fs.statSync(entryPath);
+          mtime = entryStats.mtime.toISOString().split('T')[0];
+          if (!entry.isDirectory()) size = entryStats.size;
+        } catch {
+          /* ignore */
+        }
+        return {
+          name: entry.name,
+          type: entry.isDirectory() ? 'directory' : 'file',
+          ext,
+          size,
+          mtime,
+        };
+      });
+
+      const breadcrumbs = breadcrumbParts(resolved, roots);
+      const matchedPath = request.authMatchedPath ?? null;
+      const filteredBreadcrumbs = filterBreadcrumbsForOutsider(
+        breadcrumbs,
+        isInsider,
+        matchedPath,
+        true,
+      );
+
+      return reply.send({
+        path: reqPath,
+        entries: result,
+        breadcrumbs: filteredBreadcrumbs,
+        isInsider,
+      });
+    },
+  );
+};

package/src/routes/api/drives.ts

@@ -0,0 +1,23 @@
+/**
+ * Drive listing API route.
+ *
+ * Handles: GET /api/drives
+ */
+
+import type { FastifyPluginAsync, FastifyReply, FastifyRequest } from 'fastify';
+
+import { getConfig } from '../../config/index.js';
+import { getRoots } from '../../util/platform.js';
+
+// eslint-disable-next-line @typescript-eslint/require-await
+export const drivesRoutes: FastifyPluginAsync = async (fastify) => {
+  const roots = getRoots(getConfig().roots);
+
+  fastify.get(
+    '/api/drives',
+    async (_request: FastifyRequest, reply: FastifyReply) => {
+      const drives = roots.map((r) => ({ letter: r.id, label: r.label }));
+      return reply.send(drives);
+    },
+  );
+};

package/src/routes/api/export.ts

@@ -0,0 +1,314 @@
+/**
+ * Export API routes.
+ *
+ * Handles: /api/export/*, /api/mermaid-export/*, /api/plantuml-export/*
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+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 {
+  cacheExport,
+  clearDiagramCacheForFile,
+  clearExportCache,
+  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
+export const exportRoutes: FastifyPluginAsync = async (fastify) => {
+  const roots = getRoots(getConfig().roots);
+
+  // GET /api/export/*
+  fastify.get<{ Params: { '*': string }; Querystring: { format?: string } }>(
+    '/api/export/*',
+    async (request, reply) => {
+      const reqPath = request.params['*'];
+      if (!reqPath) return reply.code(400).send({ error: 'Path required' });
+
+      const exportFsPath = urlPathToFs(reqPath, roots);
+      if (!exportFsPath) return reply.code(404).send({ error: 'Invalid path' });
+      const resolved = path.resolve(exportFsPath);
+
+      if (!fs.existsSync(resolved))
+        return reply.code(404).send({ error: 'Not found', path: resolved });
+
+      const format = request.query.format ?? 'pdf';
+      const stats = fs.statSync(resolved);
+
+      // ZIP export for directories
+      if (stats.isDirectory()) {
+        if (format !== 'zip')
+          return reply
+            .code(400)
+            .send({ error: 'Directories only support ZIP export' });
+        const isInsider = request.accessMode === 'insider';
+        if (!isInsider)
+          return reply
+            .code(403)
+            .send({ error: 'ZIP export requires insider access' });
+
+        const config = getConfig();
+        const totalSize = getDirSize(resolved);
+        const maxSizeBytes = config.maxZipSizeMb * 1024 * 1024;
+        if (totalSize > maxSizeBytes) {
+          return reply.code(413).send({
+            error: `Directory too large for ZIP export (${String(Math.round(totalSize / 1024 / 1024))}MB, max ${String(config.maxZipSizeMb)}MB)`,
+          });
+        }
+
+        const dirName = path.basename(resolved);
+        const archive = archiver('zip', { zlib: { level: 6 } });
+        reply.header('Content-Type', 'application/zip');
+        reply.header(
+          'Content-Disposition',
+          `attachment; filename="${dirName}.zip"`,
+        );
+        reply.send(archive);
+        archive.directory(resolved, dirName);
+        void archive.finalize();
+        return;
+      }
+
+      // PDF/DOCX export for files
+      if (format !== 'pdf' && format !== 'docx') {
+        return reply
+          .code(400)
+          .send({ error: 'Files support pdf or docx export' });
+      }
+
+      const ext = path.extname(resolved).toLowerCase();
+      if (ext !== '.md')
+        return reply
+          .code(400)
+          .send({ error: 'Only markdown files support PDF/DOCX export' });
+
+      const config = getConfig();
+      const internalKey = config.internalInsiderKey;
+      const { port } = config;
+      const exportKey = (request.query as { key?: string }).key || internalKey;
+      if (!exportKey)
+        return reply
+          .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 fileName = path.basename(resolved);
+      const baseName = fileName.replace(/\.md$/i, '');
+
+      try {
+        const contentType =
+          format === 'pdf'
+            ? 'application/pdf'
+            : 'application/vnd.openxmlformats-officedocument.wordprocessingml.document';
+        const fileExt = format === 'pdf' ? 'pdf' : 'docx';
+
+        // Check export cache
+        const cached = getCachedExport(resolved, format);
+        if (cached) {
+          return await reply
+            .header('Content-Type', contentType)
+            .header(
+              'Content-Disposition',
+              `attachment; filename="${baseName}.${fileExt}"`,
+            )
+            .header('Content-Length', cached.length)
+            .send(cached);
+        }
+
+        const buffer = await exportPage({
+          url: exportUrl,
+          fileName,
+          format: format as ExportFormat,
+        });
+
+        // Cache the result
+        cacheExport(resolved, format, buffer);
+
+        return await reply
+          .header('Content-Type', contentType)
+          .header(
+            'Content-Disposition',
+            `attachment; filename="${baseName}.${fileExt}"`,
+          )
+          .header('Content-Length', buffer.length)
+          .send(buffer);
+      } catch (err) {
+        appendEvent({ kind: `${format}_export_error`, error: String(err) });
+        return reply.code(500).send({
+          error: `${format.toUpperCase()} export failed`,
+          details: String(err),
+        });
+      }
+    },
+  );
+
+  // DELETE /api/export-cache/* — clear all caches for a file (insider-only)
+  fastify.delete<{ Params: { '*': string } }>(
+    '/api/export-cache/*',
+    async (request, reply) => {
+      if (request.accessMode !== 'insider') {
+        return reply.code(403).send({ error: 'Insider access required' });
+      }
+
+      const reqPath = request.params['*'];
+      if (!reqPath) return reply.code(400).send({ error: 'Path required' });
+
+      const fsPath = urlPathToFs(reqPath, roots);
+      if (!fsPath) return reply.code(404).send({ error: 'Invalid path' });
+      const resolved = path.resolve(fsPath);
+
+      const { getDiagramCacheDir } =
+        await import('../../services/diagramCache.js');
+      const diagCacheDir = getDiagramCacheDir();
+      const exportCount = clearExportCache(resolved);
+      const embeddedCount = clearDiagramCacheForFile(resolved, diagCacheDir);
+      const standaloneCount = clearStandaloneDiagramCache(
+        resolved,
+        diagCacheDir,
+      );
+
+      return reply.send({
+        cleared: {
+          exports: exportCount,
+          diagrams: embeddedCount + standaloneCount,
+        },
+      });
+    },
+  );
+
+  // 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);
+    },
+  );
+};