@plebeiantech/lat.md 0.12.3-fork.13 → 0.12.3-fork.15

package/dist/src/view/static-build.js

@@ -2,10 +2,13 @@ import { createHash } from 'node:crypto';
 import { cp, lstat, mkdir, mkdtemp, readFile, rename, rm, writeFile, } from 'node:fs/promises';
 import { dirname, join, parse, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { isDocumentPath } from '../document-formats.js';
 import { DEFAULT_VIEW_LOGO_TEXT } from './protocol.js';
+import { documentTreeUrls, rewriteDocumentTreeUrls } from './document-tree.js';
 import { viewStaticSourceKey, } from './static-protocol.js';
 import { createViewStore } from './store.js';
-const BUILD_MARKER = '.lat-ui-build';
+import { rewriteClientAssetUrls } from './client-shell.js';
+import { documentResourcePath, documentPath, documentUrl, rawDocumentPath, } from './document-route.js';
 const defaultClientDir = fileURLToPath(new URL('./client/', import.meta.url));
 function isInside(parent, child) {
     const rel = relative(parent, child);
@@ -56,7 +59,16 @@ export function staticViewUrl(value, basePath) {
     }
     if (url.origin !== 'http://lat.local')
         return value;
-    for (const prefix of ['/docs/', '/code/']) {
+    if (url.pathname.startsWith('/docs/')) {
+        const route = url.pathname.slice(1).replace(/\/+$/, '');
+        const suffix = `${url.search}${url.hash}`;
+        return `${basePath}${route}${suffix}`;
+    }
+    if (url.pathname.startsWith('/resources/')) {
+        const route = url.pathname.slice(1);
+        return `${basePath}${route}${url.search}${url.hash}`;
+    }
+    for (const prefix of ['/code/', '/external/']) {
         if (!url.pathname.startsWith(prefix))
             continue;
         const route = url.pathname.slice(1).replace(/\/+$/, '');
@@ -68,18 +80,7 @@ export function staticViewUrl(value, basePath) {
     return value;
 }
 function documentPathFromUrl(value) {
-    if (!value.pathname.startsWith('/docs/'))
-        return null;
-    try {
-        return value.pathname
-            .slice('/docs/'.length)
-            .split('/')
-            .map(decodeURIComponent)
-            .join('/');
-    }
-    catch {
-        return null;
-    }
+    return documentPath(value.pathname) ?? rawDocumentPath(value.pathname);
 }
 function rewriteHtmlLink(value, basePath, sourcePath, documentPaths) {
     const direct = staticViewUrl(value, basePath);
@@ -87,32 +88,37 @@ function rewriteHtmlLink(value, basePath, sourcePath, documentPaths) {
         return direct;
     let resolved;
     try {
-        const currentPath = sourcePath.split('/').map(encodeURIComponent).join('/');
-        resolved = new URL(decodeHtmlUrlAttribute(value), `http://lat.local/docs/${currentPath}`);
+        const externalAt = sourcePath.indexOf(':');
+        const currentRoute = externalAt > 0 && !documentPaths.has(sourcePath)
+            ? `/external/${encodeURIComponent(sourcePath.slice(0, externalAt))}/${sourcePath
+                .slice(externalAt + 1)
+                .split('/')
+                .map(encodeURIComponent)
+                .join('/')}`
+            : documentUrl(sourcePath);
+        resolved = new URL(decodeHtmlUrlAttribute(value), `http://lat.local${currentRoute}`);
     }
     catch {
         return value;
     }
     const documentPath = documentPathFromUrl(resolved);
+    if (resolved.pathname.startsWith('/external/')) {
+        return staticViewUrl(`${resolved.pathname}${resolved.search}${resolved.hash}`, basePath);
+    }
     if (resolved.origin !== 'http://lat.local' ||
         !documentPath ||
         !documentPaths.has(documentPath)) {
         return value;
     }
-    return staticViewUrl(`${resolved.pathname}${resolved.search}${resolved.hash}`, basePath);
+    return staticViewUrl(`${documentUrl(documentPath)}${resolved.search}${resolved.hash}`, basePath);
 }
-function rewriteHtmlLinks(html, basePath, sourcePath, documentPaths) {
-    return html.replace(/href="([^"]*)"/g, (attribute, value) => {
-        const rewritten = rewriteHtmlLink(value, basePath, sourcePath, documentPaths);
-        if (rewritten === value)
-            return attribute;
-        return `href="${rewritten.replaceAll('&', '&').replaceAll('"', '"')}"`;
-    });
+function rewriteDocumentLinks(tree, basePath, sourcePath, documentPaths) {
+    return rewriteDocumentTreeUrls(tree, (value) => rewriteHtmlLink(value, basePath, sourcePath, documentPaths));
 }
 function rewriteMarkdownReference(reference, basePath, sourcePath, documentPaths) {
     return {
         ...reference,
-        paragraphHtml: rewriteHtmlLinks(reference.paragraphHtml, basePath, sourcePath, documentPaths),
+        paragraphTree: rewriteDocumentLinks(reference.paragraphTree, basePath, sourcePath, documentPaths),
         url: staticViewUrl(reference.url, basePath),
     };
 }
@@ -124,8 +130,8 @@ function rewriteBackReference(reference, basePath, sectionPaths, documentPaths)
 function rewriteDocument(document, basePath, sectionPaths, documentPaths) {
     return {
         ...document,
-        html: rewriteHtmlLinks(document.html, basePath, document.path, documentPaths),
-        gitHtml: null,
+        tree: rewriteDocumentLinks(document.tree, basePath, document.path, documentPaths),
+        gitTree: null,
         backReferences: document.backReferences.map((section) => ({
             ...section,
             references: section.references.map((reference) => rewriteBackReference(reference, basePath, sectionPaths, documentPaths)),
@@ -136,7 +142,7 @@ function rewriteSourceReference(reference, basePath, sectionPaths, documentPaths
     const sectionPath = reference.sectionId.split('#', 1)[0];
     return {
         ...reference,
-        paragraphHtml: rewriteHtmlLinks(reference.paragraphHtml, basePath, sectionPaths.get(sectionPath) ?? null, documentPaths),
+        paragraphTree: rewriteDocumentLinks(reference.paragraphTree, basePath, sectionPaths.get(sectionPath) ?? null, documentPaths),
         url: staticViewUrl(reference.url, basePath),
     };
 }
@@ -187,21 +193,103 @@ function sourceRequest(value) {
         at: positiveInteger(url.searchParams.get('at')),
     };
 }
+function externalRequest(value, external) {
+    let url;
+    try {
+        url = new URL(decodeHtmlUrlAttribute(value), 'http://lat.local');
+    }
+    catch {
+        return null;
+    }
+    if (!url.pathname.startsWith('/external/'))
+        return null;
+    try {
+        const parts = url.pathname
+            .slice('/external/'.length)
+            .split('/')
+            .map(decodeURIComponent);
+        const handle = parts.shift() ?? '';
+        const path = parts.join('/');
+        if (!handle || !path)
+            return null;
+        const fragment = decodeURIComponent(url.hash.slice(1));
+        const target = `${handle}:${path}${fragment ? `#${fragment}` : ''}`;
+        const parsed = external?.parse(target);
+        if (parsed) {
+            if (!isDocumentPath(parsed.resolvedPath)) {
+                return parsed.identity;
+            }
+            const hash = parsed.identity.indexOf('#');
+            return hash === -1 ? parsed.identity : parsed.identity.slice(0, hash);
+        }
+        return `${handle}:${path}${isDocumentPath(path) || !fragment ? '' : `#${fragment}`}`;
+    }
+    catch {
+        return null;
+    }
+}
+function externalRequestsFromDocument(document, requests, external, externalBase) {
+    const add = (value) => {
+        let candidate = value;
+        if (externalBase && !value.startsWith('#')) {
+            try {
+                const colon = externalBase.indexOf(':');
+                const base = `/external/${encodeURIComponent(externalBase.slice(0, colon))}/${externalBase
+                    .slice(colon + 1)
+                    .split('/')
+                    .map(encodeURIComponent)
+                    .join('/')}`;
+                const resolved = new URL(decodeHtmlUrlAttribute(value), `http://lat.local${base}`);
+                if (resolved.origin === 'http://lat.local') {
+                    candidate = `${resolved.pathname}${resolved.hash}`;
+                }
+            }
+            catch {
+                // Leave malformed links to the renderer rather than exporting them.
+            }
+        }
+        const request = externalRequest(candidate, external);
+        if (request)
+            requests.add(request);
+    };
+    for (const value of documentTreeUrls(document.tree))
+        add(value);
+    for (const section of document.backReferences) {
+        for (const reference of section.references) {
+            add(reference.url);
+            if (reference.kind === 'markdown') {
+                for (const value of documentTreeUrls(reference.paragraphTree))
+                    add(value);
+            }
+        }
+    }
+}
+function externalRequestsFromSource(source, requests, external) {
+    for (const reference of [
+        ...(source.context ? [source.context] : []),
+        ...source.otherReferences,
+    ]) {
+        for (const value of documentTreeUrls(reference.paragraphTree)) {
+            const request = externalRequest(value, external);
+            if (request)
+                requests.add(request);
+        }
+    }
+}
 function sourceRequestsFromDocument(document, requests) {
     const add = (value) => {
         const request = sourceRequest(value);
         if (request)
             requests.set(viewStaticSourceKey(request), request);
     };
-    for (const match of document.html.matchAll(/href="([^"]*)"/g))
-        add(match[1]);
+    for (const value of documentTreeUrls(document.tree))
+        add(value);
     for (const section of document.backReferences) {
         for (const reference of section.references) {
             add(reference.url);
             if (reference.kind === 'markdown') {
-                for (const match of reference.paragraphHtml.matchAll(/href="([^"]*)"/g)) {
-                    add(match[1]);
-                }
+                for (const value of documentTreeUrls(reference.paragraphTree))
+                    add(value);
             }
         }
     }
@@ -212,8 +300,8 @@ function sourceRequestsFromSource(source, requests) {
         ...source.otherReferences,
     ];
     for (const reference of references) {
-        for (const match of reference.paragraphHtml.matchAll(/href="([^"]*)"/g)) {
-            const request = sourceRequest(match[1]);
+        for (const value of documentTreeUrls(reference.paragraphTree)) {
+            const request = sourceRequest(value);
             if (request)
                 requests.set(viewStaticSourceKey(request), request);
         }
@@ -256,7 +344,7 @@ function sectionDocumentPaths(documents) {
     return result;
 }
 function clientShell(html, basePath) {
-    const assets = html.replace(/(["'])\/assets\//g, (_match, quote) => `${quote}${basePath}assets/`);
+    const assets = rewriteClientAssetUrls(html, basePath);
     const configValue = JSON.stringify({ basePath }).replaceAll('<', '\\u003c');
     const config = `<script>globalThis.__LAT_STATIC_VIEW__=${configValue}</script>`;
     return assets.includes('</head>')
@@ -295,6 +383,8 @@ export async function buildStaticView(ctx, requestedOutput, options = {}) {
         codeExcludePaths: [outputDir],
         git: false,
         watch: false,
+        externalIgnoreLocal: true,
+        externalCa: options.externalCa,
     });
     try {
         const clientHtml = await readFile(join(clientDir, 'index.html'), 'utf8');
@@ -304,11 +394,31 @@ export async function buildStaticView(ctx, requestedOutput, options = {}) {
         const shell = clientShell(clientHtml, basePath);
         const index = { ...store.getIndex(), git: null, logoText };
         const documents = new Map();
+        const documentResources = new Set();
         const sourceRequests = new Map();
+        const externalRequests = new Set();
+        for (const file of index.externalFiles) {
+            externalRequests.add(file.target);
+        }
         for (const path of index.files) {
             const document = await store.getDocument(path);
             documents.set(path, document);
+            for (const url of documentTreeUrls(document.tree)) {
+                let parsed;
+                try {
+                    parsed = new URL(url, 'http://lat.local');
+                }
+                catch {
+                    continue;
+                }
+                if (parsed.origin !== 'http://lat.local')
+                    continue;
+                const resourcePath = documentResourcePath(parsed.pathname);
+                if (resourcePath)
+                    documentResources.add(resourcePath);
+            }
             sourceRequestsFromDocument(document, sourceRequests);
+            externalRequestsFromDocument(document, externalRequests, store.snapshot.external);
         }
         const documentPaths = new Set(documents.keys());
         const sectionPaths = sectionDocumentPaths(documents);
@@ -317,6 +427,39 @@ export async function buildStaticView(ctx, requestedOutput, options = {}) {
             const request = sourceRequest(node.url);
             if (request)
                 sourceRequests.set(viewStaticSourceKey(request), request);
+            if (node.externalTarget)
+                externalRequests.add(node.externalTarget);
+        }
+        const externals = new Map();
+        const pendingExternal = [...externalRequests];
+        for (let index = 0; index < pendingExternal.length; index++) {
+            const target = pendingExternal[index];
+            if (externals.has(target))
+                continue;
+            let external;
+            try {
+                external = await store.getExternal(target);
+            }
+            catch (error) {
+                throw new Error(`Could not export external source ${target}: ${error.message}`);
+            }
+            externals.set(target, external);
+            const before = externalRequests.size;
+            if (external.kind === 'markdown') {
+                sourceRequestsFromDocument(external.document, sourceRequests);
+                externalRequestsFromDocument(external.document, externalRequests, store.snapshot.external, external.document.path);
+            }
+            else {
+                sourceRequestsFromSource(external.source, sourceRequests);
+                externalRequestsFromSource(external.source, externalRequests, store.snapshot.external);
+            }
+            if (externalRequests.size > before) {
+                for (const next of externalRequests) {
+                    if (!externals.has(next) && !pendingExternal.includes(next)) {
+                        pendingExternal.push(next);
+                    }
+                }
+            }
         }
         const sources = new Map();
         const pending = [...sourceRequests.keys()];
@@ -352,19 +495,36 @@ export async function buildStaticView(ctx, requestedOutput, options = {}) {
             graph: 'data/graph.json',
             documents: {},
             sources: {},
+            externals: {},
         };
         await writeJson(join(payloadDir, manifest.graph), rewriteGraph(graph, basePath));
         for (const [path, document] of documents) {
             const dataPath = dataFile('documents', path);
             manifest.documents[path] = dataPath;
             await writeJson(join(payloadDir, dataPath), rewriteDocument(document, basePath, sectionPaths, documentPaths));
-            const route = `docs/${path}`;
+            const source = await store.getDocumentSource(path);
+            const rawPath = join(payloadDir, 'docs', ...path.split('/'));
+            await mkdir(dirname(rawPath), { recursive: true });
+            await writeFile(rawPath, source.content);
+            const route = `docs/${path.slice(0, -'.md'.length)}`;
             await writeRouteShell(payloadDir, route, shell);
         }
+        for (const path of [...documentResources].sort()) {
+            let content;
+            try {
+                content = await store.getDocumentResource(path);
+            }
+            catch (error) {
+                throw new Error(`Could not export document resource ${path}: ${error.message}`);
+            }
+            const outputPath = join(payloadDir, 'resources', ...path.split('/'));
+            await mkdir(dirname(outputPath), { recursive: true });
+            await writeFile(outputPath, content);
+        }
         const sourceFiles = new Map();
         for (const [key, source] of sources) {
             const rewritten = rewriteSource(source, basePath, sectionPaths, documentPaths);
-            const { path, content, highlightedHtmlLines, ...view } = rewritten;
+            const { path, content, highlightedLines, ...view } = rewritten;
             let fileDataPath = sourceFiles.get(path);
             if (!fileDataPath) {
                 fileDataPath = dataFile('source-files', path);
@@ -372,7 +532,7 @@ export async function buildStaticView(ctx, requestedOutput, options = {}) {
                 await writeJson(join(payloadDir, fileDataPath), {
                     path,
                     content,
-                    highlightedHtmlLines,
+                    highlightedLines,
                 });
             }
             const viewDataPath = dataFile('source-views', key);
@@ -383,19 +543,62 @@ export async function buildStaticView(ctx, requestedOutput, options = {}) {
             const route = `code/${path}`;
             await writeRouteShell(payloadDir, route, shell);
         }
+        const externalSourceFiles = new Map();
+        const externalRoutes = new Set();
+        for (const [target, external] of externals) {
+            if (external.kind === 'markdown') {
+                const dataPath = dataFile('external-documents', target);
+                manifest.externals[target] = { kind: 'markdown', document: dataPath };
+                await writeJson(join(payloadDir, dataPath), {
+                    ...external,
+                    document: rewriteDocument(external.document, basePath, sectionPaths, documentPaths),
+                });
+                const colon = external.document.path.indexOf(':');
+                externalRoutes.add(`external/${external.document.path.slice(0, colon)}/${external.document.path.slice(colon + 1)}`);
+                continue;
+            }
+            const rewritten = rewriteSource(external.source, basePath, sectionPaths, documentPaths);
+            const { path, content, highlightedLines, ...sourceView } = rewritten;
+            let fileDataPath = externalSourceFiles.get(path);
+            if (!fileDataPath) {
+                fileDataPath = dataFile('external-source-files', path);
+                externalSourceFiles.set(path, fileDataPath);
+                await writeJson(join(payloadDir, fileDataPath), {
+                    path,
+                    content,
+                    highlightedLines,
+                });
+            }
+            const viewDataPath = dataFile('external-source-views', target);
+            manifest.externals[target] = {
+                kind: 'source',
+                file: fileDataPath,
+                view: viewDataPath,
+            };
+            const view = {
+                kind: 'source',
+                target: external.target,
+                source: sourceView,
+            };
+            await writeJson(join(payloadDir, viewDataPath), view);
+            const colon = path.indexOf(':');
+            externalRoutes.add(`external/${path.slice(0, colon)}/${path.slice(colon + 1)}`);
+        }
+        for (const route of externalRoutes) {
+            await writeRouteShell(payloadDir, route, shell);
+        }
         await writeRouteShell(payloadDir, 'graph', shell);
         await writeJson(join(payloadDir, 'data/manifest.json'), manifest);
-        const entryRedirect = redirectShell(staticViewUrl(`/docs/${index.entry}`, basePath));
+        const entryRedirect = redirectShell(staticViewUrl(documentUrl(index.entry), basePath));
         await writeFile(join(payloadDir, 'index.html'), entryRedirect);
         if (payloadDir !== stagingDir) {
             await writeFile(join(stagingDir, 'index.html'), entryRedirect);
         }
-        await writeFile(join(stagingDir, BUILD_MARKER), `${JSON.stringify({ version: 1 })}\n`);
         await rename(stagingDir, outputDir);
         return {
             documents: documents.size,
             outputDir,
-            sources: sources.size,
+            sources: sources.size + externals.size,
         };
     }
     catch (error) {

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

@@ -1,4 +1,4 @@
-import type { ViewIndex, ViewSourceDocument } from './protocol.js';
+import type { ViewExternalDocument, ViewIndex, ViewSourceDocument } from './protocol.js';
 export type ViewStaticSourceRequest = {
     path: string;
     symbol: string;
@@ -6,18 +6,35 @@ export type ViewStaticSourceRequest = {
     line: number;
     at: number;
 };
-export type ViewStaticSourceFile = Pick<ViewSourceDocument, 'path' | 'content' | 'highlightedHtmlLines'>;
+export type ViewStaticSourceFile = Pick<ViewSourceDocument, 'path' | 'content' | 'highlightedLines'>;
 export type ViewStaticSourceView = Omit<ViewSourceDocument, keyof ViewStaticSourceFile>;
 export type ViewStaticSourceEntry = {
     file: string;
     view: string;
 };
+export type ViewStaticExternalEntry = {
+    kind: 'markdown';
+    document: string;
+} | {
+    kind: 'source';
+    file: string;
+    view: string;
+};
+export type ViewStaticExternalSourceView = {
+    kind: 'source';
+    target: string;
+    source: ViewStaticSourceView;
+};
+export type ViewStaticExternalMarkdown = Extract<ViewExternalDocument, {
+    kind: 'markdown';
+}>;
 export type ViewStaticManifest = {
     version: 1;
     index: ViewIndex;
     graph: string;
     documents: Record<string, string>;
     sources: Record<string, ViewStaticSourceEntry>;
+    externals: Record<string, ViewStaticExternalEntry>;
 };
 /** Stable lookup key shared by the static exporter and browser adapter. */
 export declare function viewStaticSourceKey(request: ViewStaticSourceRequest): string;

package/dist/src/view/store.d.ts

@@ -1,6 +1,7 @@
-import { type Section } from '../lattice.js';
+import { type ExternalResolver } from '../external-sources.js';
+import type { Section } from '../lattice-model.js';
 import { type ViewGitRepository, type ViewGitSnapshot } from './git.js';
-import type { ViewDocument, ViewDocumentError, ViewGraph, ViewIndex, ViewProjectChange, ViewSourceDocument } from './protocol.js';
+import type { ViewDocument, ViewDocumentEditResponse, ViewDocumentError, ViewDocumentSource, ViewExternalDocument, ViewGraph, ViewIndex, ViewProjectGeneration, ViewDocumentTree, ViewSourceDocument } from './protocol.js';
 import { type ViewCodeReferenceFile, type ViewParsedMarkdownFile, type ViewReferenceIndex } from './references.js';
 export type ViewProjectSnapshot = {
     generation: number;
@@ -12,6 +13,7 @@ export type ViewProjectSnapshot = {
     diagnostics: ReadonlyMap<string, readonly ViewDocumentError[]>;
     git: ViewGitSnapshot;
     index: ViewIndex;
+    external: ExternalResolver;
 };
 export type ViewStoreOptions = {
     codeExcludePaths?: string[];
@@ -19,8 +21,10 @@ export type ViewStoreOptions = {
     git?: boolean;
     gitPollMs?: number;
     watch?: boolean;
+    externalIgnoreLocal?: boolean;
+    externalCa?: string | Buffer;
 };
-type ViewStoreListener = (change: ViewProjectChange) => void;
+type ViewStoreListener = (change: ViewProjectGeneration) => void;
 /** Own the immutable, incrementally refreshed project snapshot for `lat ui`. */
 export declare class ViewStore {
     readonly latDir: string;
@@ -34,24 +38,33 @@ export declare class ViewStore {
     private ignoredCodePaths;
     private listeners;
     private watcher;
+    private externalWatchers;
     private pendingPaths;
     private debounceTimer;
     private gitPollTimer;
     private gitPollQueued;
     private refreshTail;
+    private editTail;
     private closed;
     constructor(latDir: string, projectRoot: string, realLatDir: string, snapshot: ViewProjectSnapshot, codeFiles: Map<string, ViewCodeReferenceFile>, codeScope: Set<string>, gitRepository: ViewGitRepository | null, options: ViewStoreOptions);
     get snapshot(): ViewProjectSnapshot;
     get markdownGeneration(): number;
     startWatching(): void;
+    private refreshExternalWatchers;
     subscribe(listener: ViewStoreListener): () => void;
     getIndex(): ViewIndex;
     getGraph(): ViewGraph;
+    renderSectionOutput(markdown: string, sectionId: string): Promise<ViewDocumentTree>;
     getDocument(requestedPath: string): Promise<ViewDocument>;
+    private editableDocumentPath;
+    getDocumentSource(requestedPath: string): Promise<ViewDocumentSource>;
+    getDocumentResource(requestedPath: string): Promise<Buffer>;
+    editDocument(requestedPath: string, baseContent: string, editedContent: string): Promise<ViewDocumentEditResponse>;
     getSource(requestedPath: string, requestedSymbol?: string, origin?: {
         sectionId: string;
         line: number;
     }, requestedLine?: number): Promise<ViewSourceDocument>;
+    getExternal(target: string): Promise<ViewExternalDocument>;
     refresh(paths: string[]): Promise<void>;
     private queueRefresh;
     close(): Promise<void>;