@plebeiantech/lat.md 0.12.3-fork.2 → 0.12.3-fork.21

package/dist/src/view/server.js

@@ -1,20 +1,23 @@
+import { trustedLiveRequest, RESOURCE_CONTENT_SECURITY_POLICY, } from './request-security.js';
 import { readFile } from 'node:fs/promises';
-import { createServer } from 'node:http';
+import { randomUUID } from 'node:crypto';
 import { extname, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { ViewDocumentNotFoundError, ViewSourceNotFoundError, } from './repository.js';
+import { createLatServerApp, listenLatServer, } from '../../vendor/lat.md-server/index.js';
+import { plainStyler, } from '@plebeiantech/lat.md-core/context';
+import { sectionCommand } from '@plebeiantech/lat.md-core/cli/section';
+import { DEFAULT_VIEW_LOGO_TEXT, } from './protocol.js';
+import { ViewDocumentConflictError } from './document-edit.js';
+import { ViewExternalNotFoundError, ViewDocumentNotFoundError, ViewSourceNotFoundError, } from './repository.js';
 import { createViewSearch } from './search.js';
 import { createViewStore } from './store.js';
+import { rewriteClientAssetUrls } from './client-shell.js';
+import { documentResourcePath, documentPath, rawDocumentPath, validateDocumentRoutes, } from './document-route.js';
 const DEFAULT_HOST = '127.0.0.1';
+export const DEFAULT_VIEW_PORT = 4242;
+const MAX_DOCUMENT_EDIT_BODY_BYTES = 16 * 1024 * 1024;
+const MAX_DOCUMENT_CONTENT_LENGTH = 8 * 1024 * 1024;
 const defaultClientDir = fileURLToPath(new URL('./client/', import.meta.url));
-function documentUrl(path) {
-    return `/docs/${path.split('/').map(encodeURIComponent).join('/')}`;
-}
-function setSecurityHeaders(res) {
-    res.setHeader('Content-Security-Policy', "default-src 'self'; img-src 'self' data:; object-src 'none'; base-uri 'none'; frame-ancestors 'none'");
-    res.setHeader('Referrer-Policy', 'no-referrer');
-    res.setHeader('X-Content-Type-Options', 'nosniff');
-}
 function send(res, status, contentType, body, headOnly = false) {
     res.statusCode = status;
     res.setHeader('Content-Type', contentType);
@@ -25,6 +28,24 @@ function sendJson(res, status, value, headOnly) {
     res.setHeader('Cache-Control', 'no-store');
     send(res, status, 'application/json; charset=utf-8', JSON.stringify(value), headOnly);
 }
+async function readJsonBody(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const value of req) {
+        const chunk = Buffer.isBuffer(value) ? value : Buffer.from(value);
+        size += chunk.byteLength;
+        if (size > MAX_DOCUMENT_EDIT_BODY_BYTES) {
+            throw new RangeError('Document edit is too large');
+        }
+        chunks.push(chunk);
+    }
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    }
+    catch {
+        throw new SyntaxError('Document edit must be valid JSON');
+    }
+}
 function contentType(path) {
     switch (extname(path)) {
         case '.css':
@@ -35,8 +56,17 @@ function contentType(path) {
             return 'text/javascript; charset=utf-8';
         case '.json':
             return 'application/json; charset=utf-8';
+        case '.gif':
+            return 'image/gif';
+        case '.jpeg':
+        case '.jpg':
+            return 'image/jpeg';
+        case '.png':
+            return 'image/png';
         case '.svg':
             return 'image/svg+xml';
+        case '.webp':
+            return 'image/webp';
         case '.woff2':
             return 'font/woff2';
         default:
@@ -69,47 +99,94 @@ async function sendClientFile(res, path, headOnly, immutable = false) {
         send(res, 404, 'text/plain; charset=utf-8', 'Not found', headOnly);
     }
 }
-/** Start the read-only loopback server used by `lat ui`. */
-export async function startViewServer(ctx, options = {}) {
+async function sendClientShell(res, path, headOnly, entry) {
+    try {
+        const html = rewriteClientAssetUrls(await readFile(path, 'utf8'), '/');
+        const config = `<meta name="lat-live-entry" content="${encodeURIComponent(entry)}">`;
+        const body = html.includes('</head>')
+            ? html.replace('</head>', `${config}</head>`)
+            : `${config}${html}`;
+        res.setHeader('Cache-Control', 'no-cache');
+        send(res, 200, 'text/html; charset=utf-8', body, headOnly);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        send(res, 404, 'text/plain; charset=utf-8', 'Not found', headOnly);
+    }
+}
+/** Create the portable Express application used by live Lat UI servers. */
+export async function createViewApp(ctx, options = {}) {
     const host = options.host ?? DEFAULT_HOST;
     const clientDir = options.clientDir ?? defaultClientDir;
+    const logoText = options.logoText ?? DEFAULT_VIEW_LOGO_TEXT;
     const store = await createViewStore(ctx.latDir, ctx.projectRoot, {
         git: options.git,
+        gitPollMs: options.gitPollMs,
         watch: options.watch,
+        externalCa: options.externalCa,
     });
+    try {
+        validateDocumentRoutes(store.getIndex().files);
+    }
+    catch (error) {
+        await store.close();
+        throw error;
+    }
     const search = options.search ??
         createViewSearch(ctx.latDir, undefined, () => store.markdownGeneration);
     const eventClients = new Set();
+    const instanceId = randomUUID();
     const broadcastChange = (change) => {
-        const message = `event: change\ndata: ${JSON.stringify(change)}\n\n`;
+        const message = `event: change\ndata: ${JSON.stringify({ ...change, instanceId })}\n\n`;
         for (const client of eventClients)
             client.write(message);
     };
     const unsubscribeStore = store.subscribe(broadcastChange);
-    const server = createServer((req, res) => {
+    const heartbeat = setInterval(() => {
+        for (const client of eventClients)
+            client.write(': heartbeat\n\n');
+    }, 15_000);
+    heartbeat.unref();
+    const handleRequest = (req, res) => {
         void (async () => {
-            setSecurityHeaders(res);
+            if (!trustedLiveRequest(req, host)) {
+                send(res, 403, 'text/plain; charset=utf-8', 'Untrusted request origin or host');
+                return;
+            }
             const method = req.method ?? 'GET';
             const headOnly = method === 'HEAD';
-            if (method !== 'GET' && !headOnly) {
+            const url = new URL(req.url ?? '/', `http://${req.headers.host}`);
+            const documentEdit = method === 'PATCH' && url.pathname === '/api/document';
+            if (method !== 'GET' && !headOnly && !documentEdit) {
                 res.setHeader('Allow', 'GET, HEAD');
                 send(res, 405, 'text/plain; charset=utf-8', 'Method not allowed');
                 return;
             }
-            const url = new URL(req.url ?? '/', `http://${host}`);
             if (url.pathname === '/') {
                 const entry = store.getIndex().entry;
                 if (!entry) {
                     send(res, 404, 'text/plain; charset=utf-8', 'No Markdown files found');
                     return;
                 }
-                res.statusCode = 302;
-                res.setHeader('Location', documentUrl(entry));
+                await sendClientShell(res, join(clientDir, 'index.html'), headOnly, entry);
+                return;
+            }
+            const index = store.getIndex();
+            const routePath = url.pathname.replace(/\/$/, '');
+            const markdownPath = documentPath(routePath);
+            if (markdownPath === index.entry) {
+                res.statusCode = 308;
+                res.setHeader('Location', `/${url.search}`);
                 res.end();
                 return;
             }
             if (url.pathname === '/api/index') {
-                sendJson(res, 200, store.getIndex(), headOnly);
+                sendJson(res, 200, { ...store.getIndex(), logoText }, headOnly);
+                return;
+            }
+            if (url.pathname === '/api/graph') {
+                sendJson(res, 200, store.getGraph(), headOnly);
                 return;
             }
             if (url.pathname === '/api/events') {
@@ -123,12 +200,52 @@ export async function startViewServer(ctx, options = {}) {
                     return;
                 }
                 eventClients.add(res);
-                res.write(`event: ready\ndata: ${JSON.stringify({ generation: store.snapshot.generation, markdownGeneration: store.markdownGeneration })}\n\n`);
+                res.write(`retry: 1000\nevent: ready\ndata: ${JSON.stringify({ instanceId, generation: store.snapshot.generation, markdownGeneration: store.markdownGeneration })}\n\n`);
                 req.once('close', () => eventClients.delete(res));
                 return;
             }
             if (url.pathname === '/api/document') {
                 const path = url.searchParams.get('path') ?? '';
+                if (documentEdit) {
+                    let body;
+                    try {
+                        body = await readJsonBody(req);
+                    }
+                    catch (error) {
+                        sendJson(res, error instanceof RangeError ? 413 : 400, { error: error.message }, false);
+                        return;
+                    }
+                    if (!body ||
+                        typeof body !== 'object' ||
+                        typeof body.baseContent !==
+                            'string' ||
+                        typeof body.content !==
+                            'string') {
+                        sendJson(res, 400, {
+                            error: 'Document edit content is required',
+                        }, false);
+                        return;
+                    }
+                    const edit = body;
+                    if (edit.baseContent.length > MAX_DOCUMENT_CONTENT_LENGTH ||
+                        edit.content.length > MAX_DOCUMENT_CONTENT_LENGTH) {
+                        sendJson(res, 413, { error: 'Document edit is too large' }, false);
+                        return;
+                    }
+                    try {
+                        sendJson(res, 200, await store.editDocument(path, edit.baseContent, edit.content), false);
+                    }
+                    catch (error) {
+                        if (error instanceof ViewDocumentConflictError) {
+                            sendJson(res, 409, { error: error.message }, false);
+                            return;
+                        }
+                        if (!(error instanceof ViewDocumentNotFoundError))
+                            throw error;
+                        sendJson(res, 404, { error: error.message }, false);
+                    }
+                    return;
+                }
                 try {
                     sendJson(res, 200, await store.getDocument(path), headOnly);
                 }
@@ -139,6 +256,18 @@ export async function startViewServer(ctx, options = {}) {
                 }
                 return;
             }
+            if (url.pathname === '/api/document-source') {
+                const path = url.searchParams.get('path') ?? '';
+                try {
+                    sendJson(res, 200, await store.getDocumentSource(path), headOnly);
+                }
+                catch (error) {
+                    if (!(error instanceof ViewDocumentNotFoundError))
+                        throw error;
+                    sendJson(res, 404, { error: error.message }, headOnly);
+                }
+                return;
+            }
             if (url.pathname === '/api/search') {
                 const query = (url.searchParams.get('query') ?? '').trim();
                 if (query.length > 500) {
@@ -148,6 +277,30 @@ export async function startViewServer(ctx, options = {}) {
                 sendJson(res, 200, await search(query), headOnly);
                 return;
             }
+            if (url.pathname === '/api/section') {
+                const query = (url.searchParams.get('query') ?? '').trim();
+                if (!query) {
+                    sendJson(res, 400, { error: 'Section ID is required' }, headOnly);
+                    return;
+                }
+                if (query.length > 1_000) {
+                    sendJson(res, 400, { error: 'Section ID is too long' }, headOnly);
+                    return;
+                }
+                const result = await sectionCommand({
+                    latDir: ctx.latDir,
+                    projectRoot: ctx.projectRoot,
+                    styler: plainStyler,
+                    mode: 'cli',
+                }, query);
+                const tree = await store.renderSectionOutput(result.output, query);
+                sendJson(res, 200, {
+                    output: result.output,
+                    tree,
+                    isError: result.isError === true,
+                }, headOnly);
+                return;
+            }
             if (url.pathname === '/api/source') {
                 const path = url.searchParams.get('path') ?? '';
                 const symbol = url.searchParams.get('symbol') ?? '';
@@ -170,6 +323,18 @@ export async function startViewServer(ctx, options = {}) {
                 }
                 return;
             }
+            if (url.pathname === '/api/external') {
+                const target = url.searchParams.get('target') ?? '';
+                try {
+                    sendJson(res, 200, await store.getExternal(target), headOnly);
+                }
+                catch (error) {
+                    if (!(error instanceof ViewExternalNotFoundError))
+                        throw error;
+                    sendJson(res, 404, { error: error.message }, headOnly);
+                }
+                return;
+            }
             if (url.pathname.startsWith('/assets/')) {
                 const path = clientPath(clientDir, url.pathname);
                 if (!path) {
@@ -179,10 +344,45 @@ export async function startViewServer(ctx, options = {}) {
                 await sendClientFile(res, path, headOnly, true);
                 return;
             }
+            const rawMarkdownPath = rawDocumentPath(url.pathname);
+            if (rawMarkdownPath) {
+                try {
+                    const source = await store.getDocumentSource(rawMarkdownPath);
+                    res.setHeader('Cache-Control', 'no-cache');
+                    send(res, 200, 'text/markdown; charset=utf-8', source.content, headOnly);
+                }
+                catch (error) {
+                    if (!(error instanceof ViewDocumentNotFoundError))
+                        throw error;
+                    send(res, 404, 'text/plain; charset=utf-8', error.message, headOnly);
+                }
+                return;
+            }
+            const resourcePath = documentResourcePath(url.pathname);
+            if (resourcePath) {
+                try {
+                    const body = await store.getDocumentResource(resourcePath);
+                    res.setHeader('Cache-Control', 'no-cache');
+                    res.setHeader('Content-Security-Policy', RESOURCE_CONTENT_SECURITY_POLICY);
+                    res.setHeader('Cross-Origin-Resource-Policy', 'same-origin');
+                    if (/\.(?:html?|xhtml|xml|[cm]?js)$/i.test(resourcePath)) {
+                        res.setHeader('Content-Disposition', 'attachment');
+                    }
+                    send(res, 200, contentType(resourcePath), body, headOnly);
+                }
+                catch (error) {
+                    if (!(error instanceof ViewDocumentNotFoundError))
+                        throw error;
+                    send(res, 404, 'text/plain; charset=utf-8', error.message, headOnly);
+                }
+                return;
+            }
             if (url.pathname === '/search' ||
-                url.pathname.startsWith('/docs/') ||
-                url.pathname.startsWith('/code/')) {
-                await sendClientFile(res, join(clientDir, 'index.html'), headOnly);
+                url.pathname === '/graph' ||
+                (markdownPath !== null && index.files.includes(markdownPath)) ||
+                url.pathname.startsWith('/code/') ||
+                url.pathname.startsWith('/external/')) {
+                await sendClientShell(res, join(clientDir, 'index.html'), headOnly, index.entry);
                 return;
             }
             send(res, 404, 'text/plain; charset=utf-8', 'Not found', headOnly);
@@ -193,41 +393,44 @@ export async function startViewServer(ctx, options = {}) {
             }
             sendJson(res, 500, { error: error.message }, false);
         });
-    });
-    try {
-        await new Promise((resolveListen, reject) => {
-            server.once('error', reject);
-            server.listen(options.port ?? 0, host, () => {
-                server.off('error', reject);
-                resolveListen();
-            });
-        });
-    }
-    catch (error) {
-        unsubscribeStore();
-        await store.close();
-        throw error;
-    }
-    const address = server.address();
-    if (!address || typeof address === 'string') {
-        await new Promise((resolveClose) => server.close(() => resolveClose()));
-        unsubscribeStore();
-        await store.close();
-        throw new Error('Could not determine lat ui server address');
-    }
+    };
+    const app = createLatServerApp({ handle: handleRequest });
     return {
-        server,
+        app,
         store,
-        url: `http://${host}:${address.port}/`,
         close: async () => {
+            clearInterval(heartbeat);
             unsubscribeStore();
             for (const client of eventClients)
                 client.end();
             eventClients.clear();
             await store.close();
-            await new Promise((resolveClose, reject) => {
-                server.close((error) => (error ? reject(error) : resolveClose()));
-            });
+        },
+    };
+}
+/** Start the loopback server used by `lat ui`. */
+export async function startViewServer(ctx, options = {}) {
+    const host = options.host ?? DEFAULT_HOST;
+    const view = await createViewApp(ctx, options);
+    let running;
+    try {
+        const requestedPort = options.port;
+        running = await listenLatServer(view.app, {
+            host,
+            port: requestedPort ?? DEFAULT_VIEW_PORT,
+            findAvailablePort: requestedPort === undefined,
+        });
+    }
+    catch (error) {
+        await view.close();
+        throw error;
+    }
+    return {
+        server: running.server,
+        store: view.store,
+        url: running.url,
+        close: async () => {
+            await Promise.all([running.close(), view.close()]);
         },
     };
 }

package/dist/src/view/source-target.d.ts

@@ -0,0 +1,10 @@
+/** Resolve ordinary code links relative to their Markdown file, not the vault root. */
+export declare function rewriteLocalFileLink(value: string, sourcePath: string): string;
+export type ViewSourceTarget = {
+    path: string;
+    symbol: string;
+    key: string;
+    fileKey: string;
+};
+/** Normalize a supported source wiki-link target for view indexes and routes. */
+export declare function viewSourceTarget(target: string): ViewSourceTarget | null;

package/dist/src/view/source-target.js

@@ -0,0 +1,43 @@
+import { extname } from 'node:path';
+import { normalizeRepositoryPath } from '@plebeiantech/lat.md-core/repository-path';
+import { isSourceFileExtension } from '@plebeiantech/lat.md-core/source-formats';
+import { rewriteDocumentLink } from './document-route.js';
+/** Resolve ordinary code links relative to their Markdown file, not the vault root. */
+export function rewriteLocalFileLink(value, sourcePath) {
+    if (value && !/^(?:[#/]|[a-z][a-z\d+.-]*:)/i.test(value)) {
+        try {
+            // Keep a project prefix so URL normalization cannot silently clamp an
+            // escaping relative path back into the project.
+            const base = sourcePath.split('/').map(encodeURIComponent).join('/');
+            const url = new URL(value, `http://lat.local/project/lat.md/${base}`);
+            if (url.origin === 'http://lat.local' &&
+                url.pathname.startsWith('/project/')) {
+                const path = decodeURIComponent(url.pathname.slice('/project/'.length));
+                if (normalizeRepositoryPath(path) &&
+                    (!path.startsWith('lat.md/') || isSourceFileExtension(extname(path)))) {
+                    return `/code/${path.split('/').map(encodeURIComponent).join('/')}${url.search}${url.hash}`;
+                }
+            }
+        }
+        catch {
+            // Malformed URLs retain the ordinary document/resource fallback.
+        }
+    }
+    return rewriteDocumentLink(value, sourcePath);
+}
+/** Normalize a supported source wiki-link target for view indexes and routes. */
+export function viewSourceTarget(target) {
+    const hash = target.indexOf('#');
+    const authoredPath = hash === -1 ? target : target.slice(0, hash);
+    const path = normalizeRepositoryPath(authoredPath);
+    if (!path || !isSourceFileExtension(extname(path)))
+        return null;
+    const symbol = hash === -1 ? '' : target.slice(hash + 1);
+    const fileKey = path.toLowerCase();
+    return {
+        path,
+        symbol,
+        key: `${fileKey}${symbol ? `#${symbol.toLowerCase()}` : ''}`,
+        fileKey,
+    };
+}

package/dist/src/view/static-build.d.ts

@@ -0,0 +1,32 @@
+import { rename } from 'node:fs/promises';
+import type { CmdContext } from '@plebeiantech/lat.md-core/context';
+export type StaticViewBuildOptions = {
+    basePath?: string;
+    clientDir?: string;
+    codeExcludePaths?: string[];
+    force?: boolean;
+    logoText?: string;
+    externalCa?: string | Buffer;
+    searchApi?: string;
+};
+export type StaticViewBuildResult = {
+    documents: number;
+    outputDir: string;
+    sources: number;
+};
+export declare function normalizeStaticViewBasePath(value: string): string;
+/** Convert a live view route to its physical static-directory URL. */
+export declare function staticViewUrl(value: string, basePath: string, entryPath?: string): string;
+/** Refuse build targets that exist or could replace the project itself. */
+export declare function validateViewBuildOutput(outputDir: string, projectRoot: string, kind?: string, force?: boolean): Promise<void>;
+type ViewBuildMoveDependencies = {
+    move: typeof rename;
+    wait: (milliseconds: number) => Promise<void>;
+};
+/** Commit a staged build after transient filesystem locks have cleared. */
+export declare function moveViewBuildOutput(stagingDir: string, outputDir: string, dependencies?: ViewBuildMoveDependencies): Promise<void>;
+/** Remove abandoned staging after transient filesystem locks have cleared. */
+export declare function removeViewBuildStaging(stagingDir: string): Promise<void>;
+/** Build a serverless snapshot of the current read-only Lat UI. */
+export declare function buildStaticView(ctx: CmdContext, requestedOutput: string, options?: StaticViewBuildOptions): Promise<StaticViewBuildResult>;
+export {};