svharness 0.8.0

package/dist/wiki/repowikiIndexer.js

@@ -0,0 +1,824 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REPOWIKI_LANG_ZH = exports.REPOWIKI_LANG_EN = void 0;
+exports.langRunForRepowikiTarget = langRunForRepowikiTarget;
+exports.runRepowikiIndex = runRepowikiIndex;
+exports.runRepowikiOutlineOnly = runRepowikiOutlineOnly;
+const crypto_1 = require("crypto");
+const fs_1 = require("fs");
+const fs = __importStar(require("fs/promises"));
+const path = __importStar(require("path"));
+const abort_1 = require("./abort");
+const openaiCompat_1 = require("./openaiCompat");
+const repowikiScanner_1 = require("./repowikiScanner");
+const repowikiCanonicalSections_1 = require("./repowikiCanonicalSections");
+const repowikiCheckpoint_1 = require("./repowikiCheckpoint");
+const repowikiGit_1 = require("./repowikiGit");
+const repowikiConfig_1 = require("./repowikiConfig");
+const repowikiStructureNav_1 = require("./repowikiStructureNav");
+const repowikiStructureNormalize_1 = require("./repowikiStructureNormalize");
+const repowikiMarkdownPost_1 = require("./repowikiMarkdownPost");
+const repowikiMetadataContent_1 = require("./repowikiMetadataContent");
+const repowikiMetadataJson_1 = require("./repowikiMetadataJson");
+const wikiStructureXml_1 = require("./wikiStructureXml");
+/** Canonical labels for outline + page generation (structure step uses `label`). */
+exports.REPOWIKI_LANG_EN = {
+    folder: "en",
+    label: "English (en)",
+};
+exports.REPOWIKI_LANG_ZH = {
+    folder: "zh",
+    label: "简体中文（zh-CN）",
+};
+function langRunForRepowikiTarget(target) {
+    return target === "en" ? exports.REPOWIKI_LANG_EN : exports.REPOWIKI_LANG_ZH;
+}
+/** When `languages` is omitted, generate Simplified Chinese only. */
+const DEFAULT_LANGS = [exports.REPOWIKI_LANG_ZH];
+/** AbortSignal that never aborts — used as default when caller passes nothing. */
+const NEVER_ABORT = new AbortController().signal;
+async function chatCompletionTextForIndex(signal, params) {
+    (0, abort_1.assertNotAborted)(signal);
+    const ac = new AbortController();
+    const onAbort = () => ac.abort();
+    signal.addEventListener("abort", onAbort, { once: true });
+    try {
+        const text = await (0, openaiCompat_1.chatCompletionText)({ ...params, signal: ac.signal });
+        (0, abort_1.assertNotAborted)(signal);
+        return text;
+    }
+    catch (e) {
+        if (signal.aborted || ac.signal.aborted || (0, openaiCompat_1.isFetchAbortError)(e)) {
+            throw new abort_1.WikiAbortError();
+        }
+        throw e;
+    }
+    finally {
+        signal.removeEventListener("abort", onAbort);
+    }
+}
+function normFsPosix(p) {
+    return path.normalize(p).replace(/\\/g, "/");
+}
+function invertFilesMap(files) {
+    const m = new Map();
+    if (!files)
+        return m;
+    for (const [pageId, rel] of Object.entries(files)) {
+        m.set(rel.replace(/\\/g, "/"), pageId);
+    }
+    return m;
+}
+async function pathExists(abs) {
+    try {
+        await fs.access(abs);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function structurePrompt(repoName, treeText, readmeChunk, structureLang, comprehensive) {
+    const zhOutlineExtra = structureLang.folder === "zh"
+        ? `
+
+【简体中文硬性要求 — 纲要步骤】凡是给人看的文字（仓库级 <title>/ <description>、每个 <section> 的 <title>、每个 <page> 的 <title> 与 <description>）必须全部是简体中文（zh-CN）。禁止使用英文句子或段落；仅路径、文件名、代码标识符/API 符号可保留英文。`
+        : "";
+    const enOutlineExtra = structureLang.folder === "en"
+        ? `
+
+【English hard requirement — outline step】All human-readable text in this XML (repo-level <title>/<description>, each <section>'s <title>, each <page>'s <title> and <description>) MUST be fluent English. Do not write Chinese, Japanese, or other non-English prose for those fields. Only code identifiers, filenames, paths, API symbols, and unavoidable proper nouns may stay non-English where appropriate.`
+        : "";
+    const sectionBlock = comprehensive
+        ? `Use **multiple** top-level \`<section>\` blocks under \`<sections>\`: **between 2 and 7** (inclusive). **Never** return only **one** section when the wiki has **two or more** pages — split topics into **distinct** sections (do **not** collapse everything into a single bucket named after the wiki title).
+Use **at most 7** sections total. For very small repos with only **one** page, **one** section is acceptable.
+Each section MUST have a **unique** \`id\` attribute (letters, digits, hyphens only — stable identifier).
+Each section's \`<title>\` MUST be **in the outline language** (${structureLang.label}), **repo-specific**, and suitable as a section heading (this becomes the subdirectory name under each language folder).
+**Filesystem folders** under the language directory are derived from each section \`<title>\` (slugified), **not** from \`id\`.
+Distribute pages across sections: each section's \`<pages>\` lists \`<page_ref>\` ids; use **at most ${wikiStructureXml_1.REPOWIKI_MAX_PAGES}** pages **total** across all sections.
+
+Return ONLY valid XML in this shape:
+
+<wiki_structure>
+  <title>[Overall title]</title>
+  <description>[Brief]</description>
+  <sections>
+    <section id="getting-started">
+      <title>[Section title in outline language]</title>
+      <pages>
+        <page_ref>page-1</page_ref>
+      </pages>
+      <subsections/>
+    </section>
+    <!-- more sections with unique ids -->
+  </sections>
+  <pages>
+    <page id="page-1">
+      <title>[Title]</title>
+      <description>[What this covers]</description>
+      <importance>high</importance>
+      <relevant_files>
+        <file_path>[repo-relative/path]</file_path>
+      </relevant_files>
+      <related_pages/>
+      <parent_section>getting-started</parent_section>
+    </page>
+  </pages>
+</wiki_structure>`
+        : `<wiki_structure>
+  <title>[Overall title]</title>
+  <description>[Brief]</description>
+  <pages>
+    <page id="page-1">
+      <title>[Title]</title>
+      <description>[What]</description>
+      <importance>high</importance>
+      <relevant_files>
+        <file_path>[path]</file_path>
+      </relevant_files>
+      <related_pages/>
+    </page>
+  </pages>
+</wiki_structure>`;
+    return `Analyze the repository "${repoName}" and propose a concise developer wiki outline.
+
+<file_tree>
+${treeText}
+</file_tree>
+
+<readme_excerpt>
+${readmeChunk.slice(0, 12_000)}
+</readme_excerpt>
+
+Target language for human-readable titles/descriptions ONLY in this outline step: ${structureLang.label}.${zhOutlineExtra}${enOutlineExtra}
+
+${sectionBlock}
+
+Rules:
+- Produce **at most ${wikiStructureXml_1.REPOWIKI_MAX_PAGES}** wiki pages total with **stable** ids \`page-1\`, \`page-2\`, …, \`page-${wikiStructureXml_1.REPOWIKI_MAX_PAGES}\` (use consecutive ids; fewer pages is OK).
+${comprehensive ? `- Every \`<page>\` MUST include \`<parent_section>\` with the **exact** \`id\` of the section that owns this page (the section whose \`<page_ref>\` lists this page id).\n- Each page id must appear in exactly one section's \`page_ref\` list.` : `- Without a \`<sections>\` block, every page is stored under **one** folder derived from the wiki \`<title>\`; omit \`<parent_section>\` or ignore it for paths.`}
+${comprehensive ? `- Each section \`<title>\` becomes a subdirectory name (slugified); keep titles concise and filesystem-friendly where possible.` : `- The wiki \`<title>\` alone determines that single subdirectory name (slugified).`}
+- Ensure \`relevant_files\` cite real paths from file_tree where possible (skip generated/vendor dirs).
+${comprehensive ? `- CRITICAL: Every tag must be closed. After \`<sections>\`, you MUST include one final \`<pages>...</pages>\` block containing every full \`<page id="...">...</page>\` with title, description, parent_section, and relevant_files. Section-level \`<pages>\` may only list \`<page_ref>\` — never omit the outer \`<page>\` definitions.` : `- CRITICAL: Every tag must be closed. Include a \`<pages>\` block listing every full \`<page id="...">...</page>\` with title, description, and relevant_files.`}
+- Return ONLY XML. No markdown fences. No HTML. Start with <wiki_structure> end </wiki_structure>.`;
+}
+function pageMarkdownPrompt(langFolder, langDescriptor, pageTopic, ctx) {
+    const zhExtra = langFolder === "zh"
+        ? `
+
+【简体中文硬性要求 — 正文】全部正文、各级标题（# / ## / ###）、表格单元格、Mermaid 与其它图中的说明文字一律使用简体中文（zh-CN）。禁止英文句子，除非直接引用代码、路径、标识符或 API 名称。`
+        : "";
+    const enExtra = langFolder === "en"
+        ? `
+
+【English hard requirement — body】All prose, headings (# / ## / ###), table cell text, and explanatory labels inside Mermaid/diagrams MUST be English. Do not write Chinese prose (or mixed-language explanations) unless you are quoting literal content from repo files/strings. Preserve non-English only in fenced code excerpts, paths, identifiers, and API symbols as they appear in the repo.`
+        : "";
+    const h1Rule = langFolder === "zh"
+        ? `2. Start with '# [title]' (the H1 must match the topic; for a zh-CN wiki, use Simplified Chinese for that title line).`
+        : langFolder === "en"
+            ? `2. Start with '# [title]' (the H1 must match the topic in English prose).`
+            : `2. Start with '# [title]' (the H1 must match the topic).`;
+    return `You write accurate technical Markdown documentation for developers.
+
+Output language: ${langDescriptor}.${zhExtra}${enExtra}
+
+Repository context bundled as tagged files:
+
+${ctx}
+
+Write ONE wiki page for topic: "${pageTopic}".
+
+Strict rules:
+1. Ground claims only in supplied files.
+${h1Rule}
+3. After the introduction (first paragraph or short opener) and **before** the first \`##\`, add a concise **table of contents**: a bullet or numbered list of links to the \`##\` sections that follow (use markdown links with anchors, e.g. \`[Section](#section-slug)\`, matching your real headings). **Omit this TOC** if the page is very short or only has a single \`##\` section (avoid a redundant mini-TOC).
+4. Use '##','###', tables, fenced code from files when helpful.
+5. Prefer Mermaid with \`\`\`mermaid diagrams using TOP-DOWN flow (\`graph TD\`, not LR).
+6. Where useful cite repository files on one line: \`Sources: path/to/file:line-range\` (comma-separated if multiple). Paths are repo-relative with \`/\` separators.
+
+If bundled files lack coverage, acknowledge gaps briefly — do not invent APIs.`;
+}
+function pageGenerationSystemPrompt(langFolder) {
+    if (langFolder === "zh") {
+        return "你是技术文档撰写者，只根据提供的 <file path=…> 摘录作答。Wiki 页的各级标题、正文、表格文字、图中的文字说明必须全部是简体中文（zh-CN）。除代码摘录、仓库路径与标识符/API 英文名外禁止使用英文 prose。";
+    }
+    if (langFolder === "en") {
+        return "You are a technical writer. Answer ONLY from bundled <file path=…> excerpts. The entire Markdown page MUST be English: headings, body, table text, diagram labels/explanations. Use non-English prose only inside literal code fences or when verbatim-quoting user-facing strings from the repository; identifiers, paths, and API symbols follow the codebase.";
+    }
+    return "You write factual Markdown grounded strictly in bundled <file path=…> excerpts.";
+}
+function normalizeLeadingH1(md, canonicalTitle) {
+    const t = canonicalTitle.trim();
+    if (!t)
+        return md;
+    const text = md.replace(/^\uFEFF/, "");
+    const lines = text.split(/\r?\n/);
+    let i = 0;
+    while (i < lines.length && /^\s*$/.test(lines[i]))
+        i++;
+    if (i < lines.length && /^#\s/.test(lines[i])) {
+        lines[i] = `# ${t}`;
+        return lines.join("\n");
+    }
+    return md;
+}
+async function mkdirp(p) {
+    await fs.mkdir(p, { recursive: true });
+}
+function bucketAndStemFromRel(relPosix) {
+    const n = relPosix.replace(/\\/g, "/");
+    const slash = n.lastIndexOf("/");
+    const file = slash === -1 ? n : n.slice(slash + 1);
+    const stem = file.replace(/\.md$/i, "");
+    const bucket = slash === -1 ? "" : n.slice(0, slash);
+    return { bucket, stem };
+}
+async function mergePathOwners(wikiBase, checkpoint) {
+    const meta = await (0, repowikiConfig_1.loadRepowikiMetadata)(wikiBase);
+    const m = new Map();
+    for (const [k, v] of invertFilesMap(meta?.files).entries()) {
+        m.set(k, v);
+    }
+    if (checkpoint?.fileByPageId) {
+        for (const [pid, rel] of Object.entries(checkpoint.fileByPageId)) {
+            const n = rel.replace(/\\/g, "/");
+            m.set(n, pid);
+        }
+    }
+    return m;
+}
+function pageFullyOnDisk(wikiBase, langFolders, relPosix) {
+    return langFolders.map(async (lg) => pathExists(path.join(wikiBase, lg, ...relPosix.split("/").filter(Boolean))));
+}
+async function shouldSkipCompletedPage(wikiBase, langFolders, checkpoint, pageId) {
+    if (!checkpoint?.completed.includes(pageId))
+        return false;
+    const rel = checkpoint.fileByPageId[pageId]?.replace(/\\/g, "/");
+    if (!rel)
+        return false;
+    const checks = pageFullyOnDisk(wikiBase, langFolders, rel);
+    const results = await Promise.all(checks);
+    return results.every(Boolean);
+}
+async function runRepowikiIndex(opts) {
+    const log = opts.onLog ?? (() => { });
+    const report = opts.onProgress;
+    const signal = opts.signal ?? NEVER_ABORT;
+    const wikiBase = path.join(opts.wikiOutputRootFs, opts.wikiRelPath.replace(/^[/\\]+/, ""));
+    const langs = opts.languages?.length ? opts.languages : DEFAULT_LANGS;
+    const resumeEnabled = opts.resumeEnabled !== false;
+    const forceFull = Boolean(opts.forceFull);
+    (0, abort_1.assertNotAborted)(signal);
+    const head = await (0, repowikiGit_1.gitHeadAt)(opts.repoRootFs);
+    const primaryLang = langs[0].folder;
+    await mkdirp(wikiBase);
+    for (const lg of langs) {
+        await mkdirp(path.join(wikiBase, lg.folder));
+    }
+    const repoName = path.basename(opts.repoRootFs.replace(/[/\\]+$/, ""));
+    const fileList = await (0, repowikiScanner_1.collectRepoFileList)(opts.repoRootFs);
+    const treeText = (0, repowikiScanner_1.summarizeTreeLines)(fileList, 260);
+    const readme = await (0, repowikiScanner_1.tryReadFirstReadme)(opts.repoRootFs);
+    const structureLang = langs[0] ?? exports.REPOWIKI_LANG_ZH;
+    const langFolders = langs.map((l) => l.folder);
+    let existingCp = forceFull ? null : await (0, repowikiCheckpoint_1.readRepowikiCheckpoint)(wikiBase);
+    if (forceFull && existingCp) {
+        await (0, repowikiCheckpoint_1.clearRepowikiCheckpoint)(wikiBase);
+        existingCp = null;
+    }
+    if (existingCp &&
+        !(0, repowikiCheckpoint_1.checkpointMatchesRun)(existingCp, opts.repoRootFs, wikiBase, primaryLang)) {
+        log("[repowiki] Clearing stale checkpoint (paths or language differ).");
+        await (0, repowikiCheckpoint_1.clearRepowikiCheckpoint)(wikiBase);
+        existingCp = null;
+    }
+    let runId = (0, crypto_1.randomUUID)();
+    let xml = "";
+    let pages = [];
+    let resumed = false;
+    const tryResume = resumeEnabled &&
+        !forceFull &&
+        existingCp &&
+        (0, repowikiCheckpoint_1.checkpointMatchesRun)(existingCp, opts.repoRootFs, wikiBase, primaryLang);
+    if (tryResume && existingCp) {
+        const structurePath = path.join(wikiBase, "structure.xml");
+        const rawStructure = await fs.readFile(structurePath, "utf8").catch(() => "");
+        if (rawStructure.trim()) {
+            const parsedXml = (0, wikiStructureXml_1.extractWikiStructureXml)(rawStructure) || rawStructure;
+            const parsedPages = (0, wikiStructureXml_1.parseWikiPages)(parsedXml);
+            if (parsedPages.length > 0) {
+                xml = parsedXml;
+                pages = parsedPages.slice(0, wikiStructureXml_1.REPOWIKI_MAX_PAGES);
+                const comprehensiveResume = opts.comprehensiveSections ?? false;
+                const normalizedResume = (0, repowikiStructureNormalize_1.normalizeComprehensiveWikiStructure)({
+                    comprehensive: comprehensiveResume,
+                    langFolder: structureLang.folder,
+                    xml,
+                    pages,
+                });
+                if (normalizedResume.xml !== xml) {
+                    await fs.writeFile(structurePath, normalizedResume.xml.replace(/^\uFEFF/, ""), "utf8");
+                    log("[repowiki] Updated structure.xml (normalized sections / parent_section).");
+                }
+                xml = normalizedResume.xml;
+                pages = normalizedResume.pages;
+                runId = existingCp.runId;
+                resumed = true;
+                log(`[repowiki] Resuming run ${runId} (${existingCp.completed.length} page(s) already completed).`);
+            }
+        }
+    }
+    if (!resumed) {
+        report?.({ done: 0, total: 0, detail: "Requesting wiki outline from model…" });
+        log("[repowiki] Requesting wiki structure…");
+        const structureSystem = structureLang.folder === "zh"
+            ? "你只输出格式正确的 wiki_structure XML（符合用户给定模板）；不要使用 markdown 代码围栏。纲要中凡是给人阅读的标题与描述必须使用简体中文（zh-CN）。"
+            : structureLang.folder === "en"
+                ? "You output ONLY well-formed wiki_structure XML matching the user's template. Never use markdown fences. Every repo title, wiki title/description, section titles, page titles, and page descriptions meant for humans must be fluent English (no Chinese prose in those strings unless it is unavoidable quoted content from the repository)."
+                : "You output ONLY well-formed wiki_structure XML matching the user's template. Never use markdown fences.";
+        const comprehensive = opts.comprehensiveSections ?? false;
+        let structureRaw = await chatCompletionTextForIndex(signal, {
+            baseUrl: opts.baseUrl,
+            apiKey: opts.apiKey,
+            model: opts.model,
+            temperature: 0.2,
+            messages: [
+                { role: "system", content: structureSystem },
+                {
+                    role: "user",
+                    content: structurePrompt(repoName, treeText, readme, structureLang, comprehensive),
+                },
+            ],
+        });
+        (0, abort_1.assertNotAborted)(signal);
+        xml = (0, wikiStructureXml_1.extractWikiStructureXml)(structureRaw) ?? "";
+        if (!xml) {
+            throw new Error(`Model returned no <wiki_structure> XML. Preview: ${structureRaw.slice(0, 400)}`);
+        }
+        pages = (0, wikiStructureXml_1.parseWikiPages)(xml);
+        if (!pages.length) {
+            throw new Error(`Could not parse wiki pages from XML. Preview: ${structureRaw.slice(0, 500)}`);
+        }
+        if (pages.length > wikiStructureXml_1.REPOWIKI_MAX_PAGES) {
+            log(`[repowiki] Truncating outline from ${pages.length} to ${wikiStructureXml_1.REPOWIKI_MAX_PAGES} pages.`);
+            pages = pages.slice(0, wikiStructureXml_1.REPOWIKI_MAX_PAGES);
+        }
+        if (comprehensive && (0, repowikiStructureNormalize_1.comprehensiveOutlineNeedsStructureRetry)(comprehensive, xml, pages)) {
+            log("[repowiki] Outline has too few <section> blocks — requesting revised outline…");
+            structureRaw = await chatCompletionTextForIndex(signal, {
+                baseUrl: opts.baseUrl,
+                apiKey: opts.apiKey,
+                model: opts.model,
+                temperature: 0.2,
+                messages: [
+                    { role: "system", content: structureSystem },
+                    {
+                        role: "user",
+                        content: structurePrompt(repoName, treeText, readme, structureLang, comprehensive) +
+                            (0, repowikiStructureNormalize_1.structureRepairUserAppendix)(structureRaw, structureLang.folder),
+                    },
+                ],
+            });
+            (0, abort_1.assertNotAborted)(signal);
+            const xmlRetry = (0, wikiStructureXml_1.extractWikiStructureXml)(structureRaw) ?? "";
+            if (!xmlRetry) {
+                throw new Error(`Revision request returned no <wiki_structure> XML. Preview: ${structureRaw.slice(0, 400)}`);
+            }
+            xml = xmlRetry;
+            pages = (0, wikiStructureXml_1.parseWikiPages)(xml);
+            if (!pages.length) {
+                throw new Error(`Could not parse wiki pages from revised XML. Preview: ${structureRaw.slice(0, 500)}`);
+            }
+            if (pages.length > wikiStructureXml_1.REPOWIKI_MAX_PAGES) {
+                log(`[repowiki] Truncating revised outline from ${pages.length} to ${wikiStructureXml_1.REPOWIKI_MAX_PAGES} pages.`);
+                pages = pages.slice(0, wikiStructureXml_1.REPOWIKI_MAX_PAGES);
+            }
+        }
+        const normalized = (0, repowikiStructureNormalize_1.normalizeComprehensiveWikiStructure)({
+            comprehensive,
+            langFolder: structureLang.folder,
+            xml,
+            pages,
+        });
+        xml = normalized.xml;
+        pages = normalized.pages;
+        await fs.writeFile(path.join(wikiBase, "structure.xml"), xml.replace(/^\uFEFF/, ""), "utf8");
+        log("[repowiki] Wrote structure.xml");
+        const freshCp = {
+            version: 1,
+            runId,
+            status: "running",
+            sourceRootFs: normFsPosix(opts.repoRootFs),
+            wikiBaseFs: normFsPosix(wikiBase),
+            indexedCommit: head ?? null,
+            targetLang: primaryLang,
+            languages: langFolders,
+            completed: [],
+            fileByPageId: {},
+        };
+        await (0, repowikiCheckpoint_1.writeRepowikiCheckpoint)(wikiBase, freshCp);
+    }
+    let checkpoint = (await (0, repowikiCheckpoint_1.readRepowikiCheckpoint)(wikiBase)) ?? {
+        version: 1,
+        runId,
+        status: "running",
+        sourceRootFs: normFsPosix(opts.repoRootFs),
+        wikiBaseFs: normFsPosix(wikiBase),
+        indexedCommit: head ?? null,
+        targetLang: primaryLang,
+        languages: langFolders,
+        completed: [],
+        fileByPageId: {},
+    };
+    const sectionGroups = (0, repowikiStructureNav_1.parseSectionGroups)(xml);
+    const outlineFolderSegment = (0, repowikiCanonicalSections_1.defaultWikiFolderSegment)((0, repowikiStructureNav_1.extractWikiOutlineTitle)(xml), structureLang.folder);
+    const folderBySectionId = (0, repowikiCanonicalSections_1.buildUniqueSectionFolderSegments)(sectionGroups);
+    const folderByPageId = new Map();
+    for (const p of pages) {
+        folderByPageId.set(p.id, (0, repowikiCanonicalSections_1.sectionFolderSegmentForPage)(p, sectionGroups, outlineFolderSegment, folderBySectionId));
+    }
+    const sectionMap = (0, repowikiCanonicalSections_1.formatSectionFolderMapSummary)(folderByPageId, pages.map((p) => p.id));
+    log(`[repowiki] Section map: ${sectionMap}`);
+    const pathOwners = await mergePathOwners(wikiBase, checkpoint);
+    const primaryLangDir = path.join(wikiBase, primaryLang);
+    const physicalExists = (rel) => (0, fs_1.existsSync)(path.join(primaryLangDir, ...rel.split("/").filter(Boolean)));
+    const filesRelByPageId = new Map();
+    for (const p of pages) {
+        if (await shouldSkipCompletedPage(wikiBase, langFolders, checkpoint, p.id)) {
+            const relCp = checkpoint.fileByPageId[p.id]?.replace(/\\/g, "/");
+            if (relCp) {
+                filesRelByPageId.set(p.id, relCp);
+            }
+        }
+    }
+    const pagesNeedingPaths = pages.filter((p) => !filesRelByPageId.has(p.id));
+    const stemAlloc = (0, wikiStructureXml_1.allocateWikiFileStemsWithTargetPaths)(pagesNeedingPaths, folderByPageId, pathOwners, physicalExists);
+    for (const p of pagesNeedingPaths) {
+        const bucket = folderByPageId.get(p.id);
+        const stem = stemAlloc.get(p.id);
+        filesRelByPageId.set(p.id, `${bucket}/${stem}.md`.replace(/\\/g, "/"));
+    }
+    for (const p of pages) {
+        if (!filesRelByPageId.has(p.id)) {
+            throw new Error(`[repowiki] Missing path mapping for page ${p.id}`);
+        }
+    }
+    const pagesToGenerate = [];
+    for (const p of pages) {
+        if (await shouldSkipCompletedPage(wikiBase, langFolders, checkpoint, p.id)) {
+            continue;
+        }
+        pagesToGenerate.push(p);
+    }
+    const totalSteps = 2 + pages.length * langs.length;
+    let done = 1;
+    report?.({
+        done,
+        total: totalSteps,
+        detail: resumed
+            ? `Resumed — ${pagesToGenerate.length} page(s) remaining`
+            : `Outline ready (${pages.length} page × ${langs.length} languages)`,
+    });
+    async function persistCheckpoint(completedList) {
+        const next = {
+            ...checkpoint,
+            runId,
+            status: "running",
+            completed: completedList,
+            fileByPageId: { ...checkpoint.fileByPageId },
+            languages: langFolders,
+            indexedCommit: head ?? checkpoint.indexedCommit ?? null,
+        };
+        for (const p of pages) {
+            const rel = filesRelByPageId.get(p.id);
+            if (rel && completedList.includes(p.id)) {
+                next.fileByPageId[p.id] = rel;
+            }
+        }
+        await (0, repowikiCheckpoint_1.writeRepowikiCheckpoint)(wikiBase, next);
+        Object.assign(checkpoint, next);
+    }
+    let completedSoFar = [...checkpoint.completed].filter((id) => pages.some((p) => p.id === id));
+    for (let i = 0; i < pages.length; i++) {
+        (0, abort_1.assertNotAborted)(signal);
+        const page = pages[i];
+        if (await shouldSkipCompletedPage(wikiBase, langFolders, checkpoint, page.id)) {
+            log(`[repowiki] Skip ${page.id} (already completed).`);
+            done += langs.length;
+            continue;
+        }
+        const relForPage = filesRelByPageId.get(page.id);
+        const { bucket, stem } = bucketAndStemFromRel(relForPage);
+        if (!bucket) {
+            throw new Error(`[repowiki] Invalid path (missing section folder): ${relForPage}`);
+        }
+        const existing = await resolveExistingPaths(opts.repoRootFs, fileList, page.relevantFiles).catch(() => page.relevantFiles);
+        page.relevantFiles = existing.slice(0, 12);
+        let ctxBundle = await (0, repowikiScanner_1.bundleSourceContext)(opts.repoRootFs, page.relevantFiles, 24_000);
+        if (!ctxBundle.trim()) {
+            const fallbackPick = sampleFallbackPaths(fileList, 12);
+            const fb = await (0, repowikiScanner_1.bundleSourceContext)(opts.repoRootFs, fallbackPick, 20_000);
+            log(`[repowiki] Page ${page.id}: thin context — using sampled repo files.`);
+            ctxBundle = fb;
+        }
+        if (!ctxBundle.trim()) {
+            (0, abort_1.assertNotAborted)(signal);
+            for (const lg of langs) {
+                await writeMarkdown(wikiBase, lg.folder, bucket, stem, lg.folder === "zh"
+                    ? `# ${page.title}\n\n_未找到可读的仓库文件用于摘要。_\n`
+                    : `# ${page.title}\n\n_No readable repository files found to summarize._\n`, opts.repoRootFs);
+                done++;
+                report?.({
+                    done,
+                    total: totalSteps,
+                    detail: `Stub ${lg.folder}/${bucket}/${stem}.md (${i + 1}/${pages.length})`,
+                });
+            }
+            if (!completedSoFar.includes(page.id)) {
+                completedSoFar.push(page.id);
+                await persistCheckpoint(completedSoFar);
+            }
+            continue;
+        }
+        for (const lg of langs) {
+            (0, abort_1.assertNotAborted)(signal);
+            report?.({
+                done,
+                total: totalSteps,
+                detail: `Waiting for model: ${lg.folder}/${bucket}/${stem}.md (${i + 1}/${pages.length})`,
+            });
+            const md = await chatCompletionTextForIndex(signal, {
+                baseUrl: opts.baseUrl,
+                apiKey: opts.apiKey,
+                model: opts.model,
+                temperature: 0.25,
+                messages: [
+                    { role: "system", content: pageGenerationSystemPrompt(lg.folder) },
+                    {
+                        role: "user",
+                        content: pageMarkdownPrompt(lg.folder, lg.label, `${page.title}\n\n${page.description}`, ctxBundle),
+                    },
+                ],
+            });
+            await writeMarkdown(wikiBase, lg.folder, bucket, stem, normalizeLeadingH1(md, page.title), opts.repoRootFs);
+            log(`[repowiki] ${lg.folder}/${bucket}/${stem}.md (${i + 1}/${pages.length})`);
+            done++;
+            report?.({
+                done,
+                total: totalSteps,
+                detail: `Saved ${lg.folder}/${bucket}/${stem}.md`,
+            });
+        }
+        if (!completedSoFar.includes(page.id)) {
+            completedSoFar.push(page.id);
+        }
+        await persistCheckpoint(completedSoFar);
+    }
+    done++;
+    report?.({
+        done,
+        total: totalSteps,
+        detail: "Writing metadata.json…",
+    });
+    (0, abort_1.assertNotAborted)(signal);
+    const files = {};
+    for (const p of pages) {
+        const rel = filesRelByPageId.get(p.id);
+        files[p.id] = rel;
+    }
+    const embedBase64 = opts.repowikiMetadataEmbedMarkdownBase64 !== false;
+    let contentBase64ByLang;
+    if (embedBase64) {
+        contentBase64ByLang = await (0, repowikiMetadataContent_1.collectContentBase64ByLang)({
+            wikiBase,
+            langFolders,
+            pageIds: pages.map((p) => p.id),
+            filesRelByPageId,
+        });
+    }
+    const outlineTitle = (0, repowikiStructureNav_1.extractWikiOutlineTitle)(xml).trim();
+    const meta = {
+        schema: repowikiMetadataJson_1.REPOWIKI_METADATA_SCHEMA_ID,
+        version: repowikiMetadataJson_1.REPOWIKI_METADATA_SCHEMA_VERSION,
+        metadataSchemaVersion: repowikiMetadataJson_1.REPOWIKI_METADATA_SCHEMA_VERSION,
+        indexedAt: new Date().toISOString(),
+        indexedCommit: head ?? null,
+        wikiTitle: outlineTitle ? outlineTitle : null,
+        model: opts.model,
+        langFolders: [...langFolders],
+        pages: pages.map((p) => ({ id: p.id, title: p.title })),
+        pageIds: pages.map((p) => p.id),
+        sourceRootFs: opts.repoRootFs.replace(/\\/g, "/"),
+        wikiBaseFs: wikiBase.replace(/\\/g, "/"),
+        files,
+        ...(contentBase64ByLang ? { contentBase64ByLang } : {}),
+    };
+    const metaJson = JSON.stringify(meta, null, 2);
+    await fs.writeFile(path.join(wikiBase, "metadata.json"), metaJson, "utf8");
+    log("[repowiki] Wrote metadata.json");
+    await (0, repowikiCheckpoint_1.clearRepowikiCheckpoint)(wikiBase);
+    log("[repowiki] Index complete (checkpoint cleared).");
+}
+async function writeMarkdown(wikiBase, langFolder, sectionFolderSlug, stem, md, repoRootFs) {
+    const dir = path.join(wikiBase, langFolder, sectionFolderSlug);
+    await mkdirp(dir);
+    const target = path.join(dir, `${stem}.md`);
+    const linked = (0, repowikiMarkdownPost_1.linkifySourcesLinesInMarkdown)(md, target, repoRootFs);
+    await fs.writeFile(target, linked.replace(/^\uFEFF/, ""), "utf8");
+}
+async function resolveExistingPaths(_repoRootFs, allRel, requested) {
+    const set = new Set(allRel.map((p) => p.replace(/\\/g, "/")));
+    const out = [];
+    for (let raw of requested) {
+        raw = raw.replace(/\\/g, "/").replace(/^\.\//, "");
+        if (!raw)
+            continue;
+        if (set.has(raw)) {
+            out.push(raw);
+            continue;
+        }
+        const baseName = raw.split("/").pop();
+        const hit = [...set].find((p) => p === raw || p.endsWith("/" + baseName) || p.split("/").pop() === baseName) ?? "";
+        if (hit)
+            out.push(hit);
+    }
+    return [...new Set(out)].slice(0, 14);
+}
+function sampleFallbackPaths(allRel, n) {
+    const priority = /\.(tsx?|jsx?|py|go|rs|java|kt|kts|gradle|swift|rb|yaml|yml|json|md)$/i;
+    const scored = allRel.filter((p) => priority.test(p));
+    const pick = scored.length >= n ? scored.slice(0, n) : [...scored, ...allRel].slice(0, n);
+    return [...new Set(pick)];
+}
+/**
+ * Run only the outline stage of repowiki: call the LLM once to produce
+ * `structure.xml`, compute section folders, and resolve target file paths
+ * for every page. Does NOT generate per-page Markdown — intended to power
+ * the `--wiki-tasks-only` CLI mode so downstream agents can fill pages.
+ */
+async function runRepowikiOutlineOnly(opts) {
+    const log = opts.onLog ?? (() => { });
+    const report = opts.onProgress;
+    const signal = opts.signal ?? NEVER_ABORT;
+    const wikiBase = path.join(opts.wikiOutputRootFs, opts.wikiRelPath.replace(/^[/\\]+/, ""));
+    const langs = opts.languages?.length ? opts.languages : DEFAULT_LANGS;
+    (0, abort_1.assertNotAborted)(signal);
+    const primaryLang = langs[0].folder;
+    await mkdirp(wikiBase);
+    for (const lg of langs) {
+        await mkdirp(path.join(wikiBase, lg.folder));
+    }
+    const repoName = path.basename(opts.repoRootFs.replace(/[/\\]+$/, ""));
+    const fileList = await (0, repowikiScanner_1.collectRepoFileList)(opts.repoRootFs);
+    const treeText = (0, repowikiScanner_1.summarizeTreeLines)(fileList, 260);
+    const readme = await (0, repowikiScanner_1.tryReadFirstReadme)(opts.repoRootFs);
+    const structureLang = langs[0] ?? exports.REPOWIKI_LANG_ZH;
+    report?.({ done: 0, total: 0, detail: "Requesting wiki outline from model…" });
+    log("[repowiki] Requesting wiki structure…");
+    const structureSystem = structureLang.folder === "zh"
+        ? "你只输出格式正确的 wiki_structure XML（符合用户给定模板）；不要使用 markdown 代码围栏。纲要中凡是给人阅读的标题与描述必须使用简体中文（zh-CN）。"
+        : structureLang.folder === "en"
+            ? "You output ONLY well-formed wiki_structure XML matching the user's template. Never use markdown fences. Every repo title, wiki title/description, section titles, page titles, and page descriptions meant for humans must be fluent English (no Chinese prose in those strings unless it is unavoidable quoted content from the repository)."
+            : "You output ONLY well-formed wiki_structure XML matching the user's template. Never use markdown fences.";
+    const comprehensive = opts.comprehensiveSections ?? false;
+    let structureRaw = await chatCompletionTextForIndex(signal, {
+        baseUrl: opts.baseUrl,
+        apiKey: opts.apiKey,
+        model: opts.model,
+        temperature: 0.2,
+        messages: [
+            { role: "system", content: structureSystem },
+            {
+                role: "user",
+                content: structurePrompt(repoName, treeText, readme, structureLang, comprehensive),
+            },
+        ],
+    });
+    (0, abort_1.assertNotAborted)(signal);
+    let xml = (0, wikiStructureXml_1.extractWikiStructureXml)(structureRaw) ?? "";
+    if (!xml) {
+        throw new Error(`Model returned no <wiki_structure> XML. Preview: ${structureRaw.slice(0, 400)}`);
+    }
+    let pages = (0, wikiStructureXml_1.parseWikiPages)(xml);
+    if (!pages.length) {
+        throw new Error(`Could not parse wiki pages from XML. Preview: ${structureRaw.slice(0, 500)}`);
+    }
+    if (pages.length > wikiStructureXml_1.REPOWIKI_MAX_PAGES) {
+        log(`[repowiki] Truncating outline from ${pages.length} to ${wikiStructureXml_1.REPOWIKI_MAX_PAGES} pages.`);
+        pages = pages.slice(0, wikiStructureXml_1.REPOWIKI_MAX_PAGES);
+    }
+    if (comprehensive && (0, repowikiStructureNormalize_1.comprehensiveOutlineNeedsStructureRetry)(comprehensive, xml, pages)) {
+        log("[repowiki] Outline has too few <section> blocks — requesting revised outline…");
+        structureRaw = await chatCompletionTextForIndex(signal, {
+            baseUrl: opts.baseUrl,
+            apiKey: opts.apiKey,
+            model: opts.model,
+            temperature: 0.2,
+            messages: [
+                { role: "system", content: structureSystem },
+                {
+                    role: "user",
+                    content: structurePrompt(repoName, treeText, readme, structureLang, comprehensive) +
+                        (0, repowikiStructureNormalize_1.structureRepairUserAppendix)(structureRaw, structureLang.folder),
+                },
+            ],
+        });
+        (0, abort_1.assertNotAborted)(signal);
+        const xmlRetry = (0, wikiStructureXml_1.extractWikiStructureXml)(structureRaw) ?? "";
+        if (!xmlRetry) {
+            throw new Error(`Revision request returned no <wiki_structure> XML. Preview: ${structureRaw.slice(0, 400)}`);
+        }
+        xml = xmlRetry;
+        pages = (0, wikiStructureXml_1.parseWikiPages)(xml);
+        if (!pages.length) {
+            throw new Error(`Could not parse wiki pages from revised XML. Preview: ${structureRaw.slice(0, 500)}`);
+        }
+        if (pages.length > wikiStructureXml_1.REPOWIKI_MAX_PAGES) {
+            log(`[repowiki] Truncating revised outline from ${pages.length} to ${wikiStructureXml_1.REPOWIKI_MAX_PAGES} pages.`);
+            pages = pages.slice(0, wikiStructureXml_1.REPOWIKI_MAX_PAGES);
+        }
+    }
+    const normalized = (0, repowikiStructureNormalize_1.normalizeComprehensiveWikiStructure)({
+        comprehensive,
+        langFolder: structureLang.folder,
+        xml,
+        pages,
+    });
+    xml = normalized.xml;
+    pages = normalized.pages;
+    const structureXmlPath = path.join(wikiBase, "structure.xml");
+    await fs.writeFile(structureXmlPath, xml.replace(/^\uFEFF/, ""), "utf8");
+    log("[repowiki] Wrote structure.xml");
+    const sectionGroups = (0, repowikiStructureNav_1.parseSectionGroups)(xml);
+    const outlineFolderSegment = (0, repowikiCanonicalSections_1.defaultWikiFolderSegment)((0, repowikiStructureNav_1.extractWikiOutlineTitle)(xml), structureLang.folder);
+    const folderBySectionId = (0, repowikiCanonicalSections_1.buildUniqueSectionFolderSegments)(sectionGroups);
+    const folderByPageId = new Map();
+    for (const p of pages) {
+        folderByPageId.set(p.id, (0, repowikiCanonicalSections_1.sectionFolderSegmentForPage)(p, sectionGroups, outlineFolderSegment, folderBySectionId));
+    }
+    const sectionMap = (0, repowikiCanonicalSections_1.formatSectionFolderMapSummary)(folderByPageId, pages.map((p) => p.id));
+    log(`[repowiki] Section map: ${sectionMap}`);
+    // In tasks-only mode there is no checkpoint / prior metadata to honor,
+    // so pass empty owners and a `never-exists` physical probe: we just want
+    // deterministic target paths for the tasks list.
+    const stemAlloc = (0, wikiStructureXml_1.allocateWikiFileStemsWithTargetPaths)(pages, folderByPageId, new Map(), () => false);
+    const outlinePages = pages.map((p) => {
+        const bucket = folderByPageId.get(p.id);
+        const stem = stemAlloc.get(p.id);
+        const relUnderLang = `${bucket}/${stem}.md`.replace(/\\/g, "/");
+        return {
+            id: p.id,
+            title: p.title,
+            description: p.description,
+            parentSection: p.parentSection,
+            sectionFolder: bucket,
+            relativeOutputPath: `${primaryLang}/${relUnderLang}`,
+            relevantFiles: p.relevantFiles.slice(),
+        };
+    });
+    report?.({
+        done: 1,
+        total: 1,
+        detail: `Outline ready (${outlinePages.length} page, tasks-only mode)`,
+    });
+    return {
+        wikiBaseFs: wikiBase,
+        primaryLang,
+        structureXmlPath,
+        sectionMapSummary: sectionMap,
+        pages: outlinePages,
+    };
+}