@karmaniverous/jeeves-server 3.0.0-0

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

@@ -0,0 +1,71 @@
+/**
+ * Link availability query endpoint.
+ * Returns what views and exports are available for a given path.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { getConfig } from '../../config/index.js';
+import { getPlantUmlFormats } from '../../services/plantuml.js';
+import { getRoots, urlPathToFs } from '../../util/platform.js';
+// eslint-disable-next-line @typescript-eslint/require-await
+export const linkInfoRoutes = async (fastify) => {
+    const roots = getRoots(getConfig().roots);
+    fastify.get('/api/link-info/*', async (request, reply) => {
+        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);
+        let stats;
+        try {
+            stats = fs.statSync(resolved);
+        }
+        catch {
+            return reply.send({ exists: false });
+        }
+        const isDirectory = stats.isDirectory();
+        const ext = path.extname(resolved).toLowerCase();
+        const pageUrl = `/browse/${reqPath}`;
+        let rawUrl = null;
+        const exportLinks = [];
+        if (isDirectory) {
+            if (request.accessMode === 'insider') {
+                exportLinks.push({
+                    format: 'zip',
+                    url: `/api/export/${reqPath}?format=zip`,
+                });
+            }
+        }
+        else {
+            rawUrl = `/api/raw/${reqPath}`;
+            if (ext === '.md' || ext === '.markdown') {
+                exportLinks.push({ format: 'pdf', url: `/api/export/${reqPath}?format=pdf` }, { format: 'docx', url: `/api/export/${reqPath}?format=docx` });
+            }
+            else if (ext === '.mmd') {
+                for (const fmt of ['svg', 'png', 'pdf']) {
+                    exportLinks.push({
+                        format: fmt,
+                        url: `/api/mermaid-export/${reqPath}?format=${fmt}`,
+                    });
+                }
+            }
+            else if (['.puml', '.plantuml', '.pu'].includes(ext)) {
+                for (const fmt of getPlantUmlFormats()) {
+                    exportLinks.push({
+                        format: fmt,
+                        url: `/api/plantuml-export/${reqPath}?format=${fmt}`,
+                    });
+                }
+            }
+        }
+        return reply.send({
+            exists: true,
+            isDirectory,
+            pageUrl,
+            rawUrl,
+            exportLinks,
+        });
+    });
+};

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

@@ -0,0 +1,104 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+// Must set tmpDir before mocks reference it
+let tmpDir;
+vi.mock('../../config/index.js', () => ({
+    getConfig: () => ({ roots: {} }),
+}));
+vi.mock('../../services/plantuml.js', () => ({
+    getPlantUmlFormats: () => ['svg', 'png', 'pdf'],
+}));
+vi.mock('../../util/platform.js', () => ({
+    getRoots: () => ({}),
+    urlPathToFs: (reqPath) => {
+        // Simple mock: treat first segment as root name, rest as path
+        const parts = reqPath.split('/');
+        if (parts[0] === 'test')
+            return path.join(tmpDir, ...parts.slice(1));
+        return null;
+    },
+}));
+const { linkInfoRoutes } = await import('./linkInfo.js');
+describe('GET /api/link-info', () => {
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'jeeves-linkinfo-'));
+    });
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    async function callHandler(urlPath, accessMode = 'insider') {
+        const routes = {};
+        const fakeFastify = {
+            get: (routePath, handler) => {
+                routes[routePath] = handler;
+            },
+        };
+        await linkInfoRoutes(fakeFastify, {});
+        const handler = routes['/api/link-info/*'];
+        let result;
+        const fakeReply = {
+            code: () => ({
+                send: (d) => {
+                    result = d;
+                    return d;
+                },
+            }),
+            send: (d) => {
+                result = d;
+                return d;
+            },
+        };
+        const fakeRequest = {
+            params: { '*': urlPath },
+            accessMode,
+        };
+        await handler(fakeRequest, fakeReply);
+        return result;
+    }
+    it('returns exists: false for non-existent path', async () => {
+        const res = await callHandler('test/doesnotexist.md');
+        expect(res).toEqual({ exists: false });
+    });
+    it('returns directory links with ZIP for insiders', async () => {
+        fs.mkdirSync(path.join(tmpDir, 'folder'));
+        const res = await callHandler('test/folder');
+        expect(res.exists).toBe(true);
+        expect(res.isDirectory).toBe(true);
+        expect(res.rawUrl).toBe(null);
+        expect(res.exportLinks).toEqual([
+            { format: 'zip', url: '/api/export/test/folder?format=zip' },
+        ]);
+    });
+    it('omits ZIP for directories if outsider', async () => {
+        fs.mkdirSync(path.join(tmpDir, 'folder'));
+        const res = await callHandler('test/folder', 'outsider');
+        expect(res.exportLinks).toEqual([]);
+    });
+    it('returns markdown export links (pdf + docx)', async () => {
+        fs.writeFileSync(path.join(tmpDir, 'doc.md'), '# hello');
+        const res = await callHandler('test/doc.md');
+        expect(res.rawUrl).toBe('/api/raw/test/doc.md');
+        const links = res.exportLinks;
+        expect(links.map((l) => l.format)).toEqual(['pdf', 'docx']);
+    });
+    it('returns mermaid export links', async () => {
+        fs.writeFileSync(path.join(tmpDir, 'diag.mmd'), 'graph TD; A-->B');
+        const res = await callHandler('test/diag.mmd');
+        const links = res.exportLinks;
+        expect(links.map((l) => l.format)).toEqual(['svg', 'png', 'pdf']);
+    });
+    it('returns plantuml export links', async () => {
+        fs.writeFileSync(path.join(tmpDir, 'diag.puml'), '@startuml\nA->B\n@enduml');
+        const res = await callHandler('test/diag.puml');
+        const links = res.exportLinks;
+        expect(links.map((l) => l.format)).toEqual(['svg', 'png', 'pdf']);
+    });
+    it('returns no export links for plain files', async () => {
+        fs.writeFileSync(path.join(tmpDir, 'data.json'), '{}');
+        const res = await callHandler('test/data.json');
+        expect(res.rawUrl).toBe('/api/raw/test/data.json');
+        expect(res.exportLinks).toEqual([]);
+    });
+});

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

@@ -0,0 +1,117 @@
+/**
+ * API authentication middleware (preHandler hook).
+ */
+import { resolveInsiderKeyAuth, resolveKeyAuth, resolveSessionAuth, } from '../../auth/resolve.js';
+import { getConfig } from '../../config/index.js';
+import { decodeStack } from '../../services/deepShareLinks.js';
+/**
+ * Add the API auth preHandler hook directly to a Fastify instance.
+ * Must be called on the parent context (not via register()) so the hook
+ * applies to all sibling and child routes.
+ */
+export function addAuthMiddleware(fastify) {
+    fastify.addHook('preHandler', async (request, reply) => {
+        if (!request.url.startsWith('/api'))
+            return;
+        if (request.url.startsWith('/api/readme-link'))
+            return;
+        if (request.url.startsWith('/api/content-link/'))
+            return;
+        if (request.url.startsWith('/api/auth/status'))
+            return;
+        if (request.url.startsWith('/api/diagram/'))
+            return;
+        const config = getConfig();
+        // Utility endpoints handle their own scope checking
+        if (request.url.startsWith('/api/util/')) {
+            const query = request.query;
+            // Try key-based auth
+            if (query.key) {
+                const keyResult = resolveKeyAuth(config, '/', query.key, query.exp);
+                if (keyResult.valid && keyResult.mode === 'insider') {
+                    request.accessMode = 'insider';
+                    request.authSeed = keyResult.seed;
+                    request.insiderScopes = keyResult.scopes ?? null;
+                    return;
+                }
+                // Try as a direct insider key
+                const insiderResult = resolveInsiderKeyAuth(config, query.key);
+                if (insiderResult.valid) {
+                    request.accessMode = 'insider';
+                    request.authSeed = insiderResult.seed;
+                    request.insiderScopes = insiderResult.scopes ?? null;
+                    request.insiderEmail = insiderResult.email;
+                    return;
+                }
+            }
+            // Try session cookie
+            const sessionResult = resolveSessionAuth(config, request);
+            if (sessionResult.valid) {
+                request.accessMode = 'insider';
+                request.authSeed = sessionResult.seed;
+                request.insiderScopes = sessionResult.scopes ?? null;
+                request.insiderEmail = sessionResult.email;
+                return;
+            }
+            reply
+                .code(401)
+                .send({ error: 'Insider auth required for utility endpoints' });
+            return;
+        }
+        // General API auth
+        const query = request.query;
+        const deepParams = query.d !== undefined && query.s !== undefined
+            ? { d: query.d, dirs: query.dirs ?? '0', s: query.s }
+            : undefined;
+        const urlPath = request.url
+            .split('?')[0]
+            .replace('/api/path', '')
+            .replace('/api/drives', '/')
+            .replace('/api/file', '')
+            .replace('/api/raw', '')
+            .replace('/api/export-cache', '')
+            .replace('/api/export', '');
+        // Try key-based auth
+        let authResult = resolveKeyAuth(config, urlPath || '/', query.key, query.exp, deepParams);
+        // Retry with dirs fallback (directory shares)
+        if (!authResult.valid &&
+            deepParams &&
+            deepParams.dirs === '1' &&
+            query.key) {
+            const stack = decodeStack(deepParams.s);
+            const lastStackEntry = stack[stack.length - 1];
+            if (lastStackEntry && lastStackEntry !== urlPath) {
+                authResult = resolveKeyAuth(config, lastStackEntry, query.key, query.exp, deepParams);
+            }
+        }
+        // Try session cookie (always check — insiders visiting outsider links
+        // should be upgraded to insider access)
+        const sessionResult = resolveSessionAuth(config, request);
+        if (authResult.valid && sessionResult.valid) {
+            // Both key and session are valid — prefer insider session
+            request.accessMode = 'insider';
+            request.authSeed = sessionResult.seed;
+            request.insiderEmail = sessionResult.email;
+            request.insiderScopes = sessionResult.scopes ?? null;
+            request.keyAge = sessionResult.keyAge;
+            return;
+        }
+        if (authResult.valid) {
+            request.accessMode = authResult.mode;
+            request.authSeed = authResult.seed;
+            request.deepShareParams = authResult.deepShareParams;
+            request.authMatchedPath = authResult.matchedPath;
+            return;
+        }
+        if (sessionResult.valid) {
+            request.accessMode = 'insider';
+            request.authSeed = sessionResult.seed;
+            request.insiderEmail = sessionResult.email;
+            request.insiderScopes = sessionResult.scopes ?? null;
+            request.keyAge = sessionResult.keyAge;
+            return;
+        }
+        reply.code(401).send({ error: 'Unauthorized' });
+        return;
+    });
+}

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

