@karmaniverous/jeeves-server 3.4.2 → 3.5.0

package/dist/src/routes/api/diagramExport.js

@@ -0,0 +1,101 @@
+/**
+ * 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 { 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, urlPathToFs } from '../../util/platform.js';
+/** Resolve a URL path to a validated filesystem path, or send an error reply. */
+function resolveExportPath(reqPath, roots, reply) {
+    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, buffer, format, downloadName) {
+    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, engine, resolved, ext, format, render) {
+    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 = async (fastify) => {
+    const roots = getRoots(getConfig().roots);
+    // GET /api/mermaid-export/*
+    fastify.get('/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('/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/dist/src/routes/api/diagramExport.test.js

@@ -0,0 +1,134 @@
+/**
+ * Tests for diagram export route handlers.
+ *
+ * Validates the cache-first rendering pipeline shared by Mermaid and PlantUML
+ * handlers, and the path resolution + error handling for both routes.
+ *
+ * @packageDocumentation
+ */
+import fs from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+// Mock config before importing the module under test
+const tmpDir = path.join(tmpdir(), `diagramExport-test-${String(Date.now())}`);
+vi.mock('../../config/index.js', () => ({
+    getConfig: () => ({
+        roots: {},
+    }),
+}));
+vi.mock('../../services/diagramCache.js', () => {
+    let cache = {};
+    return {
+        getCachedDiagramBuffer: (engine, source, format) => {
+            const key = `${engine}:${source}:${format}`;
+            return cache[key] ?? null;
+        },
+        cacheDiagramBuffer: (engine, source, buffer, format) => {
+            cache[`${engine}:${source}:${format}`] = buffer;
+        },
+        _reset: () => {
+            cache = {};
+        },
+    };
+});
+vi.mock('../../services/mermaid.js', () => ({
+    renderMermaidToFile: vi.fn(),
+}));
+vi.mock('../../services/plantuml.js', () => ({
+    getPlantUmlFormats: () => ['svg', 'png'],
+    renderPlantUmlToBuffer: vi.fn(),
+}));
+const { diagramExportRoutes } = await import('./diagramExport.js');
+const { renderMermaidToFile } = await import('../../services/mermaid.js');
+const { renderPlantUmlToBuffer } = await import('../../services/plantuml.js');
+/** Minimal Fastify reply mock that captures sent data. */
+function createReplyMock() {
+    const headers = {};
+    let sentData = null;
+    let statusCode = 200;
+    const reply = {
+        code: (c) => {
+            statusCode = c;
+            return reply;
+        },
+        header: (key, value) => {
+            headers[key.toLowerCase()] = value;
+            return reply;
+        },
+        send: (data) => {
+            sentData = data;
+            return reply;
+        },
+        get statusCode() {
+            return statusCode;
+        },
+        get headers() {
+            return headers;
+        },
+        get sentData() {
+            return sentData;
+        },
+    };
+    return reply;
+}
+describe('diagramExportRoutes', () => {
+    const routes = {};
+    beforeEach(async () => {
+        fs.mkdirSync(tmpDir, { recursive: true });
+        const fakeFastify = {
+            get: (routePath, handler) => {
+                routes[routePath] = handler;
+            },
+        };
+        await diagramExportRoutes(fakeFastify, {});
+    });
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+        vi.restoreAllMocks();
+    });
+    it('returns 400 when no path is provided for mermaid export', async () => {
+        const reply = createReplyMock();
+        await routes['/api/mermaid-export/*']({ params: { '*': '' }, query: {} }, reply);
+        expect(reply.statusCode).toBe(400);
+    });
+    it('returns 404 for non-existent mermaid file', async () => {
+        const reply = createReplyMock();
+        await routes['/api/mermaid-export/*']({ params: { '*': 'nonexistent.mmd' }, query: {} }, reply);
+        expect(reply.statusCode).toBe(404);
+    });
+    it('returns 400 when no path is provided for plantuml export', async () => {
+        const reply = createReplyMock();
+        await routes['/api/plantuml-export/*']({ params: { '*': '' }, query: {} }, reply);
+        expect(reply.statusCode).toBe(400);
+    });
+    it('returns 404 for non-existent plantuml file', async () => {
+        const reply = createReplyMock();
+        await routes['/api/plantuml-export/*']({ params: { '*': 'nonexistent.puml' }, query: {} }, reply);
+        expect(reply.statusCode).toBe(404);
+    });
+    it('sends 500 when mermaid render returns null', async () => {
+        // Create a real .mmd file
+        const mmdPath = path.join(tmpDir, 'test.mmd');
+        fs.writeFileSync(mmdPath, 'graph TD; A-->B');
+        // Mock urlPathToFs to resolve our temp path
+        const platformMod = await import('../../util/platform.js');
+        vi.spyOn(platformMod, 'urlPathToFs').mockReturnValue(mmdPath);
+        vi.mocked(renderMermaidToFile).mockResolvedValue(null);
+        const reply = createReplyMock();
+        await routes['/api/mermaid-export/*']({ params: { '*': 'test.mmd' }, query: { format: 'svg' } }, reply);
+        expect(reply.statusCode).toBe(500);
+        expect(reply.sentData.error).toContain('render failed');
+    });
+    it('sends 500 when plantuml render returns null', async () => {
+        const pumlPath = path.join(tmpDir, 'test.puml');
+        fs.writeFileSync(pumlPath, '@startuml\nA -> B\n@enduml');
+        const platformMod = await import('../../util/platform.js');
+        vi.spyOn(platformMod, 'urlPathToFs').mockReturnValue(pumlPath);
+        vi.mocked(renderPlantUmlToBuffer).mockResolvedValue(null);
+        const reply = createReplyMock();
+        await routes['/api/plantuml-export/*']({ params: { '*': 'test.puml' }, query: { format: 'svg' } }, reply);
+        expect(reply.statusCode).toBe(500);
+        expect(reply.sentData.error).toContain('render failed');
+    });
+});

package/dist/src/routes/api/events.js

@@ -0,0 +1,13 @@
+/**
+ * GET /api/events — returns recent event log entries.
+ */
+import { getRecentEvents } from '../../services/eventLog.js';
+// eslint-disable-next-line @typescript-eslint/require-await
+export const eventsRoutes = async (fastify) => {
+    fastify.get('/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/dist/src/routes/api/export.js

@@ -1,19 +1,18 @@
 /**
- * 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';
 import path from 'node:path';
 import archiver from 'archiver';
 import { getConfig } from '../../config/index.js';
-import { cacheDiagramBuffer, getCachedDiagramBuffer, } from '../../services/diagramCache.js';
 import { appendEvent } from '../../services/eventQueue.js';
 import { 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 = async (fastify) => {
@@ -78,7 +77,7 @@ export const exportRoutes = async (fastify) => {
             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 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, '');
         try {
@@ -140,79 +139,4 @@ export const exportRoutes = async (fastify) => {
             },
         });
     });
-    // GET /api/mermaid-export/*
-    fastify.get('/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('/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/dist/src/routes/api/index.js

@@ -2,9 +2,11 @@
  * API route registrar — composes all API sub-plugins.
  */
 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';
@@ -23,9 +25,11 @@ export const apiRoute = 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/dist/src/routes/api/search.js

@@ -1,13 +1,15 @@
 /**
  * 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 picomatch from 'picomatch';
 import { getConfig } from '../../config/index.js';
+import { fsPathToUrl, getRoots, urlPathToFs } from '../../util/platform.js';
 /** Check if a path passes the insider's scope rules. */
 function pathAllowedByScope(urlPath, scopes) {
     if (!scopes)
@@ -23,48 +25,6 @@ function pathAllowedByScope(urlPath, scopes) {
     }
     return true;
 }
-/**
- * Resolve a browse path back to a filesystem path using roots config.
- * Inverse of fsPathToBrowsePath.
- */
-function browsePathToFsPath(browsePath, roots) {
-    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, roots) {
-    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 = async (fastify) => {
     fastify.post('/api/search', async (request, reply) => {
@@ -81,7 +41,7 @@ export const searchRoutes = async (fastify) => {
             return reply.code(400).send({ error: 'query is required' });
         }
         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);
         try {
@@ -103,11 +63,10 @@ export const searchRoutes = 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 });
@@ -173,7 +132,7 @@ export const searchRoutes = async (fastify) => {
             // Sort chunks within each group by index, and fetch mtime
             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/dist/src/routes/api/sharing.js

@@ -2,6 +2,8 @@
  * Sharing API routes.
  *
  * Handles: /api/share, /api/util/share-for, /api/readme-link, /api/rotate-key
+ *
+ * @packageDocumentation
  */
 import crypto from 'node:crypto';
 import fs from 'node:fs';
@@ -14,18 +16,32 @@ import { encodeStack } from '../../services/deepShareLinks.js';
 import { computeDeepShareKey, computeOutsiderKeyWithExpiry, computePathKey, } from '../../util/crypto.js';
 import { fsPathToUrl, getRoots } from '../../util/platform.js';
 import { setInsiderKey } from '../../util/state.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const serverRoot = path.resolve(__dirname, '..', '..', '..');
+/** Build a deep-share browse URL from its constituent parts. */
+function buildDeepShareUrl(targetPath, key, params) {
+    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;
+}
 // eslint-disable-next-line @typescript-eslint/require-await
 export const sharingRoutes = async (fastify) => {
     const roots = getRoots(getConfig().roots);
+    /** Resolve the _internal key seed, or send a 503 error. */
+    function getInternalSeed(reply) {
+        const internalKey = getConfig().resolvedKeys.find((k) => k.name === '_internal');
+        if (!internalKey?.seed) {
+            void reply.code(503).send({ error: 'No _internal key configured' });
+            return null;
+        }
+        return internalKey.seed;
+    }
     // GET /api/readme-link
     fastify.get('/api/readme-link', async (_request, reply) => {
-        const config = getConfig();
-        const internalKey = config.resolvedKeys.find((k) => k.name === '_internal');
-        if (!internalKey?.seed)
-            return reply.code(503).send({ error: 'No _internal key configured' });
-        const seed = internalKey.seed;
-        const __dirname = path.dirname(fileURLToPath(import.meta.url));
-        const serverRoot = path.resolve(__dirname, '..', '..', '..');
+        const seed = getInternalSeed(reply);
+        if (!seed)
+            return;
         const readmePath = path.join(serverRoot, 'README.md');
         if (!fs.existsSync(readmePath))
             return reply.code(404).send({ error: 'README.md not found' });
@@ -33,21 +49,18 @@ export const sharingRoutes = async (fastify) => {
         const stack = encodeStack([urlPath]);
         const deepParams = { depth: 2, dirs: false, stack, exp: undefined };
         const key = computeDeepShareKey(seed, urlPath, deepParams);
-        const shareUrl = `/browse${urlPath}?key=${key}&d=2&dirs=0&s=${stack}`;
-        return reply.send({ url: shareUrl });
+        return reply.send({
+            url: buildDeepShareUrl(urlPath, key, { depth: 2, dirs: false, stack }),
+        });
     });
     // GET /api/content-link/:file — share link for content/*.md (terms, privacy)
     fastify.get('/api/content-link/:file', async (request, reply) => {
-        const config = getConfig();
-        const internalKey = config.resolvedKeys.find((k) => k.name === '_internal');
-        if (!internalKey?.seed)
-            return reply.code(503).send({ error: 'No _internal key configured' });
+        const seed = getInternalSeed(reply);
+        if (!seed)
+            return;
         const { file } = request.params;
         if (!/^[\w-]+$/.test(file))
             return reply.code(400).send({ error: 'Invalid file name' });
-        const seed = internalKey.seed;
-        const __dirname = path.dirname(fileURLToPath(import.meta.url));
-        const serverRoot = path.resolve(__dirname, '..', '..', '..');
         const contentPath = path.join(serverRoot, 'content', `${file}.md`);
         if (!fs.existsSync(contentPath))
             return reply.code(404).send({ error: `${file}.md not found` });
@@ -55,8 +68,9 @@ export const sharingRoutes = async (fastify) => {
         const stack = encodeStack([urlPath]);
         const deepParams = { depth: 0, dirs: false, stack, exp: undefined };
         const key = computeDeepShareKey(seed, urlPath, deepParams);
-        const shareUrl = `/browse${urlPath}?key=${key}&d=0&dirs=0&s=${stack}`;
-        return reply.send({ url: shareUrl });
+        return reply.send({
+            url: buildDeepShareUrl(urlPath, key, { depth: 0, dirs: false, stack }),
+        });
     });
     // POST /api/share
     fastify.post('/api/share', async (request, reply) => {
@@ -77,9 +91,12 @@ export const sharingRoutes = async (fastify) => {
                 exp: expiry,
             };
             outsiderKey = computeDeepShareKey(seed, targetPath, deepParams);
-            shareUrl = `/browse${targetPath}?key=${outsiderKey}&d=${String(depth ?? 0)}&dirs=${dirs ? '1' : '0'}&s=${stack}`;
-            if (expiry)
-                shareUrl += `&exp=${expiry}`;
+            shareUrl = buildDeepShareUrl(targetPath, outsiderKey, {
+                depth: depth ?? 0,
+                dirs: dirs ?? false,
+                stack,
+                exp: expiry,
+            });
         }
         else if (expiry) {
             outsiderKey = computeOutsiderKeyWithExpiry(seed, targetPath, expiry);
@@ -98,7 +115,7 @@ export const sharingRoutes = async (fastify) => {
         });
     });
     // POST /api/rotate-key
-    fastify.post('/api/rotate-key', async (request, reply) => {
+    fastify.post('/api/rotate-key', (request, reply) => {
         const insiderEmail = request.insiderEmail;
         if (!insiderEmail)
             return reply.code(403).send({ error: 'Insider auth required' });
@@ -109,7 +126,7 @@ export const sharingRoutes = async (fastify) => {
         const newSeed = crypto.randomBytes(32).toString('hex');
         const now = new Date().toISOString();
         setInsiderKey(insider.email, newSeed, now);
-        await resetConfig();
+        resetConfig();
         return reply.send({ ok: true, keyCreatedAt: now });
     });
     // POST /api/util/share-for

package/dist/src/routes/api/sharing.test.js

@@ -0,0 +1,52 @@
+/**
+ * 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, key, params) {
+    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');
+    });
+});

package/dist/src/routes/auth.js

@@ -73,7 +73,7 @@ export const authRoute = async (fastify) => {
             insider.seed = newSeed;
             // Persist to state.json (mutable runtime state)
             setInsiderKey(insider.email, newSeed, timestamp);
-            await resetConfig(); // Reload to pick up new state
+            resetConfig(); // Reload to pick up new state
         }
         // Set session cookie
         const cookieValue = createSessionCookie(email, sessionSecret, userInfo.picture);