npm - @mfittko/repo-wiki - Versions diffs - 0.2.1 - Mend

@mfittko/repo-wiki 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (190) hide show

package/.llmwiki/schema.md +107 -0
package/AGENTS.md +42 -0
package/CHANGELOG.md +91 -0
package/LICENSE +21 -0
package/README.md +254 -0
package/dist/bin/repo-wiki.d.ts +2 -0
package/dist/bin/repo-wiki.js +7 -0
package/dist/bin/repo-wiki.js.map +1 -0
package/dist/src/cli.d.ts +1 -0
package/dist/src/cli.js +404 -0
package/dist/src/cli.js.map +1 -0
package/dist/src/compiler.d.ts +55 -0
package/dist/src/compiler.js +2046 -0
package/dist/src/compiler.js.map +1 -0
package/dist/src/config.d.ts +63 -0
package/dist/src/config.js +86 -0
package/dist/src/config.js.map +1 -0
package/dist/src/context-assembler.d.ts +68 -0
package/dist/src/context-assembler.js +378 -0
package/dist/src/context-assembler.js.map +1 -0
package/dist/src/data-model-signals.d.ts +1 -0
package/dist/src/data-model-signals.js +13 -0
package/dist/src/data-model-signals.js.map +1 -0
package/dist/src/docs-ingestor.d.ts +138 -0
package/dist/src/docs-ingestor.js +844 -0
package/dist/src/docs-ingestor.js.map +1 -0
package/dist/src/docs-linter.d.ts +14 -0
package/dist/src/docs-linter.js +164 -0
package/dist/src/docs-linter.js.map +1 -0
package/dist/src/docs-validation.d.ts +36 -0
package/dist/src/docs-validation.js +297 -0
package/dist/src/docs-validation.js.map +1 -0
package/dist/src/extractors.d.ts +50 -0
package/dist/src/extractors.js +2275 -0
package/dist/src/extractors.js.map +1 -0
package/dist/src/frontmatter.d.ts +46 -0
package/dist/src/frontmatter.js +377 -0
package/dist/src/frontmatter.js.map +1 -0
package/dist/src/index.d.ts +26 -0
package/dist/src/index.js +18 -0
package/dist/src/index.js.map +1 -0
package/dist/src/init.d.ts +12 -0
package/dist/src/init.js +121 -0
package/dist/src/init.js.map +1 -0
package/dist/src/language.d.ts +2 -0
package/dist/src/language.js +62 -0
package/dist/src/language.js.map +1 -0
package/dist/src/linter.d.ts +33 -0
package/dist/src/linter.js +398 -0
package/dist/src/linter.js.map +1 -0
package/dist/src/llm-provider.d.ts +267 -0
package/dist/src/llm-provider.js +474 -0
package/dist/src/llm-provider.js.map +1 -0
package/dist/src/page-ownership.d.ts +38 -0
package/dist/src/page-ownership.js +96 -0
package/dist/src/page-ownership.js.map +1 -0
package/dist/src/planner.d.ts +55 -0
package/dist/src/planner.js +422 -0
package/dist/src/planner.js.map +1 -0
package/dist/src/prompts.d.ts +103 -0
package/dist/src/prompts.js +344 -0
package/dist/src/prompts.js.map +1 -0
package/dist/src/publisher.d.ts +68 -0
package/dist/src/publisher.js +662 -0
package/dist/src/publisher.js.map +1 -0
package/dist/src/repository-analysis.d.ts +88 -0
package/dist/src/repository-analysis.js +485 -0
package/dist/src/repository-analysis.js.map +1 -0
package/dist/src/scanner.d.ts +122 -0
package/dist/src/scanner.js +309 -0
package/dist/src/scanner.js.map +1 -0
package/dist/src/search.d.ts +71 -0
package/dist/src/search.js +410 -0
package/dist/src/search.js.map +1 -0
package/dist/src/secret-patterns.d.ts +3 -0
package/dist/src/secret-patterns.js +14 -0
package/dist/src/secret-patterns.js.map +1 -0
package/dist/src/utils/args.d.ts +2 -0
package/dist/src/utils/args.js +19 -0
package/dist/src/utils/args.js.map +1 -0
package/dist/src/utils/dotenv.d.ts +7 -0
package/dist/src/utils/dotenv.js +73 -0
package/dist/src/utils/dotenv.js.map +1 -0
package/dist/src/utils/fs.d.ts +22 -0
package/dist/src/utils/fs.js +83 -0
package/dist/src/utils/fs.js.map +1 -0
package/dist/src/utils/git.d.ts +13 -0
package/dist/src/utils/git.js +39 -0
package/dist/src/utils/git.js.map +1 -0
package/dist/src/wiki-graph.d.ts +74 -0
package/dist/src/wiki-graph.js +335 -0
package/dist/src/wiki-graph.js.map +1 -0
package/dist/src/wiki-patch.d.ts +152 -0
package/dist/src/wiki-patch.js +489 -0
package/dist/src/wiki-patch.js.map +1 -0
package/dist/src/wiki-query.d.ts +63 -0
package/dist/src/wiki-query.js +255 -0
package/dist/src/wiki-query.js.map +1 -0
package/dist/test/cli.test.d.ts +1 -0
package/dist/test/cli.test.js +514 -0
package/dist/test/cli.test.js.map +1 -0
package/dist/test/compiler-eval.test.d.ts +1 -0
package/dist/test/compiler-eval.test.js +234 -0
package/dist/test/compiler-eval.test.js.map +1 -0
package/dist/test/compiler.test.d.ts +1 -0
package/dist/test/compiler.test.js +2537 -0
package/dist/test/compiler.test.js.map +1 -0
package/dist/test/context-assembler.test.d.ts +1 -0
package/dist/test/context-assembler.test.js +379 -0
package/dist/test/context-assembler.test.js.map +1 -0
package/dist/test/docs-linter.test.d.ts +1 -0
package/dist/test/docs-linter.test.js +900 -0
package/dist/test/docs-linter.test.js.map +1 -0
package/dist/test/dotenv.test.d.ts +1 -0
package/dist/test/dotenv.test.js +77 -0
package/dist/test/dotenv.test.js.map +1 -0
package/dist/test/extractors-go.test.d.ts +1 -0
package/dist/test/extractors-go.test.js +393 -0
package/dist/test/extractors-go.test.js.map +1 -0
package/dist/test/extractors-rust.test.d.ts +1 -0
package/dist/test/extractors-rust.test.js +219 -0
package/dist/test/extractors-rust.test.js.map +1 -0
package/dist/test/extractors-utils.test.d.ts +1 -0
package/dist/test/extractors-utils.test.js +786 -0
package/dist/test/extractors-utils.test.js.map +1 -0
package/dist/test/fixtures/compiler-e2e/basic-node-service/repo/infra/deploy.d.ts +1 -0
package/dist/test/fixtures/compiler-e2e/basic-node-service/repo/infra/deploy.js +4 -0
package/dist/test/fixtures/compiler-e2e/basic-node-service/repo/infra/deploy.js.map +1 -0
package/dist/test/frontmatter.test.d.ts +1 -0
package/dist/test/frontmatter.test.js +287 -0
package/dist/test/frontmatter.test.js.map +1 -0
package/dist/test/init-planner.test.d.ts +1 -0
package/dist/test/init-planner.test.js +688 -0
package/dist/test/init-planner.test.js.map +1 -0
package/dist/test/linter.test.d.ts +1 -0
package/dist/test/linter.test.js +426 -0
package/dist/test/linter.test.js.map +1 -0
package/dist/test/llm-provider.test.d.ts +1 -0
package/dist/test/llm-provider.test.js +783 -0
package/dist/test/llm-provider.test.js.map +1 -0
package/dist/test/page-ownership.test.d.ts +1 -0
package/dist/test/page-ownership.test.js +247 -0
package/dist/test/page-ownership.test.js.map +1 -0
package/dist/test/publisher.test.d.ts +1 -0
package/dist/test/publisher.test.js +1297 -0
package/dist/test/publisher.test.js.map +1 -0
package/dist/test/repository-analysis.test.d.ts +1 -0
package/dist/test/repository-analysis.test.js +182 -0
package/dist/test/repository-analysis.test.js.map +1 -0
package/dist/test/run-compiled-tests.d.ts +1 -0
package/dist/test/run-compiled-tests.js +48 -0
package/dist/test/run-compiled-tests.js.map +1 -0
package/dist/test/scanner.test.d.ts +1 -0
package/dist/test/scanner.test.js +551 -0
package/dist/test/scanner.test.js.map +1 -0
package/dist/test/search.test.d.ts +1 -0
package/dist/test/search.test.js +92 -0
package/dist/test/search.test.js.map +1 -0
package/dist/test/update-changelog.test.d.ts +1 -0
package/dist/test/update-changelog.test.js +125 -0
package/dist/test/update-changelog.test.js.map +1 -0
package/dist/test/wiki-graph.test.d.ts +1 -0
package/dist/test/wiki-graph.test.js +164 -0
package/dist/test/wiki-graph.test.js.map +1 -0
package/dist/test/wiki-patch.test.d.ts +1 -0
package/dist/test/wiki-patch.test.js +610 -0
package/dist/test/wiki-patch.test.js.map +1 -0
package/dist/test/wiki-query.test.d.ts +1 -0
package/dist/test/wiki-query.test.js +163 -0
package/dist/test/wiki-query.test.js.map +1 -0
package/docs/PLAN.md +993 -0
package/docs/WHY.md +61 -0
package/docs/plans/agent-integration.md +85 -0
package/docs/plans/ci-publishing.md +111 -0
package/docs/plans/doc-validation.md +92 -0
package/docs/plans/github-action.md +113 -0
package/docs/plans/incremental-mode.md +98 -0
package/docs/plans/karpathy-llm-wiki-alignment.md +84 -0
package/docs/plans/llm-compiler.md +160 -0
package/docs/plans/production-scanner.md +104 -0
package/docs/plans/query-and-file-back.md +103 -0
package/docs/plans/search-index.md +118 -0
package/docs/plans/trust-hardening.md +74 -0
package/docs/plans/wiki-graph.md +183 -0
package/docs/plans/wiki-health.md +76 -0
package/package.json +83 -0
package/prompts/compiler.md +16 -0
package/prompts/lint.md +18 -0
package/prompts/page-templates.md +25 -0
package/skills/repo-wiki-cli/SKILL.md +139 -0

