@plebeiantech/lat.md 0.12.3-fork.9 → 0.13.4-fork.2

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

@@ -0,0 +1,152 @@
+import { cp, lstat, mkdir, mkdtemp, readFile, readdir, rename, rm, writeFile, } from 'node:fs/promises';
+import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
+import { nodeFileTrace } from '@vercel/nft';
+import { LAT_UI_CONTENT_SECURITY_POLICY } from '../../vendor/lat.md-server/index.js';
+import { INDEX_FILE, hasIndex } from '../search/db.js';
+const defaultDependencies = {
+    traceFiles: nodeFileTrace,
+};
+function json(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+function basePathSegments(basePath) {
+    const parsed = new URL(basePath, 'http://lat.local');
+    if (parsed.origin !== 'http://lat.local' ||
+        parsed.search ||
+        parsed.hash ||
+        !basePath.startsWith('/')) {
+        throw new Error(`Invalid Lat UI server base path: ${basePath}`);
+    }
+    return parsed.pathname
+        .split('/')
+        .filter(Boolean)
+        .map((part) => {
+        const decoded = decodeURIComponent(part);
+        if (decoded === '.' ||
+            decoded === '..' ||
+            decoded.includes('/') ||
+            decoded.includes('\\')) {
+            throw new Error(`Invalid Lat UI server base path: ${basePath}`);
+        }
+        return decoded;
+    });
+}
+function safeTracePath(path) {
+    if (isAbsolute(path) ||
+        path === '..' ||
+        path.startsWith(`..${sep}`) ||
+        path.split(/[\\/]/).includes('..')) {
+        throw new Error(`Node file trace escaped the server artifact: ${path}`);
+    }
+    return path;
+}
+function outputConfig() {
+    const securityHeaders = {
+        'Content-Security-Policy': LAT_UI_CONTENT_SECURITY_POLICY,
+        'Referrer-Policy': 'no-referrer',
+        'X-Content-Type-Options': 'nosniff',
+    };
+    const immutableHeaders = {
+        'Cache-Control': 'public, max-age=31536000, immutable',
+    };
+    return {
+        version: 3,
+        routes: [
+            { src: '/(.*)', headers: securityHeaders, continue: true },
+            {
+                src: '/(?:.*?/)?assets/.*',
+                headers: immutableHeaders,
+                continue: true,
+            },
+            {
+                src: '/(?:.*?/)?data/[^/]+/[a-f0-9]{20}\\.json',
+                headers: immutableHeaders,
+                continue: true,
+            },
+            { handle: 'filesystem' },
+            { src: '/', dest: '/index.html' },
+            { src: '/(.*)/', dest: '/$1/index.html' },
+            { src: '/(.*)', dest: '/$1/index.html' },
+        ],
+    };
+}
+/** Convert an installed portable Lat UI server into Vercel Build Output API v3. */
+export async function buildVercelOutput(requestedArtifact, requestedOutput = '.vercel/output', options = {}, dependencies = defaultDependencies) {
+    const artifactDir = resolve(requestedArtifact);
+    const outputDir = resolve(requestedOutput);
+    if (!options.force) {
+        try {
+            await lstat(outputDir);
+            throw new Error(`Vercel build output already exists: ${outputDir}. Use force to replace it.`);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    const manifestFile = join(artifactDir, 'server-data', 'server.json');
+    const manifest = JSON.parse(await readFile(manifestFile, 'utf8'));
+    if (typeof manifest.basePath !== 'string') {
+        throw new Error(`Invalid Lat UI server manifest: ${manifestFile}`);
+    }
+    const entrypoint = join(artifactDir, 'app.mjs');
+    const trace = await dependencies.traceFiles([entrypoint], {
+        base: artifactDir,
+        conditions: ['node', 'production'],
+        exportsOnly: true,
+        processCwd: artifactDir,
+    });
+    for (const warning of trace.warnings) {
+        options.warn?.(`Node file trace: ${warning.message}`);
+    }
+    // Keep the database in the function even if tracing cannot infer the asset.
+    if (!hasIndex(join(artifactDir, 'server-data'))) {
+        throw new Error('Missing hybrid search database; rebuild this deployment.');
+    }
+    trace.fileList.add('server-data/server.json');
+    trace.fileList.add(`server-data/${INDEX_FILE}`);
+    // bare-addon resolves native lock bindings dynamically, beyond file tracing.
+    for (const file of [...trace.fileList]) {
+        if (!file.endsWith('fs-native-extensions/binding.js'))
+            continue;
+        const prebuilds = join(dirname(file), 'prebuilds');
+        for (const asset of await readdir(join(artifactDir, prebuilds), {
+            recursive: true,
+        })) {
+            if (asset.endsWith('.node'))
+                trace.fileList.add(join(prebuilds, asset));
+        }
+    }
+    await mkdir(dirname(outputDir), { recursive: true });
+    const stagingDir = await mkdtemp(join(dirname(outputDir), '.lat-vercel-staging-'));
+    try {
+        const staticDir = join(stagingDir, 'static');
+        const functionPath = join('functions', ...basePathSegments(manifest.basePath), 'api', 'search.func');
+        const functionDir = join(stagingDir, functionPath);
+        await cp(join(artifactDir, 'public'), staticDir, { recursive: true });
+        for (const traced of trace.fileList) {
+            const path = safeTracePath(traced);
+            const destination = join(functionDir, path);
+            await mkdir(dirname(destination), { recursive: true });
+            await cp(join(artifactDir, path), destination, {
+                dereference: true,
+                recursive: true,
+            });
+        }
+        await writeFile(join(functionDir, '.vc-config.json'), json({
+            runtime: 'nodejs22.x',
+            handler: 'app.mjs',
+            launcherType: 'Nodejs',
+            shouldAddHelpers: true,
+        }));
+        await writeFile(join(stagingDir, 'config.json'), json(outputConfig()));
+        if (options.force)
+            await rm(outputDir, { recursive: true, force: true });
+        await rename(stagingDir, outputDir);
+        return { files: trace.fileList.size, functionPath, outputDir };
+    }
+    catch (error) {
+        await rm(stagingDir, { recursive: true, force: true });
+        throw error;
+    }
+}

package/dist/src/view/vercel-server-build.d.ts

@@ -0,0 +1,10 @@
+import type { CmdContext } from '@plebeiantech/lat.md-core/context';
+import { buildServerView, type ServerViewBuildOptions, type ServerViewBuildResult } from './server-build.js';
+import { type VercelBuildOptions, type VercelBuildResult } from './vercel-build.js';
+export type VercelServerBuildDependencies = {
+    buildNode: typeof buildServerView;
+    buildOutput: (artifact: string, output: string, options: VercelBuildOptions) => Promise<VercelBuildResult>;
+    installDependencies: (artifact: string) => Promise<void>;
+};
+/** Build the portable server in staging, install it, then emit Vercel v3 output. */
+export declare function buildVercelServerView(ctx: CmdContext, requestedOutput: string, options?: ServerViewBuildOptions, dependencies?: VercelServerBuildDependencies): Promise<ServerViewBuildResult>;

package/dist/src/view/vercel-server-build.js

@@ -0,0 +1,61 @@
+import { spawn } from 'node:child_process';
+import { mkdir, mkdtemp, rm } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { buildServerView, } from './server-build.js';
+import { validateViewBuildOutput } from './static-build.js';
+import { buildVercelOutput, } from './vercel-build.js';
+function installServerDependencies(artifact) {
+    const executable = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+    const args = [
+        'install',
+        '--ignore-scripts',
+        '--no-package-lock',
+        '--omit=dev',
+        '--no-audit',
+        '--no-fund',
+    ];
+    return new Promise((resolveInstall, reject) => {
+        const child = spawn(executable, args, { cwd: artifact, stdio: 'inherit' });
+        child.once('error', reject);
+        child.once('exit', (code, signal) => {
+            if (code === 0) {
+                resolveInstall();
+                return;
+            }
+            reject(new Error(`npm install failed${signal ? ` with signal ${signal}` : ` with exit code ${code}`}`));
+        });
+    });
+}
+const defaultDependencies = {
+    buildNode: buildServerView,
+    buildOutput: buildVercelOutput,
+    installDependencies: installServerDependencies,
+};
+/** Build the portable server in staging, install it, then emit Vercel v3 output. */
+export async function buildVercelServerView(ctx, requestedOutput, options = {}, dependencies = defaultDependencies) {
+    const outputDir = resolve(ctx.projectRoot, requestedOutput);
+    await validateViewBuildOutput(outputDir, ctx.projectRoot, 'Vercel', options.force);
+    await mkdir(dirname(outputDir), { recursive: true });
+    const stagingDir = await mkdtemp(join(dirname(outputDir), '.lat-vercel-server-'));
+    const nodeArtifact = join(stagingDir, 'node');
+    try {
+        const result = await dependencies.buildNode(ctx, nodeArtifact, {
+            ...options,
+            force: false,
+        });
+        await dependencies.installDependencies(nodeArtifact);
+        await dependencies.buildOutput(nodeArtifact, outputDir, {
+            force: options.force,
+            warn: (message) => console.warn(message),
+        });
+        return { ...result, outputDir };
+    }
+    finally {
+        await rm(stagingDir, {
+            recursive: true,
+            force: true,
+            maxRetries: 10,
+            retryDelay: 150,
+        });
+    }
+}

package/dist/src/wiki/catalog.d.ts

@@ -0,0 +1,21 @@
+import { type Section } from '@plebeiantech/lat.md-core/lattice';
+import { type DiataxisMode } from '@plebeiantech/lat.md-core/cli/check-mode';
+export type WikiCatalogDoc = {
+    mode: DiataxisMode;
+    slug: string;
+    title: string;
+    firstParagraph: string;
+    relPath: string;
+    filePath: string;
+    body: string;
+    sections: Section[];
+};
+export type WikiCatalog = {
+    latDir: string;
+    projectRoot: string;
+    rootTitle?: string;
+    rootOverview?: string;
+    docs: WikiCatalogDoc[];
+    allSections: Section[];
+};
+export declare function buildWikiCatalog(latDir: string, projectRoot?: string): Promise<WikiCatalog>;

package/dist/src/wiki/catalog.js

@@ -0,0 +1,256 @@
+import { readFile } from 'node:fs/promises';
+import { basename, dirname, relative } from 'node:path';
+import { listLatticeFiles, parseFrontmatter, parseSections, } from '@plebeiantech/lat.md-core/lattice';
+import { parse } from '@plebeiantech/lat.md-core/parser';
+import { toPosix } from '@plebeiantech/lat.md-core/path';
+import { DIATAXIS_MODES, MODE_DIRS, indexNameFor, } from '@plebeiantech/lat.md-core/cli/check-mode';
+const DIR_TO_MODE = Object.create(null);
+for (const mode of DIATAXIS_MODES) {
+    DIR_TO_MODE[MODE_DIRS[mode]] = mode;
+}
+const RESERVED_SLUGS = new Set(['home', '_sidebar', '_footer']);
+function headingToText(node) {
+    function collect(children) {
+        let result = '';
+        for (const c of children) {
+            if ('value' in c && typeof c.value === 'string') {
+                result += c.value;
+            }
+            else if ('children' in c &&
+                Array.isArray(c.children)) {
+                result += collect(c.children);
+            }
+        }
+        return result;
+    }
+    return collect(node.children).trim();
+}
+function isBadgeOrImageParagraph(node) {
+    if (!node.children || node.children.length === 0)
+        return true;
+    for (const child of node.children) {
+        if (child.type === 'image')
+            continue;
+        if (child.type === 'link') {
+            const link = child;
+            const allImageOrEmpty = link.children?.every((c) => c.type === 'image' ||
+                (c.type === 'text' &&
+                    typeof c.value === 'string' &&
+                    c.value.trim() === '')) ?? false;
+            if (allImageOrEmpty)
+                continue;
+        }
+        if (child.type === 'text' &&
+            typeof child.value === 'string' &&
+            child.value.trim() === '') {
+            continue;
+        }
+        return false;
+    }
+    return true;
+}
+function extractParagraphText(content, node) {
+    if (node.position?.start?.offset != null &&
+        node.position?.end?.offset != null) {
+        return content
+            .slice(node.position.start.offset, node.position.end.offset)
+            .replace(/\r?\n\s*/g, ' ')
+            .trim();
+    }
+    return '';
+}
+export async function buildWikiCatalog(latDir, projectRoot = dirname(latDir)) {
+    const files = await listLatticeFiles(latDir);
+    const allSections = [];
+    const rawDocs = [];
+    let rootTitle;
+    let rootOverview;
+    for (const file of files) {
+        const content = await readFile(file, 'utf-8');
+        const tree = parse(content);
+        const sections = parseSections(file, content, projectRoot, tree);
+        allSections.push(...sections);
+        const relPath = toPosix(relative(latDir, file));
+        const filePath = toPosix(relative(projectRoot, file));
+        const segments = relPath.split('/');
+        const fileName = segments.pop();
+        const holder = segments.length === 0 ? basename(latDir) : segments.at(-1);
+        const isIndex = fileName === indexNameFor(holder);
+        // Root index extraction
+        if (isIndex && segments.length === 0) {
+            // Find first H1 heading
+            let h1Node;
+            for (const node of tree.children) {
+                if (node.type === 'heading' && node.depth === 1) {
+                    h1Node = node;
+                    break;
+                }
+            }
+            if (h1Node) {
+                rootTitle = headingToText(h1Node);
+                const h1Index = tree.children.indexOf(h1Node);
+                for (let i = h1Index + 1; i < tree.children.length; i++) {
+                    const node = tree.children[i];
+                    if (node.type === 'heading')
+                        break;
+                    if (node.type === 'paragraph' && !isBadgeOrImageParagraph(node)) {
+                        rootOverview = extractParagraphText(content, node);
+                        break;
+                    }
+                }
+            }
+            else {
+                rootTitle = undefined;
+                for (const node of tree.children) {
+                    if (node.type === 'heading')
+                        break;
+                    if (node.type === 'paragraph' && !isBadgeOrImageParagraph(node)) {
+                        rootOverview = extractParagraphText(content, node);
+                        break;
+                    }
+                }
+            }
+            continue;
+        }
+        // Exclude other directory indexes
+        if (isIndex)
+            continue;
+        const fm = parseFrontmatter(content);
+        if (fm.requireCodeMention === true ||
+            fm.raw['require-code-mention'] === true) {
+            continue;
+        }
+        const firstSegment = relPath.split('/')[0];
+        const dirMode = firstSegment && firstSegment !== relPath
+            ? DIR_TO_MODE[firstSegment]
+            : undefined;
+        const declaredRaw = fm.raw['mode'];
+        const hasDeclared = declaredRaw !== null && declaredRaw !== undefined;
+        const declaredValid = typeof declaredRaw === 'string' &&
+            DIATAXIS_MODES.includes(declaredRaw);
+        if (hasDeclared && !declaredValid) {
+            continue;
+        }
+        const declared = declaredValid ? declaredRaw : undefined;
+        if (declared && dirMode && declared !== dirMode) {
+            continue;
+        }
+        const resolvedMode = declared ?? dirMode;
+        if (!resolvedMode)
+            continue;
+        // Body with stripped frontmatter
+        const body = content.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '');
+        // Title: first H1 heading text, falling back to file stem
+        let title;
+        for (const s of sections) {
+            if (s.depth === 1) {
+                title = s.heading;
+                break;
+            }
+        }
+        const stem = basename(file, '.md');
+        if (!title)
+            title = stem;
+        // First paragraph
+        let firstParagraph = '';
+        const firstHeadingIndex = tree.children.findIndex((n) => n.type === 'heading');
+        if (firstHeadingIndex >= 0) {
+            for (let i = firstHeadingIndex + 1; i < tree.children.length; i++) {
+                const node = tree.children[i];
+                if (node.type === 'heading')
+                    break;
+                if (node.type === 'paragraph') {
+                    firstParagraph = extractParagraphText(content, node);
+                    break;
+                }
+            }
+        }
+        else {
+            const firstP = tree.children.find((n) => n.type === 'paragraph');
+            if (firstP) {
+                firstParagraph = extractParagraphText(content, firstP);
+            }
+        }
+        if (!firstParagraph && sections.length > 0 && sections[0].firstParagraph) {
+            firstParagraph = sections[0].firstParagraph;
+        }
+        rawDocs.push({
+            file,
+            relPath,
+            filePath,
+            content,
+            tree,
+            sections,
+            mode: resolvedMode,
+            body,
+            title,
+            firstParagraph,
+        });
+    }
+    // Sort docs deterministically by relPath
+    rawDocs.sort((a, b) => a.relPath.localeCompare(b.relPath));
+    // Slug assignment with collision and reserved name handling
+    const stemCounts = new Map();
+    for (const doc of rawDocs) {
+        const stem = basename(doc.relPath, '.md').toLowerCase();
+        stemCounts.set(stem, (stemCounts.get(stem) ?? 0) + 1);
+    }
+    const candidates = rawDocs.map((doc) => {
+        const stem = basename(doc.relPath, '.md');
+        const modeSlug = `${doc.mode}-${stem}`;
+        const relDir = dirname(doc.relPath);
+        const dirPrefix = relDir === '.' ? '' : relDir.replace(/\//g, '-');
+        const dirSlug = dirPrefix ? `${dirPrefix}-${stem}` : modeSlug;
+        return { doc, stem, modeSlug, dirSlug };
+    });
+    // Check which initial slugs collide or are reserved
+    const candidateModeCounts = new Map();
+    for (const c of candidates) {
+        candidateModeCounts.set(c.modeSlug.toLowerCase(), (candidateModeCounts.get(c.modeSlug.toLowerCase()) ?? 0) + 1);
+    }
+    const assignedDocs = [];
+    const usedSlugs = new Set();
+    for (const c of candidates) {
+        const lowerStem = c.stem.toLowerCase();
+        const isReserved = RESERVED_SLUGS.has(lowerStem);
+        const hasStemCollision = (stemCounts.get(lowerStem) ?? 0) > 1;
+        let slug;
+        if (isReserved || hasStemCollision) {
+            const modeCollides = (candidateModeCounts.get(c.modeSlug.toLowerCase()) ?? 0) > 1;
+            if (modeCollides && c.dirSlug !== c.modeSlug) {
+                slug = c.dirSlug;
+            }
+            else {
+                slug = c.modeSlug;
+            }
+        }
+        else {
+            slug = c.stem;
+        }
+        // Ensure no accidental collision with already assigned slug
+        let finalSlug = slug;
+        let suffix = 2;
+        while (usedSlugs.has(finalSlug.toLowerCase())) {
+            finalSlug = `${slug}-${suffix++}`;
+        }
+        usedSlugs.add(finalSlug.toLowerCase());
+        assignedDocs.push({
+            mode: c.doc.mode,
+            slug: finalSlug,
+            title: c.doc.title,
+            firstParagraph: c.doc.firstParagraph,
+            relPath: c.doc.relPath,
+            filePath: c.doc.filePath,
+            body: c.doc.body,
+            sections: c.doc.sections,
+        });
+    }
+    return {
+        latDir,
+        projectRoot,
+        rootTitle,
+        rootOverview,
+        docs: assignedDocs,
+        allSections,
+    };
+}

package/dist/src/wiki/publish.d.ts

@@ -0,0 +1,27 @@
+export type WikiRemoteInfo = {
+    repoName: string;
+    repoUrl?: string;
+    wikiRemoteUrl: string;
+};
+export type PublishWikiOptions = {
+    latDir: string;
+    projectRoot?: string;
+    remote?: string;
+    repoUrl?: string;
+    ref?: string;
+    message?: string;
+    dryRun?: boolean;
+};
+export type PublishWikiResult = {
+    wikiRemoteUrl: string;
+    repoUrl?: string;
+    ref: string;
+    pages: number;
+    writtenFiles: string[];
+    removedFiles: string[];
+    changed: boolean;
+    pushed: boolean;
+    commitSha?: string;
+};
+export declare function resolveWikiRemote(projectRoot: string, remoteOrUrl?: string): WikiRemoteInfo;
+export declare function publishWiki(options: PublishWikiOptions): Promise<PublishWikiResult>;