@@ -0,0 +1,38 @@
+/**
+ * Raw file serving API route.
+ *
+ * Handles: GET /api/raw/*
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { getConfig } from '../../config/index.js';
+import { getContentType, isInlineType } from '../../util/fileDetection.js';
+import { getRoots, urlPathToFs } from '../../util/platform.js';
+// eslint-disable-next-line @typescript-eslint/require-await
+export const rawRoutes = async (fastify) => {
+    const roots = getRoots(getConfig().roots);
+    fastify.get('/api/raw/*', async (request, reply) => {
+        const reqPath = request.params['*'];
+        if (!reqPath)
+            return reply.code(400).send({ error: 'Path required' });
+        const rawFsPath = urlPathToFs(reqPath, roots);
+        if (!rawFsPath)
+            return reply.code(404).send({ error: 'Invalid path' });
+        const resolved = path.resolve(rawFsPath);
+        if (!fs.existsSync(resolved))
+            return reply.code(404).send({ error: 'Not found', path: resolved });
+        const stats = fs.statSync(resolved);
+        if (stats.isDirectory()) {
+            return reply.code(400).send({
+                error: 'Cannot serve directory as raw — use /api/export for ZIP',
+            });
+        }
+        const ext = path.extname(resolved).toLowerCase();
+        const contentType = getContentType(ext);
+        reply.header('Content-Type', contentType);
+        if (!isInlineType(contentType)) {
+            reply.header('Content-Disposition', `attachment; filename="${path.basename(resolved)}"`);
+        }
+        return reply.send(fs.readFileSync(resolved));
+    });
+};

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

@@ -0,0 +1,59 @@
+/**
+ * Runner proxy routes — proxies requests to the local jeeves-runner API.
+ *
+ * All routes require insider auth. The runner only listens on localhost,
+ * so jeeves-server acts as an authenticated gateway.
+ */
+import { getConfig } from '../../config/index.js';
+const DEFAULT_RUNNER_URL = 'http://127.0.0.1:3100';
+function getRunnerUrl() {
+    return getConfig().runnerUrl ?? DEFAULT_RUNNER_URL;
+}
+/** Proxy a request to the runner and send the response via reply. */
+async function proxyToRunner(reply, path, method = 'GET') {
+    try {
+        const res = await fetch(`${getRunnerUrl()}${path}`, { method });
+        const text = await res.text();
+        void reply
+            .code(res.status)
+            .header('content-type', res.headers.get('content-type') ?? 'application/json')
+            .send(text);
+    }
+    catch {
+        void reply.code(502).send(JSON.stringify({ error: 'Runner unreachable' }));
+    }
+}
+// eslint-disable-next-line @typescript-eslint/require-await
+export const runnerRoutes = async (fastify) => {
+    fastify.addHook('preHandler', async (request, reply) => {
+        if (request.accessMode !== 'insider') {
+            return reply.code(403).send({ error: 'Insider access required' });
+        }
+    });
+    fastify.get('/api/runner/health', async (_req, reply) => {
+        await proxyToRunner(reply, '/health');
+    });
+    fastify.get('/api/runner/jobs', async (_req, reply) => {
+        await proxyToRunner(reply, '/jobs');
+    });
+    fastify.get('/api/runner/jobs/:id', async (req, reply) => {
+        await proxyToRunner(reply, `/jobs/${encodeURIComponent(req.params.id)}`);
+    });
+    fastify.get('/api/runner/jobs/:id/runs', async (req, reply) => {
+        const limit = req.query.limit ?? '20';
+        const id = encodeURIComponent(req.params.id);
+        await proxyToRunner(reply, `/jobs/${id}/runs?limit=${limit}`);
+    });
+    fastify.post('/api/runner/jobs/:id/run', async (req, reply) => {
+        await proxyToRunner(reply, `/jobs/${encodeURIComponent(req.params.id)}/run`, 'POST');
+    });
+    fastify.post('/api/runner/jobs/:id/enable', async (req, reply) => {
+        await proxyToRunner(reply, `/jobs/${encodeURIComponent(req.params.id)}/enable`, 'POST');
+    });
+    fastify.post('/api/runner/jobs/:id/disable', async (req, reply) => {
+        await proxyToRunner(reply, `/jobs/${encodeURIComponent(req.params.id)}/disable`, 'POST');
+    });
+    fastify.get('/api/runner/stats', async (_req, reply) => {
+        await proxyToRunner(reply, '/stats');
+    });
+};

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

