@plebeiantech/lat.md 0.13.4-fork.1 → 0.13.4-fork.2

package/dist/src/cli/index.js

@@ -406,4 +406,35 @@ program
     const { graphCommand } = await import('./graph.js');
     handleResult(await graphCommand(ctx, opts));
 });
+const wikiCmd = program
+    .command('wiki')
+    .description('Publish Diátaxis documentation to GitHub Wiki');
+wikiCmd
+    .command('build [output]')
+    .description('Build GitHub Wiki pages into a directory')
+    .option('--repo <owner/repo-or-url>', 'GitHub repository to resolve blob links against')
+    .option('--ref <ref>', 'Git revision for source links')
+    .action(async (output, opts) => {
+    const ctx = resolveContext(program.opts());
+    const { wikiBuildCommand } = await import('./wiki.js');
+    try {
+        handleResult(await wikiBuildCommand(ctx, output, opts));
+    }
+    catch (err) {
+        handleResult({ output: err.message, isError: true });
+    }
+});
+wikiCmd
+    .command('publish')
+    .description('Publish GitHub Wiki pages to companion .wiki.git repository')
+    .option('--remote <remote-or-url>', 'Git remote or URL (default: origin)')
+    .option('--repo <owner/repo-or-url>', 'GitHub repository for blob links')
+    .option('--ref <ref>', 'Git revision for source links')
+    .option('--message <message>', 'Commit message for the wiki push')
+    .option('--dry-run', 'Commit locally in the clone without pushing')
+    .action(async (opts) => {
+    const ctx = resolveContext(program.opts());
+    const { wikiPublishCommand } = await import('./wiki.js');
+    handleResult(await wikiPublishCommand(ctx, opts));
+});
 await program.parseAsync(checkTargetArgs.args, { from: 'user' });

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

@@ -0,0 +1,12 @@
+import type { CmdContext, CmdResult } from '@plebeiantech/lat.md-core/context';
+export declare function wikiBuildCommand(ctx: CmdContext, output?: string, opts?: {
+    repo?: string;
+    ref?: string;
+}): Promise<CmdResult>;
+export declare function wikiPublishCommand(ctx: CmdContext, opts?: {
+    remote?: string;
+    repo?: string;
+    ref?: string;
+    message?: string;
+    dryRun?: boolean;
+}): Promise<CmdResult>;

package/dist/src/cli/wiki.js

@@ -0,0 +1,85 @@
+import { isAbsolute, relative, resolve } from 'node:path';
+import { buildWikiCatalog } from '../wiki/catalog.js';
+import { transformWikiCatalog } from '../wiki/transform.js';
+import { renderWikiBundle, writeWikiBundle } from '../wiki/render.js';
+import { publishWiki, resolveWikiRemote, } from '../wiki/publish.js';
+// @lat: [[cli#CLI#wiki]]
+export async function wikiBuildCommand(ctx, output, opts) {
+    const resolvedOutput = output
+        ? resolve(ctx.projectRoot, output)
+        : resolve(ctx.projectRoot, '.lat-build/wiki');
+    const relToLat = relative(ctx.latDir, resolvedOutput);
+    if (resolvedOutput === ctx.projectRoot ||
+        resolvedOutput === ctx.latDir ||
+        (!relToLat.startsWith('..') && !isAbsolute(relToLat))) {
+        throw new Error(`Refusing to write wiki build output to source directory (${resolvedOutput}).`);
+    }
+    let remoteInfo;
+    if (opts?.repo) {
+        try {
+            remoteInfo = resolveWikiRemote(ctx.projectRoot, opts.repo);
+        }
+        catch (err) {
+            return {
+                output: err.message,
+                isError: true,
+            };
+        }
+    }
+    else {
+        try {
+            remoteInfo = resolveWikiRemote(ctx.projectRoot);
+        }
+        catch {
+            remoteInfo = undefined;
+        }
+    }
+    const rawCatalog = await buildWikiCatalog(ctx.latDir, ctx.projectRoot);
+    if (rawCatalog.docs.length === 0) {
+        return {
+            output: `No Diátaxis documents found in ${ctx.latDir}.`,
+            isError: true,
+        };
+    }
+    const catalog = await transformWikiCatalog(rawCatalog, {
+        repoUrl: remoteInfo?.repoUrl,
+        ref: opts?.ref,
+    });
+    const bundle = renderWikiBundle(catalog, { repoName: remoteInfo?.repoName });
+    const { writtenFiles } = await writeWikiBundle(resolvedOutput, bundle, {
+        clean: true,
+    });
+    return {
+        output: `Built ${catalog.docs.length} Diátaxis page(s) (${writtenFiles.length} file(s)) to ${resolvedOutput}.`,
+    };
+}
+export async function wikiPublishCommand(ctx, opts) {
+    try {
+        const result = await publishWiki({
+            latDir: ctx.latDir,
+            projectRoot: ctx.projectRoot,
+            remote: opts?.remote,
+            repoUrl: opts?.repo,
+            ref: opts?.ref,
+            message: opts?.message,
+            dryRun: opts?.dryRun,
+        });
+        if (!result.changed) {
+            return {
+                output: `Wiki is already up to date (${result.pages} page(s)).`,
+            };
+        }
+        const action = result.pushed
+            ? 'Published'
+            : 'Built and committed (dry-run)';
+        return {
+            output: `${action} ${result.pages} Diátaxis page(s) to ${result.wikiRemoteUrl} (${result.commitSha?.slice(0, 7)}).`,
+        };
+    }
+    catch (err) {
+        return {
+            output: err.message,
+            isError: true,
+        };
+    }
+}

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>;

