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

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