package/dist/src/publisher.js ADDED Viewed

@@ -0,0 +1,662 @@
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileExists } from './utils/fs.js';
+import { getGitStatus, runGit } from './utils/git.js';
+import { applyFrontmatterPolicy, stripFrontmatter } from './frontmatter.js';
+export const PUBLISH_TARGETS = ['github-wiki', 'github-pages'];
+/**
+ * Marker embedded in every support file generated by repo-wiki for GitHub Pages.
+ * Files that contain this marker are regenerated on each publish so they stay
+ * up-to-date with new layout / navigation features. Files without this marker
+ * are treated as user-customized and are never overwritten.
+ */
+const REPO_WIKI_GENERATED_MARKER = 'repo-wiki-generated: regenerated on each publish';
+const REPO_WIKI_GENERATED_HTML_COMMENT = `<!-- ${REPO_WIKI_GENERATED_MARKER} -->`;
+const REPO_WIKI_GENERATED_YAML_COMMENT = `# ${REPO_WIKI_GENERATED_MARKER}`;
+/** Returns true if the file exists and was written by repo-wiki. */
+async function isRepoWikiGeneratedFile(filePath, kind) {
+    try {
+        const content = await fs.readFile(filePath, 'utf8');
+        return isRepoWikiGeneratedContent(content, kind);
+    }
+    catch {
+        return false;
+    }
+}
+function isRepoWikiGeneratedContent(content, kind) {
+    if (content.includes(REPO_WIKI_GENERATED_MARKER)) {
+        return true;
+    }
+    switch (kind) {
+        case 'config':
+            return isLegacyRepoWikiPagesConfig(content);
+        case 'layout':
+            return isLegacyRepoWikiPagesLayout(content);
+        default:
+            return false;
+    }
+}
+function isLegacyRepoWikiPagesConfig(content) {
+    return /^defaults:\n  - scope:\n      path: ""\n    values:\n      layout: "repo-wiki"\n(?:wiki_pages_dir: "[^"\n]*"\n)?$/.test(content);
+}
+function isLegacyRepoWikiPagesLayout(content) {
+    return content.startsWith('<!doctype html>\n<html lang="en">\n')
+        && content.includes('<title>{% if page.title %}{{ page.title | escape }}{% else %}{{ page.name | replace: \'.md\', \'\' | escape }}{% endif %}')
+        && content.includes('import mermaid from \'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs\';')
+        && content.includes('document.querySelectorAll(\'pre > code.language-mermaid\')')
+        && (content.includes('<main>\n    {{ content }}\n  </main>')
+            || content.includes('{% assign _rp = page.path %}') && content.includes('{% include wiki_nav.html %}'));
+}
+export async function publishWiki({ wikiDir, remote, branch, target = 'github-wiki', pagesPath = '.', message, dryRun = false, frontmatterPolicy, gitUserName = process.env.LLMWIKI_GIT_USER_NAME || 'repo-wiki-bot', gitUserEmail = process.env.LLMWIKI_GIT_USER_EMAIL || 'repo-wiki-bot@users.noreply.github.com' }) {
+    const absoluteWikiDir = path.resolve(wikiDir || '.llmwiki/wiki');
+    const publishTarget = target;
+    const publishRemote = resolvePublishRemote(publishTarget, remote);
+    const summaryRemote = sanitizeRemote(publishRemote);
+    const publishBranch = branch || defaultBranchForTarget(publishTarget);
+    const publishFrontmatterPolicy = frontmatterPolicy || defaultFrontmatterPolicyForTarget(publishTarget);
+    const resolvedPublishPath = resolvePublishPath(publishTarget, pagesPath);
+    assertSafeGitArgument(publishBranch, 'branch');
+    assertSafeGitArgument(publishRemote, 'remote');
+    if (!await fileExists(absoluteWikiDir)) {
+        throw new Error(`Wiki directory does not exist: ${absoluteWikiDir}`);
+    }
+    const markdownFileCount = await countMarkdownFiles(absoluteWikiDir);
+    if (dryRun) {
+        return {
+            summary: {
+                status: 'dry-run',
+                wikiDir: absoluteWikiDir,
+                remote: summaryRemote,
+                branch: publishBranch,
+                target: publishTarget,
+                path: resolvedPublishPath.relative,
+                pages: markdownFileCount,
+                frontmatterPolicy: publishFrontmatterPolicy
+            }
+        };
+    }
+    if (!publishRemote) {
+        return {
+            summary: {
+                status: 'skipped-no-remote',
+                wikiDir: absoluteWikiDir,
+                remote: null,
+                branch: publishBranch,
+                target: publishTarget,
+                path: resolvedPublishPath.relative,
+                pages: markdownFileCount,
+                frontmatterPolicy: publishFrontmatterPolicy,
+                next_step: publishTarget === 'github-pages'
+                    ? 'Set LLMWIKI_PUBLISH_REMOTE or pass --remote with a target repository URL, for example OWNER/REPO.git.'
+                    : 'Set LLMWIKI_PUBLISH_REMOTE, GITHUB_WIKI_REMOTE, or pass --remote with an OWNER/REPO.wiki.git URL.'
+            }
+        };
+    }
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'repo-wiki-publish-'));
+    const checkoutDir = path.join(tempRoot, 'wiki');
+    const commitMessage = message || `Compile repository wiki ${new Date().toISOString()}`;
+    let cloned = false;
+    try {
+        try {
+            await runGit(['clone', '--branch', publishBranch, '--', publishRemote, checkoutDir]);
+            cloned = true;
+        }
+        catch (error) {
+            if (!isCloneFallbackError(error)) {
+                throw error;
+            }
+            await fs.mkdir(checkoutDir, { recursive: true });
+            await runGit(['init'], { cwd: checkoutDir });
+            await runGit(['remote', 'add', 'origin', publishRemote], { cwd: checkoutDir });
+        }
+        const publishDir = resolvedPublishPath.absoluteResolver(checkoutDir);
+        assertPublishPathContained(checkoutDir, publishDir);
+        if (publishTarget === 'github-pages') {
+            await cleanGeneratedMarkdown(publishDir);
+        }
+        else {
+            await cleanPublishPath(checkoutDir, publishDir);
+        }
+        await copyGeneratedWiki(absoluteWikiDir, publishDir, publishFrontmatterPolicy, publishTarget === 'github-pages');
+        if (publishTarget === 'github-pages') {
+            await ensurePagesSiteSupport(checkoutDir, publishDir, resolvedPublishPath.relative);
+        }
+        await runGit(['config', 'user.name', gitUserName], { cwd: checkoutDir });
+        await runGit(['config', 'user.email', gitUserEmail], { cwd: checkoutDir });
+        await runGit(['add', '.'], { cwd: checkoutDir });
+        const status = await getGitStatus(checkoutDir);
+        if (!status) {
+            return {
+                summary: {
+                    status: 'no-changes',
+                    wikiDir: absoluteWikiDir,
+                    remote: summaryRemote,
+                    branch: publishBranch,
+                    target: publishTarget,
+                    path: resolvedPublishPath.relative,
+                    pages: markdownFileCount,
+                    frontmatterPolicy: publishFrontmatterPolicy,
+                    cloned
+                }
+            };
+        }
+        await runGit(['commit', '-m', commitMessage], { cwd: checkoutDir });
+        await runGit(['push', 'origin', `HEAD:${publishBranch}`], { cwd: checkoutDir });
+        return {
+            summary: {
+                status: 'published',
+                wikiDir: absoluteWikiDir,
+                remote: summaryRemote,
+                branch: publishBranch,
+                target: publishTarget,
+                path: resolvedPublishPath.relative,
+                pages: markdownFileCount,
+                frontmatterPolicy: publishFrontmatterPolicy,
+                cloned
+            }
+        };
+    }
+    catch (error) {
+        throw redactGitError(error, publishRemote);
+    }
+    finally {
+        await fs.rm(tempRoot, { recursive: true, force: true });
+    }
+}
+function sanitizeRemote(remote) {
+    if (!remote) {
+        return null;
+    }
+    return remote.replace(/([a-z][a-z\d+.-]*:\/\/)([^/?#@]+):([^/?#@]+)@/gi, '$1***:***@')
+        .replace(/([a-z][a-z\d+.-]*:\/\/)([^/?#@:]+)@/gi, '$1***@');
+}
+function redactGitError(error, remote) {
+    const redactedRemote = sanitizeRemote(remote);
+    const redact = (value) => {
+        if (typeof value !== 'string') {
+            return value;
+        }
+        const sanitized = sanitizeRemote(value) || value;
+        return remote && redactedRemote ? sanitized.split(remote).join(redactedRemote) : sanitized;
+    };
+    if (!(error instanceof Error)) {
+        return new Error(String(redact(error)));
+    }
+    const redactedError = new Error(String(redact(error.message)));
+    redactedError.name = error.name;
+    redactedError.stack = typeof error.stack === 'string' ? String(redact(error.stack)) : error.stack;
+    for (const key of ['code', 'signal', 'stdout', 'stderr', 'cmd']) {
+        const value = error[key];
+        if (value !== undefined) {
+            redactedError[key] = redact(value);
+        }
+    }
+    return redactedError;
+}
+function isCloneFallbackError(error) {
+    const details = [
+        error instanceof Error ? error.message : '',
+        typeof error?.stderr === 'string' ? error.stderr : ''
+    ].join('\n').toLowerCase();
+    return details.includes('remote branch') && details.includes('not found')
+        || details.includes('repository') && details.includes('not found')
+        || details.includes('repository') && details.includes('does not exist')
+        || details.includes('does not appear to be a git repository');
+}
+async function cleanCheckout(targetDir) {
+    await fs.mkdir(targetDir, { recursive: true });
+    const entries = await fs.readdir(targetDir, { withFileTypes: true });
+    await Promise.all(entries
+        .filter((entry) => entry.name !== '.git')
+        .map((entry) => fs.rm(path.join(targetDir, entry.name), { recursive: true, force: true })));
+}
+async function cleanPublishPath(checkoutDir, publishDir) {
+    if (checkoutDir === publishDir) {
+        await cleanCheckout(checkoutDir);
+        return;
+    }
+    await fs.rm(publishDir, { recursive: true, force: true });
+    await fs.mkdir(publishDir, { recursive: true });
+}
+async function cleanGeneratedMarkdown(publishDir) {
+    await fs.mkdir(publishDir, { recursive: true });
+    const entries = await fs.readdir(publishDir, { withFileTypes: true });
+    await Promise.all(entries.map(async (entry) => {
+        if (isReservedPublishEntry(entry.name)) {
+            return;
+        }
+        const entryPath = path.join(publishDir, entry.name);
+        if (entry.isDirectory()) {
+            await cleanGeneratedMarkdown(entryPath);
+            return;
+        }
+        if (entry.isFile() && entry.name.endsWith('.md') && !isPreservedPagesMarkdown(entry.name)) {
+            await fs.rm(entryPath, { force: true });
+        }
+    }));
+}
+function isReservedPublishEntry(name) {
+    return name === '.git' || name === '.github' || name === '_layouts';
+}
+function isPreservedPagesMarkdown(name) {
+    return name === 'index.md' || name === 'Navigation.md';
+}
+async function copyGeneratedWiki(sourceDir, targetDir, frontmatterPolicy, isPages = false) {
+    await fs.mkdir(targetDir, { recursive: true });
+    const entries = await fs.readdir(sourceDir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (entry.name === '.git') {
+            continue;
+        }
+        const source = path.join(sourceDir, entry.name);
+        const target = path.join(targetDir, entry.name);
+        if (entry.isSymbolicLink()) {
+            await copySymlink(source, target);
+        }
+        else if (entry.isDirectory()) {
+            await copyGeneratedWiki(source, target, frontmatterPolicy, isPages);
+        }
+        else if (entry.isFile() && entry.name.endsWith('.md')) {
+            const content = await fs.readFile(source, 'utf8');
+            const transformed = applyFrontmatterPolicy(content, frontmatterPolicy);
+            const finalContent = isPages ? rewriteInternalWikiLinks(transformed) : transformed;
+            await fs.writeFile(target, finalContent, 'utf8');
+        }
+        else if (entry.isFile()) {
+            await fs.copyFile(source, target);
+        }
+    }
+}
+async function copySymlink(source, target) {
+    const linkTarget = await fs.readlink(source);
+    await fs.rm(target, { recursive: true, force: true });
+    await fs.symlink(linkTarget, target);
+}
+async function countMarkdownFiles(wikiDir) {
+    const entries = await fs.readdir(wikiDir, { withFileTypes: true });
+    const nestedCounts = await Promise.all(entries.map(async (entry) => {
+        const entryPath = path.join(wikiDir, entry.name);
+        if (entry.isDirectory()) {
+            return countMarkdownFiles(entryPath);
+        }
+        return entry.isFile() && entry.name.endsWith('.md') ? 1 : 0;
+    }));
+    return nestedCounts.reduce((total, count) => total + count, 0);
+}
+function resolvePublishRemote(target, remote) {
+    if (remote || process.env.LLMWIKI_PUBLISH_REMOTE) {
+        return remote || process.env.LLMWIKI_PUBLISH_REMOTE;
+    }
+    return target === 'github-wiki' ? process.env.GITHUB_WIKI_REMOTE : undefined;
+}
+function defaultBranchForTarget(target) {
+    return target === 'github-pages' ? 'gh-pages' : 'master';
+}
+export function defaultFrontmatterPolicyForTarget(target) {
+    return target === 'github-wiki' ? 'provenance' : 'preserve';
+}
+function assertSafeGitArgument(value, label) {
+    if (!value) {
+        return;
+    }
+    if (/^[\s-]/.test(value)) {
+        throw new Error(`Publish ${label} must not start with whitespace or "-".`);
+    }
+    if (/[\u0000\r\n]/.test(value)) {
+        throw new Error(`Publish ${label} contains unsupported control characters.`);
+    }
+}
+function resolvePublishPath(target, pagesPath) {
+    const rawPath = target === 'github-pages' ? (pagesPath || '.').trim() || '.' : '.';
+    if (/[\u0000\r\n]/.test(rawPath)) {
+        throw new Error('Publish path contains unsupported control characters.');
+    }
+    const pathForSegments = rawPath.replace(/\\/g, '/');
+    if (path.isAbsolute(pathForSegments) || path.posix.isAbsolute(pathForSegments)) {
+        throw new Error(`Publish path must be relative: ${rawPath}`);
+    }
+    const segments = pathForSegments.split('/').filter(Boolean);
+    if (segments.includes('..')) {
+        throw new Error(`Publish path must not contain ".." path segments: ${rawPath}`);
+    }
+    if (segments.some((segment) => segment.toLowerCase() === '.git')) {
+        throw new Error(`Publish path must not target reserved .git paths: ${rawPath}`);
+    }
+    const normalized = path.posix.normalize(pathForSegments).replace(/^\.\/+/, '') || '.';
+    return {
+        relative: normalized,
+        absoluteResolver: (checkoutDir) => path.resolve(checkoutDir, normalized)
+    };
+}
+function assertPublishPathContained(checkoutDir, publishDir) {
+    const relative = path.relative(checkoutDir, publishDir);
+    if (relative === '' || (!path.isAbsolute(relative) && relative !== '..' && !relative.startsWith(`..${path.sep}`))) {
+        return;
+    }
+    throw new Error(`Publish path must stay inside checkout: ${publishDir}`);
+}
+async function ensurePagesSiteSupport(siteRootDir, publishDir, pagesPath) {
+    await ensurePagesEntryAndNavigation(publishDir);
+    await ensurePagesNavInclude(siteRootDir, publishDir);
+    await ensurePagesMermaidSupport(siteRootDir, pagesPath);
+}
+async function ensurePagesEntryAndNavigation(publishDir) {
+    const homePath = path.join(publishDir, 'Home.md');
+    const indexPath = path.join(publishDir, 'index.md');
+    if (await fileExists(homePath) && !await fileExists(indexPath)) {
+        const homeContent = await fs.readFile(homePath, 'utf8');
+        await fs.writeFile(indexPath, homeContent, 'utf8');
+    }
+    const sidebarPath = path.join(publishDir, '_Sidebar.md');
+    const navigationPath = path.join(publishDir, 'Navigation.md');
+    if (await fileExists(sidebarPath) && !await fileExists(navigationPath)) {
+        const sidebarContent = await fs.readFile(sidebarPath, 'utf8');
+        await fs.writeFile(navigationPath, rewritePagesNavigationLinks(sidebarContent), 'utf8');
+    }
+}
+function rewritePagesNavigationLinks(content) {
+    return content.replace(/(?<!!)(\[[^\]]+\]\()([^\s)]+)(\))/g, (_match, prefix, target, suffix) => {
+        const rewritten = rewritePagesNavigationTarget(target);
+        return `${prefix}${rewritten}${suffix}`;
+    });
+}
+function rewritePagesNavigationTarget(target) {
+    if (!target || target.startsWith('#')) {
+        return target;
+    }
+    if (/^[a-z][a-z\d+.-]*:/i.test(target) || target.startsWith('//') || target.startsWith('/')) {
+        return target;
+    }
+    const [pathPart, hash = ''] = target.split('#', 2);
+    if (!pathPart || /[/?]/.test(pathPart)) {
+        return target;
+    }
+    if (path.extname(pathPart).toLowerCase() === '.md') {
+        return `${pathPart.slice(0, -3)}.html${hash ? `#${hash}` : ''}`;
+    }
+    if (path.extname(pathPart)) {
+        return target;
+    }
+    return `${pathPart}.html${hash ? `#${hash}` : ''}`;
+}
+async function ensurePagesMermaidSupport(siteRootDir, pagesPath) {
+    const configPath = path.join(siteRootDir, '_config.yml');
+    // Regenerate if new, marked as repo-wiki generated, or matching known legacy repo-wiki defaults.
+    // Preserve markerless files that do not match those legacy signatures as user-customized.
+    if (!await fileExists(configPath) || await isRepoWikiGeneratedFile(configPath, 'config')) {
+        await fs.writeFile(configPath, buildPagesConfig(pagesPath), 'utf8');
+    }
+    const layoutDir = path.join(siteRootDir, '_layouts');
+    const layoutPath = path.join(layoutDir, 'repo-wiki.html');
+    if (!await fileExists(layoutPath) || await isRepoWikiGeneratedFile(layoutPath, 'layout')) {
+        await fs.mkdir(layoutDir, { recursive: true });
+        await fs.writeFile(layoutPath, PAGES_LAYOUT, 'utf8');
+    }
+}
+function buildPagesConfig(pagesPath) {
+    const normalized = pagesPath === '.' ? '' : pagesPath;
+    const base = `${REPO_WIKI_GENERATED_YAML_COMMENT}\ndefaults:\n  - scope:\n      path: ""\n    values:\n      layout: "repo-wiki"\n`;
+    if (!normalized) {
+        return base;
+    }
+    // YAML-escape: backslashes first, then double-quotes to prevent YAML injection
+    const escaped = normalized.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    return `${base}wiki_pages_dir: "${escaped}"\n`;
+}
+async function ensurePagesNavInclude(siteRootDir, publishDir) {
+    const includesDir = path.join(siteRootDir, '_includes');
+    const navIncludePath = path.join(includesDir, 'wiki_nav.html');
+    // Preserve every markerless existing nav include as user-customized. Even markup
+    // resembling an older generated nav may have been edited by hand, so only files
+    // with the current repo-wiki marker are safe to refresh automatically.
+    if (await fileExists(navIncludePath) && !await isRepoWikiGeneratedFile(navIncludePath)) {
+        return;
+    }
+    let navBody = '';
+    const sidebarPath = path.join(publishDir, '_Sidebar.md');
+    const navMdPath = path.join(publishDir, 'Navigation.md');
+    if (await fileExists(sidebarPath)) {
+        navBody = parseSidebarToNavHtml(await fs.readFile(sidebarPath, 'utf8'));
+    }
+    else if (await fileExists(navMdPath)) {
+        navBody = parseSidebarToNavHtml(await fs.readFile(navMdPath, 'utf8'));
+    }
+    await fs.mkdir(includesDir, { recursive: true });
+    const navContent = navBody ? `${REPO_WIKI_GENERATED_HTML_COMMENT}\n${navBody}` : REPO_WIKI_GENERATED_HTML_COMMENT;
+    await fs.writeFile(navIncludePath, navContent, 'utf8');
+}
+/**
+ * Rewrite internal wiki-style links in markdown content so they use the
+ * published `.html` page URLs expected under GitHub Pages.
+ *
+ * Rules:
+ * - `[text](PageName)` → `[text](PageName.html)` (bare page-name link)
+ * - `[text](./Page.md)` → `[text](Page.html)` (normalize leading `./` and convert markdown source links)
+ * - External URLs, `mailto:`, anchor-only, and known asset extensions are left unchanged.
+ *
+ * Quantifiers are bounded to prevent polynomial backtracking on adversarial input.
+ */
+export function rewriteInternalWikiLinks(content) {
+    return content.replace(/\[([^\]\n]{0,2048})\]\(([^)\n]{1,2048})\)/g, (match, text, href, offset) => {
+        if (offset > 0 && content[offset - 1] === '!') {
+            return match;
+        }
+        return `[${text}](${normalizeWikiHref(href)})`;
+    });
+}
+function isExternalOrAnchorHref(href) {
+    return /^(?:https?:|mailto:|ftp:|\/\/|#)/i.test(href.trim());
+}
+function normalizeWikiHref(href) {
+    const normalizedHref = href.trim();
+    // Reject unsafe URI schemes after trimming surrounding whitespace so leading
+    // spaces/tabs cannot bypass scheme detection in downstream markdown/HTML.
+    if (/^(?:javascript:|data:|vbscript:|blob:|about:)/i.test(normalizedHref)) {
+        return '#';
+    }
+    // Leave external links, mailto, anchor-only, and protocol-relative links unchanged
+    if (isExternalOrAnchorHref(normalizedHref)) {
+        return normalizedHref;
+    }
+    // Split off query string and fragment before applying extension logic
+    const hashIndex = normalizedHref.indexOf('#');
+    const queryIndex = normalizedHref.indexOf('?');
+    let separatorIndex;
+    if (queryIndex === -1) {
+        separatorIndex = hashIndex;
+    }
+    else if (hashIndex === -1) {
+        separatorIndex = queryIndex;
+    }
+    else {
+        separatorIndex = Math.min(queryIndex, hashIndex);
+    }
+    const pathPart = separatorIndex === -1 ? normalizedHref : normalizedHref.slice(0, separatorIndex);
+    const suffix = separatorIndex === -1 ? '' : normalizedHref.slice(separatorIndex);
+    // Leave known non-markdown asset extensions unchanged
+    if (/\.(?:png|jpe?g|gif|svg|webp|ico|pdf|txt|json|ya?ml|html?|css|js|ts)$/i.test(pathPart)) {
+        return normalizedHref;
+    }
+    // Normalize leading ./
+    let normalized = pathPart.replace(/^\.\//, '');
+    // Convert markdown source links to published HTML page URLs.
+    if (/\.md$/i.test(normalized)) {
+        normalized = normalized.replace(/\.md$/i, '.html');
+    }
+    else if (normalized && !/\.[a-z]{1,10}$/i.test(normalized) && !normalized.endsWith('/')) {
+        normalized += '.html';
+    }
+    return normalized + suffix;
+}
+/**
+ * Convert `_Sidebar.md` or `Navigation.md` content into a Liquid/HTML navigation
+ * fragment suitable for use as a Jekyll `_includes/wiki_nav.html` file.
+ *
+ * Internal hrefs are prefixed with `{{ _base }}` so they resolve correctly
+ * regardless of the page's depth in the site tree. External links and
+ * anchor-only links are left without the prefix.
+ */
+function parseSidebarToNavHtml(content) {
+    const body = stripFrontmatter(content);
+    const lines = body.split('\n');
+    const parts = [];
+    let inList = false;
+    for (const line of lines) {
+        const headingMatch = /^#{1,4}\s+(.+)$/.exec(line);
+        if (headingMatch) {
+            if (inList) {
+                parts.push('</ul>');
+                inList = false;
+            }
+            parts.push(`<h4 class="nav-section">${escapeHtml(headingMatch[1].trim())}</h4>`);
+            continue;
+        }
+        const linkItemMatch = /^[ \t]*[-*+]\s+\[([^\]\n]{0,512})\]\(([^)\n]{0,512})\)/.exec(line);
+        if (linkItemMatch) {
+            if (!inList) {
+                parts.push('<ul>');
+                inList = true;
+            }
+            const text = escapeHtml(linkItemMatch[1]);
+            const rawHref = normalizeWikiHref(linkItemMatch[2]);
+            const isInternal = !isExternalOrAnchorHref(rawHref);
+            const escapedHref = escapeHtml(rawHref);
+            // Prefix internal links with {{ _base }} so they remain depth-relative.
+            // Jekyll evaluates the include in the layout's Liquid scope, so _base is available.
+            const href = isInternal ? `{{ _base }}${escapedHref}` : escapedHref;
+            parts.push(`<li><a href="${href}">${text}</a></li>`);
+            continue;
+        }
+        const plainItemMatch = /^[ \t]*[-*+]\s+(.+)$/.exec(line);
+        if (plainItemMatch) {
+            if (!inList) {
+                parts.push('<ul>');
+                inList = true;
+            }
+            parts.push(`<li>${escapeHtml(plainItemMatch[1].trim())}</li>`);
+        }
+    }
+    if (inList) {
+        parts.push('</ul>');
+    }
+    return parts.join('\n');
+}
+function escapeHtml(text) {
+    return text
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+const PAGES_LAYOUT = `<!doctype html>
+<!-- repo-wiki-generated: regenerated on each publish -->
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>{% if page.title %}{{ page.title | escape }}{% else %}{{ page.name | replace: '.md', '' | escape }}{% endif %} &mdash; Wiki</title>
+  <style>
+    *, *::before, *::after { box-sizing: border-box; }
+    body { color: #24292f; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; line-height: 1.5; margin: 0; }
+    .layout { display: flex; min-height: 100vh; }
+    .sidebar { background: #f6f8fa; border-right: 1px solid #d0d7de; flex-shrink: 0; overflow-y: auto; padding: 1rem; width: 220px; }
+    .sidebar-title { font-size: 0.875rem; font-weight: 600; margin-bottom: 0.5rem; }
+    .sidebar-title a { color: #24292f; text-decoration: none; }
+    .sidebar-title a:hover { color: #0969da; }
+    .site-nav ul { list-style: none; margin: 0; padding: 0; }
+    .site-nav li { margin: 0.15rem 0; }
+    .site-nav a { color: #0969da; font-size: 0.875rem; text-decoration: none; }
+    .site-nav a:hover { text-decoration: underline; }
+    .site-nav .nav-section { color: #57606a; font-size: 0.7rem; font-weight: 600; letter-spacing: 0.05em; margin: 0.75rem 0 0.25rem; text-transform: uppercase; }
+    .nav-divider { border: none; border-top: 1px solid #d0d7de; margin: 0.5rem 0; }
+    main { flex: 1; min-width: 0; max-width: 980px; padding: 2rem; }
+    .breadcrumb { color: #57606a; font-size: 0.875rem; margin-bottom: 1rem; }
+    .breadcrumb a { color: #0969da; text-decoration: none; }
+    .breadcrumb a:hover { text-decoration: underline; }
+    .page-metadata { background: #f6f8fa; border: 1px solid #d0d7de; border-radius: 6px; color: #57606a; font-size: 0.875rem; margin: 0 0 1.5rem; padding: 0.75rem 1rem; }
+    .page-metadata summary { color: #24292f; cursor: pointer; font-weight: 600; }
+    .page-metadata dl { display: grid; gap: 0.35rem 1rem; grid-template-columns: max-content minmax(0, 1fr); margin: 0.75rem 0 0; }
+    .page-metadata dt { color: #24292f; font-weight: 600; }
+    .page-metadata dd { margin: 0; min-width: 0; }
+    .page-metadata ul { margin: 0; padding-left: 1.25rem; }
+    .page-metadata code { color: #24292f; }
+    .back-link { border-top: 1px solid #d0d7de; color: #57606a; font-size: 0.875rem; margin-top: 2rem; padding-top: 1rem; }
+    .back-link a { color: #0969da; text-decoration: none; }
+    .back-link a:hover { text-decoration: underline; }
+    a { color: #0969da; text-decoration: none; }
+    a:hover { text-decoration: underline; }
+    pre { background: #f6f8fa; border-radius: 6px; overflow: auto; padding: 1rem; }
+    code { background: #f6f8fa; border-radius: 4px; padding: 0.1em 0.3em; }
+    pre code { background: transparent; padding: 0; }
+    table { border-collapse: collapse; display: block; overflow: auto; width: 100%; }
+    th, td { border: 1px solid #d0d7de; padding: 0.4rem 0.75rem; }
+    .mermaid { background: #fff; border: 1px solid #d0d7de; border-radius: 6px; margin: 1rem 0; padding: 1rem; }
+    @media (max-width: 768px) { .layout { flex-direction: column; } .sidebar { border-right: none; border-bottom: 1px solid #d0d7de; width: 100%; } }
+  </style>
+</head>
+<body>
+{% assign _rp = page.path %}{% assign _wd = site.wiki_pages_dir | default: '.' %}{% if _wd != '.' %}{% assign _wd_prefix = _wd | append: '/' %}{% assign _rp = _rp | remove_first: _wd_prefix %}{% endif %}{% assign _depth = _rp | split: '/' | size | minus: 1 %}{% assign _base = '' %}{% for _i in (1.._depth) %}{% assign _base = _base | append: '../' %}{% endfor %}
+  <div class="layout">
+    <aside class="sidebar">
+      <div class="sidebar-title"><a href="{{ _base }}Home.html">Wiki</a></div>
+      <nav class="site-nav" aria-label="Site navigation">
+        <h4 class="nav-section">Quick links</h4>
+        <ul>
+          <li><a href="{{ _base }}Home.html">Home</a></li>
+          <li><a href="{{ _base }}Index.html">Index</a></li>
+          <li><a href="{{ _base }}Architecture.html">Architecture</a></li>
+          <li><a href="{{ _base }}Agent-Context-Pack.html">Agent Context Pack</a></li>
+          <li><a href="{{ _base }}Build-Test-and-Run.html">Build, Test &amp; Run</a></li>
+          <li><a href="{{ _base }}Documentation-Debt-Report.html">Documentation Debt</a></li>
+        </ul>
+        <hr class="nav-divider">
+        {% include wiki_nav.html %}
+      </nav>
+    </aside>
+    <main>
+      {% assign _kind = page.kind | default: '' %}{% if _kind == 'module' %}
+      <nav class="breadcrumb" aria-label="Breadcrumb">
+        <a href="{{ _base }}Home.html">Home</a> &rsaquo;
+        <a href="{{ _base }}Index.html">Index</a> &rsaquo;
+        <span>{{ page.title | default: page.name | replace: '.md', '' | escape }}</span>
+      </nav>{% elsif _kind != '' and _kind != 'home' %}
+      <nav class="breadcrumb" aria-label="Breadcrumb">
+        <a href="{{ _base }}Home.html">Home</a> &rsaquo;
+        <span>{{ page.title | default: page.name | replace: '.md', '' | escape }}</span>
+      </nav>{% endif %}
+      {% if page.page_state or page.kind or page.confidence or page.claim_status or page.source_repo or page.source_commit or page.compiled_at or page.source_paths %}
+      <details class="page-metadata">
+        <summary>Page metadata</summary>
+        <dl>
+          {% if page.kind %}<dt>Kind</dt><dd>{{ page.kind | escape }}</dd>{% endif %}
+          {% if page.page_state %}<dt>State</dt><dd>{{ page.page_state | escape }}</dd>{% endif %}
+          {% if page.confidence %}<dt>Confidence</dt><dd>{{ page.confidence | escape }}</dd>{% endif %}
+          {% if page.claim_status %}<dt>Claim status</dt><dd>{{ page.claim_status | escape }}</dd>{% endif %}
+          {% if page.source_repo %}<dt>Source repo</dt><dd>{{ page.source_repo | escape }}</dd>{% endif %}
+          {% if page.source_commit %}<dt>Source commit</dt><dd><code>{{ page.source_commit | escape }}</code></dd>{% endif %}
+          {% if page.compiled_at %}<dt>Compiled at</dt><dd>{{ page.compiled_at | escape }}</dd>{% endif %}
+          {% if page.source_paths %}<dt>Source paths</dt><dd><ul>{% for source_path in page.source_paths %}<li><code>{{ source_path | escape }}</code></li>{% endfor %}</ul></dd>{% endif %}
+        </dl>
+      </details>
+      {% endif %}
+      {{ content }}
+      {% if _kind != 'home' %}<div class="back-link"><a href="{{ _base }}Index.html">&larr; Back to Index</a></div>{% endif %}
+    </main>
+  </div>
+  <script type="module">
+    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
+    mermaid.initialize({ startOnLoad: false, securityLevel: 'strict' });
+    const blocks = document.querySelectorAll('pre > code.language-mermaid');
+    blocks.forEach((block) => {
+      const container = document.createElement('div');
+      container.className = 'mermaid';
+      container.textContent = block.textContent || '';
+      block.parentElement?.replaceWith(container);
+    });
+    await mermaid.run({ nodes: document.querySelectorAll('.mermaid') });
+  </script>
+</body>
+</html>
+`;
+//# sourceMappingURL=publisher.js.map