package/dist/src/wiki/publish.js

@@ -0,0 +1,265 @@
+import { execFile, execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, dirname, isAbsolute, join } from 'node:path';
+import { promisify } from 'node:util';
+import { buildWikiCatalog } from './catalog.js';
+import { transformWikiCatalog } from './transform.js';
+import { renderWikiBundle, writeWikiBundle } from './render.js';
+const execFileAsync = promisify(execFile);
+const GITHUB_HTTPS_RE = /^https:\/\/github\.com\/([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+?)(?:\.git)?\/?$/;
+const GITHUB_SSH_RE = /^(?:git@github\.com:|ssh:\/\/git@github\.com\/)([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+?)(?:\.git)?\/?$/;
+const GITHUB_SLUG_RE = /^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+?)(?:\.git)?$/;
+function redactCredentials(url) {
+    return url.replace(/:\/\/[^@/]+@/, '://***@');
+}
+function assertNotUpstream(target) {
+    const lower = target.trim().toLowerCase();
+    if (lower === 'upstream' || lower.includes('vercel-labs/lat.md')) {
+        throw new Error(`Refusing to target upstream repository (vercel-labs/lat.md). Specify your fork repository.`);
+    }
+}
+function parseGitHubUrlOrSlug(target) {
+    const httpsMatch = target.match(GITHUB_HTTPS_RE);
+    if (httpsMatch) {
+        return { owner: httpsMatch[1], repo: httpsMatch[2], isSsh: false };
+    }
+    const sshMatch = target.match(GITHUB_SSH_RE);
+    if (sshMatch) {
+        return { owner: sshMatch[1], repo: sshMatch[2], isSsh: true };
+    }
+    if (!isAbsolute(target) && !existsSync(target)) {
+        const slugMatch = target.match(GITHUB_SLUG_RE);
+        if (slugMatch) {
+            return { owner: slugMatch[1], repo: slugMatch[2], isSsh: false };
+        }
+    }
+    return null;
+}
+export function resolveWikiRemote(projectRoot, remoteOrUrl) {
+    if (remoteOrUrl) {
+        if (remoteOrUrl.trim().startsWith('-')) {
+            throw new Error(`Invalid git remote or URL: ${remoteOrUrl}`);
+        }
+        assertNotUpstream(remoteOrUrl);
+    }
+    let resolved = remoteOrUrl;
+    // If omitted, default to origin
+    if (!resolved) {
+        try {
+            const originUrl = execFileSync('git', ['-C', projectRoot, 'remote', 'get-url', '--', 'origin'], {
+                encoding: 'utf-8',
+                env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+                stdio: ['pipe', 'pipe', 'ignore'],
+            }).trim();
+            assertNotUpstream(originUrl);
+            resolved = originUrl;
+        }
+        catch (err) {
+            if (err.message.includes('Refusing to target upstream')) {
+                throw err;
+            }
+            throw new Error(`No remote named 'origin' found in git repository. Specify --remote or --repo.`);
+        }
+    }
+    else if (!resolved.includes('/') &&
+        !resolved.includes(':') &&
+        !resolved.endsWith('.git')) {
+        // Single remote name token
+        try {
+            const namedUrl = execFileSync('git', ['-C', projectRoot, 'remote', 'get-url', '--', resolved], {
+                encoding: 'utf-8',
+                env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+                stdio: ['pipe', 'pipe', 'ignore'],
+            }).trim();
+            assertNotUpstream(namedUrl);
+            resolved = namedUrl;
+        }
+        catch (err) {
+            if (err.message.includes('Refusing to target upstream')) {
+                throw err;
+            }
+            // If remote get-url failed, fall through with the raw token
+        }
+    }
+    assertNotUpstream(resolved);
+    const gh = parseGitHubUrlOrSlug(resolved);
+    if (gh) {
+        const repoName = gh.repo;
+        const repoUrl = `https://github.com/${gh.owner}/${gh.repo}`;
+        const wikiRemoteUrl = gh.isSsh
+            ? `git@github.com:${gh.owner}/${gh.repo}.wiki.git`
+            : `https://github.com/${gh.owner}/${gh.repo}.wiki.git`;
+        if (wikiRemoteUrl.trim().startsWith('-')) {
+            throw new Error(`Invalid wiki remote URL: ${wikiRemoteUrl}`);
+        }
+        return {
+            repoName,
+            repoUrl,
+            wikiRemoteUrl,
+        };
+    }
+    // Treat as local filesystem path
+    let wikiRemoteUrl = resolved;
+    if (wikiRemoteUrl.endsWith('.wiki.git')) {
+        // already ends with .wiki.git
+    }
+    else if (wikiRemoteUrl.endsWith('.git')) {
+        wikiRemoteUrl = wikiRemoteUrl.slice(0, -4) + '.wiki.git';
+    }
+    else {
+        wikiRemoteUrl = `${wikiRemoteUrl}.wiki.git`;
+    }
+    if (wikiRemoteUrl.trim().startsWith('-')) {
+        throw new Error(`Invalid wiki remote URL: ${wikiRemoteUrl}`);
+    }
+    const base = basename(resolved);
+    const repoName = base.replace(/\.wiki\.git$/, '').replace(/\.git$/, '');
+    return {
+        repoName,
+        repoUrl: undefined,
+        wikiRemoteUrl,
+    };
+}
+function resolveGitRef(projectRoot, explicitRef) {
+    if (explicitRef)
+        return explicitRef;
+    try {
+        const stdout = execFileSync('git', ['-C', projectRoot, 'rev-parse', 'HEAD'], {
+            encoding: 'utf-8',
+            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+            stdio: ['pipe', 'pipe', 'ignore'],
+        }).trim();
+        if (stdout)
+            return stdout;
+    }
+    catch {
+        // ignore
+    }
+    return 'HEAD';
+}
+export async function publishWiki(options) {
+    const projectRoot = options.projectRoot ?? dirname(options.latDir);
+    const remoteInfo = resolveWikiRemote(projectRoot, options.remote);
+    if (options.repoUrl) {
+        if (options.repoUrl.trim().startsWith('-')) {
+            throw new Error(`Invalid repo URL: ${options.repoUrl}`);
+        }
+        assertNotUpstream(options.repoUrl);
+        const gh = parseGitHubUrlOrSlug(options.repoUrl);
+        if (gh) {
+            remoteInfo.repoUrl = `https://github.com/${gh.owner}/${gh.repo}`;
+        }
+    }
+    if (remoteInfo.wikiRemoteUrl.trim().startsWith('-')) {
+        throw new Error(`Invalid wiki remote URL: ${remoteInfo.wikiRemoteUrl}`);
+    }
+    const ref = resolveGitRef(projectRoot, options.ref);
+    const shortSha = ref.slice(0, 7);
+    const rawCatalog = await buildWikiCatalog(options.latDir, projectRoot);
+    if (rawCatalog.docs.length === 0) {
+        throw new Error(`No Diataxis documents found in ${options.latDir} to publish.`);
+    }
+    const catalog = await transformWikiCatalog(rawCatalog, {
+        repoUrl: remoteInfo.repoUrl,
+        ref,
+    });
+    const cloneDir = await mkdtemp(join(tmpdir(), 'lat-wiki-clone-'));
+    try {
+        try {
+            await execFileAsync('git', ['clone', '--', remoteInfo.wikiRemoteUrl, cloneDir], {
+                env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+            });
+        }
+        catch (err) {
+            const safeUrl = redactCredentials(remoteInfo.wikiRemoteUrl);
+            const safeMsg = redactCredentials(err.message);
+            throw new Error(`Failed to clone wiki repository (${safeUrl}). ` +
+                `GitHub requires enabling Wikis in repository settings and creating the initial page ` +
+                `in the repository's Wiki tab before the wiki repository can be cloned or pushed.\n` +
+                `${safeMsg}`);
+        }
+        const bundle = renderWikiBundle(catalog, { repoName: remoteInfo.repoName });
+        const { writtenFiles, removedFiles } = await writeWikiBundle(cloneDir, bundle, {
+            clean: true,
+        });
+        const statusOutput = (await execFileAsync('git', ['status', '--porcelain'], {
+            cwd: cloneDir,
+            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+        })).stdout.trim();
+        if (!statusOutput) {
+            return {
+                wikiRemoteUrl: remoteInfo.wikiRemoteUrl,
+                repoUrl: remoteInfo.repoUrl,
+                ref,
+                pages: catalog.docs.length,
+                writtenFiles,
+                removedFiles,
+                changed: false,
+                pushed: false,
+            };
+        }
+        await execFileAsync('git', ['add', '-A'], {
+            cwd: cloneDir,
+            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+        });
+        const message = options.message ?? `Publish Diataxis documentation (${shortSha})`;
+        await execFileAsync('git', [
+            '-c',
+            'user.name=lat.md',
+            '-c',
+            'user.email=lat@users.noreply.github.com',
+            '-c',
+            'commit.gpgsign=false',
+            'commit',
+            '-m',
+            message,
+        ], {
+            cwd: cloneDir,
+            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+        });
+        const commitSha = (await execFileAsync('git', ['rev-parse', 'HEAD'], {
+            cwd: cloneDir,
+            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+        })).stdout.trim();
+        if (options.dryRun) {
+            return {
+                wikiRemoteUrl: remoteInfo.wikiRemoteUrl,
+                repoUrl: remoteInfo.repoUrl,
+                ref,
+                pages: catalog.docs.length,
+                writtenFiles,
+                removedFiles,
+                changed: true,
+                pushed: false,
+                commitSha,
+            };
+        }
+        try {
+            await execFileAsync('git', ['push', 'origin', 'HEAD'], {
+                cwd: cloneDir,
+                env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+            });
+        }
+        catch (err) {
+            const safeUrl = redactCredentials(remoteInfo.wikiRemoteUrl);
+            const safeMsg = redactCredentials(err.message);
+            throw new Error(`Failed to push to wiki repository (${safeUrl}): ${safeMsg}`);
+        }
+        return {
+            wikiRemoteUrl: remoteInfo.wikiRemoteUrl,
+            repoUrl: remoteInfo.repoUrl,
+            ref,
+            pages: catalog.docs.length,
+            writtenFiles,
+            removedFiles,
+            changed: true,
+            pushed: true,
+            commitSha,
+        };
+    }
+    finally {
+        await rm(cloneDir, { recursive: true, force: true });
+    }
+}

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

@@ -0,0 +1,20 @@
+import type { WikiCatalog } from './catalog.js';
+export type WikiBundlePage = {
+    slug: string;
+    fileName: string;
+    content: string;
+};
+export type WikiBundle = {
+    home: string;
+    sidebar: string;
+    pages: WikiBundlePage[];
+};
+export declare function renderWikiBundle(catalog: WikiCatalog, options?: {
+    repoName?: string;
+}): WikiBundle;
+export declare function writeWikiBundle(outputDir: string, bundle: WikiBundle, options?: {
+    clean?: boolean;
+}): Promise<{
+    writtenFiles: string[];
+    removedFiles: string[];
+}>;

package/dist/src/wiki/render.js

@@ -0,0 +1,163 @@
+import { lstat, mkdir, readdir, rm, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
+const MODE_ORDER = [
+    'tutorial',
+    'how-to',
+    'reference',
+    'explanation',
+];
+const MODE_HEADINGS = {
+    tutorial: { h2: '## Tutorials', h3: '### Tutorials' },
+    'how-to': { h2: '## How-To Guides', h3: '### How-To Guides' },
+    reference: { h2: '## Reference', h3: '### Reference' },
+    explanation: { h2: '## Explanation', h3: '### Explanation' },
+};
+function normalizeContent(content) {
+    return content.endsWith('\n') ? content : content + '\n';
+}
+export function renderWikiBundle(catalog, options) {
+    const rootTitle = catalog.rootTitle ?? options?.repoName ?? 'Documentation';
+    // Group docs by mode
+    const docsByMode = new Map();
+    for (const mode of MODE_ORDER) {
+        docsByMode.set(mode, []);
+    }
+    for (const doc of catalog.docs) {
+        const list = docsByMode.get(doc.mode);
+        if (list) {
+            list.push(doc);
+        }
+    }
+    // Sort docs within each mode by slug
+    for (const list of docsByMode.values()) {
+        list.sort((a, b) => a.slug.localeCompare(b.slug));
+    }
+    // 1. Home.md
+    const homeParts = [];
+    homeParts.push(`# ${rootTitle}`);
+    if (catalog.rootOverview) {
+        homeParts.push(catalog.rootOverview);
+    }
+    for (const mode of MODE_ORDER) {
+        const docs = docsByMode.get(mode);
+        if (docs.length === 0)
+            continue;
+        homeParts.push(MODE_HEADINGS[mode].h2);
+        const lines = docs.map((doc) => {
+            const summary = doc.firstParagraph ? `: ${doc.firstParagraph}` : '';
+            return `- [${doc.title}](${doc.slug})${summary}`;
+        });
+        homeParts.push(lines.join('\n'));
+    }
+    const home = normalizeContent(homeParts.join('\n\n'));
+    // 2. _Sidebar.md
+    const sidebarParts = ['- [Home](Home)'];
+    for (const mode of MODE_ORDER) {
+        const docs = docsByMode.get(mode);
+        if (docs.length === 0)
+            continue;
+        const lines = docs.map((doc) => `- [${doc.title}](${doc.slug})`);
+        sidebarParts.push(`${MODE_HEADINGS[mode].h3}\n${lines.join('\n')}`);
+    }
+    const sidebar = normalizeContent(sidebarParts.join('\n\n'));
+    // 3. Pages ordered by slug
+    const sortedDocs = [...catalog.docs].sort((a, b) => a.slug.localeCompare(b.slug));
+    const pages = sortedDocs.map((doc) => ({
+        slug: doc.slug,
+        fileName: `${doc.slug}.md`,
+        content: normalizeContent(doc.body),
+    }));
+    return {
+        home,
+        sidebar,
+        pages,
+    };
+}
+async function verifyNoSymlinksInPath(targetPath) {
+    const absPath = resolve(targetPath);
+    const root = isAbsolute(absPath) ? resolve(sep) : '';
+    const parts = absPath.slice(root.length).split(sep);
+    let current = root;
+    for (const part of parts) {
+        if (!part)
+            continue;
+        current = join(current, part);
+        try {
+            const stat = await lstat(current);
+            if (stat.isSymbolicLink()) {
+                if (process.platform === 'darwin' &&
+                    (current === '/var' || current === '/tmp' || current === '/etc')) {
+                    continue;
+                }
+                throw new Error(`Refusing to write to symbolic link path: ${current}`);
+            }
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                break; // remaining path does not exist yet
+            }
+            throw err;
+        }
+    }
+}
+export async function writeWikiBundle(outputDir, bundle, options) {
+    const absOutputDir = resolve(outputDir);
+    await verifyNoSymlinksInPath(absOutputDir);
+    await mkdir(absOutputDir, { recursive: true });
+    const filesToWrite = [
+        { fileName: 'Home.md', content: bundle.home },
+        { fileName: '_Sidebar.md', content: bundle.sidebar },
+    ];
+    for (const page of bundle.pages) {
+        if (page.fileName.includes('/') ||
+            page.fileName.includes('\\') ||
+            page.fileName.includes('..') ||
+            page.slug.includes('/') ||
+            page.slug.includes('\\') ||
+            page.slug.includes('..')) {
+            throw new Error(`Invalid page slug or fileName: ${page.fileName}`);
+        }
+        filesToWrite.push({ fileName: page.fileName, content: page.content });
+    }
+    const writtenSet = new Set();
+    const writtenFiles = [];
+    for (const item of filesToWrite) {
+        const filePath = resolve(absOutputDir, item.fileName);
+        if (dirname(filePath) !== absOutputDir) {
+            throw new Error(`Path traversal attempted: ${item.fileName}`);
+        }
+        try {
+            const stat = await lstat(filePath);
+            if (stat.isSymbolicLink()) {
+                throw new Error(`Refusing to overwrite symbolic link: ${filePath}`);
+            }
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT') {
+                throw err;
+            }
+        }
+        await writeFile(filePath, item.content, 'utf-8');
+        writtenSet.add(item.fileName);
+        writtenFiles.push(item.fileName);
+    }
+    const removedFiles = [];
+    if (options?.clean) {
+        const writtenLower = new Set([...writtenSet].map((f) => f.toLowerCase()));
+        const entries = await readdir(absOutputDir);
+        for (const entry of entries) {
+            if (entry.toLowerCase().endsWith('.md') &&
+                !writtenLower.has(entry.toLowerCase())) {
+                const entryPath = join(absOutputDir, entry);
+                await rm(entryPath, { force: true });
+                removedFiles.push(entry);
+            }
+        }
+    }
+    writtenFiles.sort();
+    removedFiles.sort();
+    return {
+        writtenFiles,
+        removedFiles,
+    };
+}

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