@@ -0,0 +1,236 @@
+/**
+ * Search API route — proxies to jeeves-watcher for semantic search.
+ *
+ * Handles: POST /api/search
+ * Insider-only. Results filtered by insider's scope.
+ */
+import { stat } from 'node:fs/promises';
+import path from 'node:path';
+import picomatch from 'picomatch';
+import { getConfig } from '../../config/index.js';
+/** Check if a path passes the insider's scope rules. */
+function pathAllowedByScope(urlPath, scopes) {
+    if (!scopes)
+        return true; // null = unrestricted
+    const normalized = urlPath.toLowerCase().replace(/\/+$/, '');
+    const allowMatch = picomatch(scopes.allow.map((p) => p.toLowerCase().replace(/\/+$/, '')));
+    if (!allowMatch(normalized))
+        return false;
+    if (scopes.deny.length > 0) {
+        const denyMatch = picomatch(scopes.deny.map((p) => p.toLowerCase().replace(/\/+$/, '')));
+        if (denyMatch(normalized))
+            return false;
+    }
+    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) => {
+        // Insider-only
+        if (request.accessMode !== 'insider') {
+            return reply.code(403).send({ error: 'Insider access required' });
+        }
+        const config = getConfig();
+        if (!config.watcherUrl) {
+            return reply.code(501).send({ error: 'Search not configured' });
+        }
+        const { query, limit = 20, filter } = request.body;
+        if (!query || typeof query !== 'string') {
+            return reply.code(400).send({ error: 'query is required' });
+        }
+        const insiderScopes = request.insiderScopes;
+        const roots = config.roots ?? {};
+        // Over-fetch to account for scope filtering
+        const fetchLimit = Math.min(limit * 5, 200);
+        try {
+            const watcherRes = await fetch(`${config.watcherUrl}/search`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ query, limit: fetchLimit, filter }),
+            });
+            if (!watcherRes.ok) {
+                const msg = await watcherRes.text().catch(() => '');
+                return await reply
+                    .code(502)
+                    .send({ error: `Watcher search failed: ${msg}` });
+            }
+            const rawResults = (await watcherRes.json());
+            // Filter by insider scope and map paths
+            const permitted = [];
+            for (const r of rawResults) {
+                const fp = r.payload.file_path;
+                if (!fp)
+                    continue;
+                const browsePath = fsPathToBrowsePath(fp, roots);
+                if (!browsePath)
+                    continue;
+                // Check insider scope
+                const urlPath = `/${browsePath}`;
+                if (!pathAllowedByScope(urlPath, insiderScopes ?? null))
+                    continue;
+                permitted.push({ ...r, browsePath });
+            }
+            // Group by file path, take top `limit` files
+            const fileMap = new Map();
+            for (const r of permitted) {
+                const key = r.browsePath;
+                let group = fileMap.get(key);
+                if (!group) {
+                    const parts = key.split('/');
+                    group = {
+                        filePath: r.payload.file_path ?? key,
+                        browsePath: key,
+                        fileName: parts[parts.length - 1],
+                        bestScore: r.score,
+                        domains: Array.isArray(r.payload.domains)
+                            ? r.payload.domains
+                            : r.payload.domain
+                                ? [r.payload.domain]
+                                : [],
+                        title: r.payload.title,
+                        author: r.payload.author,
+                        participants: r.payload.participants,
+                        chunks: [],
+                    };
+                    fileMap.set(key, group);
+                }
+                if (r.score > group.bestScore)
+                    group.bestScore = r.score;
+                group.chunks.push({
+                    text: r.payload.chunk_text ?? '',
+                    index: r.payload.chunk_index ?? 0,
+                    score: r.score,
+                });
+            }
+            // Sort by best score, limit
+            const grouped = [...fileMap.values()]
+                .sort((a, b) => b.bestScore - a.bestScore)
+                .slice(0, limit);
+            // 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);
+                if (fsPath) {
+                    try {
+                        const s = await stat(fsPath);
+                        g.mtime = s.mtime.toISOString();
+                    }
+                    catch {
+                        /* file may not be accessible */
+                    }
+                }
+            }));
+            // Extract distinct metadata values for filter chips
+            const metadata = {
+                domains: [
+                    ...new Set(grouped.flatMap((g) => g.domains || []).filter(Boolean)),
+                ],
+                authors: [...new Set(grouped.map((g) => g.author).filter(Boolean))],
+                participants: [
+                    ...new Set(grouped.flatMap((g) => {
+                        try {
+                            const p = JSON.parse(g.participants ?? '[]');
+                            return Array.isArray(p) ? p : [];
+                        }
+                        catch {
+                            return g.participants ? [g.participants] : [];
+                        }
+                    })),
+                ].filter(Boolean),
+            };
+            return await reply.send({ results: grouped, metadata });
+        }
+        catch (err) {
+            return await reply
+                .code(502)
+                .send({ error: `Watcher unreachable: ${String(err)}` });
+        }
+    });
+    // Cached facets manifest
+    let facetsCache = null;
+    let facetsFetchPromise = null;
+    const FACETS_CACHE_TTL_MS = 60_000; // 1 minute
+    fastify.get('/api/search/facets', async (request, reply) => {
+        if (request.accessMode !== 'insider') {
+            return reply.code(403).send({ error: 'Insider access required' });
+        }
+        const config = getConfig();
+        if (!config.watcherUrl) {
+            return reply.code(501).send({ error: 'Search not configured' });
+        }
+        // Return cached if fresh
+        if (facetsCache &&
+            Date.now() - facetsCache.fetchedAt < FACETS_CACHE_TTL_MS) {
+            return reply.send(facetsCache.data);
+        }
+        try {
+            // Guard against cache stampede: reuse in-flight fetch
+            if (!facetsFetchPromise) {
+                const watcherUrl = config.watcherUrl;
+                facetsFetchPromise = (async () => {
+                    const watcherRes = await fetch(`${watcherUrl}/search/facets`, {
+                        signal: AbortSignal.timeout(5000),
+                    });
+                    if (!watcherRes.ok) {
+                        throw new Error(`HTTP ${String(watcherRes.status)}`);
+                    }
+                    const data = await watcherRes.json();
+                    facetsCache = { data, fetchedAt: Date.now() };
+                    return data;
+                })().finally(() => {
+                    facetsFetchPromise = null;
+                });
+            }
+            const data = await facetsFetchPromise;
+            return await reply.send(data);
+        }
+        catch (err) {
+            return await reply.code(502).send({
+                error: 'Failed to reach watcher',
+                detail: err instanceof Error ? err.message : String(err),
+            });
+        }
+    });
+};