@@ -0,0 +1,7 @@
+import type { WikiCatalog, WikiCatalogDoc } from './catalog.js';
+export type WikiTransformOptions = {
+    repoUrl?: string;
+    ref?: string;
+};
+export declare function transformWikiDocument(doc: WikiCatalogDoc, catalog: WikiCatalog, options?: WikiTransformOptions): Promise<WikiCatalogDoc>;
+export declare function transformWikiCatalog(catalog: WikiCatalog, options?: WikiTransformOptions): Promise<WikiCatalog>;

package/dist/src/wiki/transform.js

@@ -0,0 +1,264 @@
+import { existsSync, statSync } from 'node:fs';
+import { dirname, isAbsolute, relative, resolve } from 'node:path';
+import { buildFileIndex, buildSectionSlugIndex, flattenSections, resolveRef, } from '@plebeiantech/lat.md-core/lattice';
+import { inspectRepositoryPath, normalizeRepositoryPath, } from '@plebeiantech/lat.md-core/repository-path';
+import { resolveSourceSymbol, } from '@plebeiantech/lat.md-core/source-parser';
+import { isSourceFilePath } from '@plebeiantech/lat.md-core/source-formats';
+import { parse } from '@plebeiantech/lat.md-core/parser';
+import { toPosix } from '@plebeiantech/lat.md-core/path';
+function collectTargetNodes(node, list) {
+    if ((node.type === 'wikiLink' || node.type === 'link') &&
+        node.position?.start?.offset != null &&
+        node.position?.end?.offset != null) {
+        list.push(node);
+        return;
+    }
+    if ('children' in node &&
+        Array.isArray(node.children)) {
+        for (const child of node.children) {
+            collectTargetNodes(child, list);
+        }
+    }
+}
+async function rewriteText(text, baseDir, ctx) {
+    if (!text)
+        return text;
+    const tree = parse(text);
+    const nodes = [];
+    collectTargetNodes(tree, nodes);
+    if (nodes.length === 0)
+        return text;
+    const repoUrl = ctx.options?.repoUrl?.replace(/\/+$/, '');
+    const ref = ctx.options?.ref ?? 'HEAD';
+    const replacements = [];
+    for (const node of nodes) {
+        const start = node.position.start.offset;
+        const end = node.position.end.offset;
+        if (node.type === 'wikiLink') {
+            const target = (node.value ?? '').trim();
+            const alias = node.data?.alias ? node.data.alias.trim() : undefined;
+            // 1. Try to resolve as Markdown section
+            const refResult = resolveRef(target, ctx.sectionIds, ctx.fileIndex, ctx.slugIndex);
+            const section = refResult?.resolved
+                ? ctx.sectionByLowerId.get(refResult.resolved.toLowerCase())
+                : undefined;
+            if (section) {
+                const doc = ctx.docByFilePath.get(section.filePath);
+                const label = alias ?? section.heading;
+                if (doc) {
+                    // Exported Diataxis section link
+                    const dest = section.depth === 1
+                        ? doc.slug
+                        : `${doc.slug}#${section.githubSlug}`;
+                    replacements.push({ start, end, replacement: `[${label}](${dest})` });
+                }
+                else {
+                    // Non-exported lat.md section link
+                    if (repoUrl) {
+                        const frag = section.githubSlug ? `#${section.githubSlug}` : '';
+                        replacements.push({
+                            start,
+                            end,
+                            replacement: `[${label}](${repoUrl}/blob/${ref}/${section.filePath}${frag})`,
+                        });
+                    }
+                    else {
+                        replacements.push({ start, end, replacement: label });
+                    }
+                }
+                continue;
+            }
+            // 2. Source code and repository path link
+            const hashIdx = target.indexOf('#');
+            const filePart = hashIdx >= 0 ? target.slice(0, hashIdx) : target;
+            const symbolPath = hashIdx >= 0 ? target.slice(hashIdx + 1) : undefined;
+            const normalizedPath = normalizeRepositoryPath(filePart);
+            if (!normalizedPath) {
+                replacements.push({ start, end, replacement: alias ?? target });
+                continue;
+            }
+            const inspected = await inspectRepositoryPath(ctx.catalog.projectRoot, normalizedPath);
+            if (inspected.kind !== 'file' && inspected.kind !== 'directory') {
+                replacements.push({ start, end, replacement: alias ?? target });
+                continue;
+            }
+            const label = alias ?? (symbolPath || normalizedPath);
+            if (symbolPath && isSourceFilePath(normalizedPath)) {
+                const symbolResult = await resolveSourceSymbol(normalizedPath, symbolPath, ctx.catalog.projectRoot, { latDir: ctx.catalog.latDir });
+                const parts = symbolPath.split('#');
+                let symbol;
+                if (parts.length === 1) {
+                    symbol = symbolResult.symbols.find((s) => s.name === parts[0] && !s.parent);
+                }
+                else if (parts.length === 2) {
+                    symbol = symbolResult.symbols.find((s) => s.name === parts[1] && s.parent === parts[0]);
+                }
+                if (symbol) {
+                    const lineFrag = symbol.startLine === symbol.endLine
+                        ? `#L${symbol.startLine}`
+                        : `#L${symbol.startLine}-L${symbol.endLine}`;
+                    if (repoUrl) {
+                        replacements.push({
+                            start,
+                            end,
+                            replacement: `[${label}](${repoUrl}/blob/${ref}/${normalizedPath}${lineFrag})`,
+                        });
+                    }
+                    else {
+                        replacements.push({ start, end, replacement: label });
+                    }
+                }
+                else {
+                    if (repoUrl) {
+                        replacements.push({
+                            start,
+                            end,
+                            replacement: `[${label}](${repoUrl}/blob/${ref}/${normalizedPath})`,
+                        });
+                    }
+                    else {
+                        replacements.push({ start, end, replacement: label });
+                    }
+                }
+            }
+            else {
+                const action = inspected.kind === 'directory' ? 'tree' : 'blob';
+                if (repoUrl) {
+                    replacements.push({
+                        start,
+                        end,
+                        replacement: `[${label}](${repoUrl}/${action}/${ref}/${normalizedPath})`,
+                    });
+                }
+                else {
+                    replacements.push({ start, end, replacement: label });
+                }
+            }
+        }
+        else if (node.type === 'link') {
+            const url = node.url ?? '';
+            // Skip same-page anchors and external URLs
+            if (url.startsWith('#') ||
+                url.startsWith('http://') ||
+                url.startsWith('https://') ||
+                url.startsWith('mailto:') ||
+                url.startsWith('tel:')) {
+                continue;
+            }
+            // Extract inner label text
+            let label = '';
+            if (node.children && node.children.length > 0) {
+                const first = node.children[0];
+                const last = node.children[node.children.length - 1];
+                if (first.position?.start?.offset != null &&
+                    last.position?.end?.offset != null) {
+                    label = text.slice(first.position.start.offset, last.position.end.offset);
+                }
+            }
+            const hashIdx = url.indexOf('#');
+            const pathPart = hashIdx >= 0 ? url.slice(0, hashIdx) : url;
+            const frag = hashIdx >= 0 ? url.slice(hashIdx) : '';
+            const resolvedPath = resolve(baseDir, pathPart);
+            const relToRoot = relative(ctx.catalog.projectRoot, resolvedPath);
+            const isInsideRoot = !relToRoot.startsWith('..') && !isAbsolute(relToRoot);
+            if (!isInsideRoot) {
+                // Prevent path traversal escape: do not rewrite links escaping project root
+                continue;
+            }
+            const repoRelPath = toPosix(relToRoot);
+            const doc = ctx.docByFilePath.get(repoRelPath) ??
+                ctx.docByFilePath.get(repoRelPath + '.md');
+            if (doc) {
+                replacements.push({
+                    start,
+                    end,
+                    replacement: `[${label}](${doc.slug}${frag})`,
+                });
+            }
+            else if (existsSync(resolvedPath)) {
+                let isDir = false;
+                try {
+                    isDir = statSync(resolvedPath).isDirectory();
+                }
+                catch {
+                    // ignore
+                }
+                const action = isDir ? 'tree' : 'blob';
+                if (repoUrl) {
+                    replacements.push({
+                        start,
+                        end,
+                        replacement: `[${label}](${repoUrl}/${action}/${ref}/${repoRelPath}${frag})`,
+                    });
+                }
+                else {
+                    replacements.push({ start, end, replacement: label });
+                }
+            }
+        }
+    }
+    // Apply replacements in reverse order of appearance
+    replacements.sort((a, b) => b.start - a.start);
+    let result = text;
+    for (const rep of replacements) {
+        result =
+            result.slice(0, rep.start) + rep.replacement + result.slice(rep.end);
+    }
+    return result;
+}
+function createTransformContext(catalog, options) {
+    const flat = flattenSections(catalog.allSections);
+    const sectionIds = new Set(flat.map((s) => s.id.toLowerCase()));
+    const sectionByLowerId = new Map(flat.map((s) => [s.id.toLowerCase(), s]));
+    const fileIndex = buildFileIndex(catalog.allSections);
+    const slugIndex = buildSectionSlugIndex(catalog.allSections);
+    const docByFilePath = new Map(catalog.docs.map((d) => [d.filePath, d]));
+    const docByRelPath = new Map(catalog.docs.map((d) => [d.relPath, d]));
+    return {
+        catalog,
+        options,
+        sectionIds,
+        sectionByLowerId,
+        fileIndex,
+        slugIndex,
+        docByFilePath,
+        docByRelPath,
+    };
+}
+export async function transformWikiDocument(doc, catalog, options) {
+    const ctx = createTransformContext(catalog, options);
+    const baseDir = resolve(catalog.projectRoot, dirname(doc.filePath));
+    const [body, firstParagraph] = await Promise.all([
+        rewriteText(doc.body, baseDir, ctx),
+        rewriteText(doc.firstParagraph, baseDir, ctx),
+    ]);
+    return {
+        ...doc,
+        body,
+        firstParagraph,
+    };
+}
+export async function transformWikiCatalog(catalog, options) {
+    const ctx = createTransformContext(catalog, options);
+    const transformedDocs = await Promise.all(catalog.docs.map(async (doc) => {
+        const baseDir = resolve(catalog.projectRoot, dirname(doc.filePath));
+        const [body, firstParagraph] = await Promise.all([
+            rewriteText(doc.body, baseDir, ctx),
+            rewriteText(doc.firstParagraph, baseDir, ctx),
+        ]);
+        return {
+            ...doc,
+            body,
+            firstParagraph,
+        };
+    }));
+    let rootOverview = catalog.rootOverview;
+    if (rootOverview) {
+        rootOverview = await rewriteText(rootOverview, catalog.latDir, ctx);
+    }
+    return {
+        ...catalog,
+        rootOverview,
+        docs: transformedDocs,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plebeiantech/lat.md",
-  "version": "0.13.4-fork.1",
+  "version": "0.13.4-fork.2",
   "description": "A knowledge graph for your codebase, written in markdown",
   "type": "module",
   "license": "MIT",
@@ -104,8 +104,8 @@
     "zod": "^4.3.6",
     "@lat.md/embed": "0.2.2",
     "@lat.md/embed-minilm-fp16": "0.1.1",
-    "@plebeiantech/lat.md-core": "0.13.4-fork.1",
-    "@lat.md/stemmer": "0.1.0"
+    "@lat.md/stemmer": "0.1.0",
+    "@plebeiantech/lat.md-core": "0.13.4-fork.2"
   },
   "scripts": {
     "build": "tsc && tsx scripts/fork-vendor-ui-server.ts && pnpm build:view",