gitnexushub 0.4.4 → 0.6.0

package/dist/wiki/upload-command.js

@@ -1,13 +1,108 @@
+import fs from 'fs/promises';
 import { resolveWikiContext } from './resolve-context.js';
 import { runWikiUploadSession } from './session.js';
 import { GnxError, ErrorCode } from './errors.js';
-import { info } from '../cli-helpers.js';
+import { info, warn } from '../cli-helpers.js';
+import { buildModuleRegistry, ensureAllFilesAssigned, estimateModuleTokens, extractSummary, fallbackGrouping, formatModuleRegistry, splitByCommunity, validateAndFixCrossReferences, } from './helpers.js';
+import { diffChangedFiles, tryIncrementalUpload } from './incremental.js';
+import { runConcurrent } from './concurrency.js';
+import { composeOverview } from './compose-overview.js';
+const DEFAULT_WIKI_CONCURRENCY = 10;
+function resolveConcurrency(optValue) {
+    if (typeof optValue === 'number' && optValue > 0)
+        return optValue;
+    const env = process.env.GNX_WIKI_CONCURRENCY;
+    if (env) {
+        const parsed = Number.parseInt(env, 10);
+        if (Number.isFinite(parsed) && parsed > 0)
+            return parsed;
+    }
+    return DEFAULT_WIKI_CONCURRENCY;
+}
+function formatBytes(n) {
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    return `${(n / (1024 * 1024)).toFixed(2)} MB`;
+}
+function formatDuration(ms) {
+    const s = Math.floor(ms / 1000);
+    if (s < 60)
+        return `${s}s`;
+    const m = Math.floor(s / 60);
+    const rem = s % 60;
+    return `${m}m${rem.toString().padStart(2, '0')}s`;
+}
+async function withHeartbeat(label, intervalMs, task) {
+    const start = Date.now();
+    const timer = setInterval(() => {
+        info(`${label} still working... ${formatDuration(Date.now() - start)} elapsed`);
+    }, intervalMs);
+    timer.unref?.();
+    try {
+        return await task();
+    }
+    finally {
+        clearInterval(timer);
+    }
+}
 function slugify(name) {
     return name
         .toLowerCase()
         .replace(/[^a-z0-9]+/g, '-')
         .replace(/^-|-$/g, '');
 }
+const MODULE_TREE_SCHEMA = {
+    type: 'object',
+    properties: {
+        modules: {
+            type: 'array',
+            description: 'Ordered list of documentation modules grouping the repo files',
+            items: {
+                type: 'object',
+                properties: {
+                    name: {
+                        type: 'string',
+                        description: 'Human-readable module name (e.g. "Authentication")',
+                    },
+                    files: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Repo-relative file paths belonging to this module',
+                    },
+                },
+                required: ['name', 'files'],
+            },
+        },
+    },
+    required: ['modules'],
+};
+function buildModulesFromStructured(structured) {
+    if (!structured || typeof structured !== 'object')
+        return [];
+    const arr = structured.modules;
+    if (!Array.isArray(arr))
+        return [];
+    const out = [];
+    for (const entry of arr) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const name = entry.name;
+        const files = entry.files;
+        if (typeof name !== 'string' || !Array.isArray(files))
+            continue;
+        const slug = slugify(name);
+        if (!slug)
+            continue;
+        out.push({
+            slug,
+            title: name,
+            files: files.filter((f) => typeof f === 'string'),
+        });
+    }
+    return out;
+}
 function parseModuleTree(raw) {
     const cleaned = raw
         .trim()
@@ -23,7 +118,12 @@ function parseModuleTree(raw) {
             cause: err,
         });
     }
-    if (parsed && !Array.isArray(parsed.modules) && typeof parsed === 'object') {
+    if (parsed && Array.isArray(parsed.modules)) {
+        const modules = buildModulesFromStructured(parsed);
+        if (modules.length > 0)
+            return modules;
+    }
+    if (parsed && typeof parsed === 'object') {
         const modules = [];
         for (const [name, files] of Object.entries(parsed)) {
             if (!Array.isArray(files))
@@ -42,7 +142,13 @@ function parseModuleTree(raw) {
     }
     throw new GnxError(ErrorCode.GENERATION_FAILED, 'module tree had no valid modules');
 }
-const SPLIT_FILE_THRESHOLD = 20;
+// Token budget for a single wiki page — matches
+// gitnexus/src/core/wiki/generator.ts:DEFAULT_MAX_TOKENS_PER_MODULE.
+// A module splits only when BOTH (total file tokens > budget) AND (files > 3),
+// so a small handful of huge files stays together but a truly large module
+// gets broken into sub-pages.
+const MAX_TOKENS_PER_MODULE = 30_000;
+const MIN_FILES_FOR_SPLIT = 3;
 function splitBySubdirectory(parentName, files) {
     const subGroups = new Map();
     for (const fp of files) {
@@ -66,15 +172,21 @@ function splitBySubdirectory(parentName, files) {
         };
     });
 }
-function applyModuleSplitting(modules) {
+async function applyModuleSplitting(modules, communityMapping, repoRoot) {
     for (const node of modules) {
         const files = node.files ?? [];
-        if (files.length > SPLIT_FILE_THRESHOLD) {
-            const children = splitBySubdirectory(node.title, files);
-            if (children.length > 1) {
-                node.children = children;
-                node.files = [];
-            }
+        if (files.length <= MIN_FILES_FOR_SPLIT)
+            continue;
+        const totalTokens = await estimateModuleTokens(files, repoRoot);
+        if (totalTokens <= MAX_TOKENS_PER_MODULE)
+            continue;
+        const byCommunity = splitByCommunity(node.title, files, communityMapping);
+        const children = byCommunity
+            ? byCommunity.map((c) => ({ slug: c.slug, title: c.name, files: c.files }))
+            : splitBySubdirectory(node.title, files);
+        if (children.length > 1) {
+            node.children = children;
+            node.files = [];
         }
     }
     return modules;
@@ -111,10 +223,69 @@ function fillTemplate(template, vars) {
     }
     return result;
 }
+function formatDryRunHeader(args) {
+    const { repoFullName, headCommit, model, modules } = args;
+    const generatedAt = new Date().toISOString();
+    const parts = [];
+    parts.push(`# ${repoFullName} — Wiki Dry Run`);
+    parts.push('');
+    parts.push(`> Generated ${generatedAt} · commit \`${headCommit.slice(0, 8)}\` · model \`${model}\` · ${modules.length} pages`);
+    parts.push('');
+    parts.push('> Streaming dry-run output — no content has been uploaded to the Hub. Pages appear below in COMPLETION order (not tree order) as each LLM call finishes, so partial output is preserved on interrupt. The table of contents is in tree order.');
+    parts.push('');
+    parts.push('## Table of Contents');
+    parts.push('');
+    for (const m of modules) {
+        parts.push(`- [${m.title}](#${m.slug})`);
+    }
+    parts.push('');
+    return parts.join('\n') + '\n';
+}
+function formatDryRunPage(page) {
+    const parts = [];
+    parts.push('---');
+    parts.push('');
+    parts.push(`<a id="${page.slug}"></a>`);
+    parts.push('');
+    parts.push(`> **Slug:** \`${page.slug}\``);
+    parts.push('');
+    parts.push(page.contentMd);
+    parts.push('');
+    return parts.join('\n') + '\n';
+}
 export async function runWikiUpload(opts, deps) {
     const ctx = await resolveWikiContext(deps);
     if (opts.abortSignal?.aborted)
         throw new GnxError(ErrorCode.USER_ABORTED, 'aborted before session start');
+    // For incremental mode, compute the git diff once up-front. If it's empty we
+    // short-circuit the whole pipeline; otherwise we pass it forward to
+    // tryIncrementalUpload so it doesn't re-shell-out to git.
+    // Dry-run always forces a full regeneration regardless of mode.
+    let precomputedStatus = null;
+    let precomputedDiff = null;
+    if (opts.mode === 'incremental' && !opts.dryRunOutputPath) {
+        precomputedStatus = await ctx.api.wikiStatus(ctx.hubRepoId);
+        if (precomputedStatus?.fromCommit) {
+            precomputedDiff = diffChangedFiles(ctx.repoRoot, precomputedStatus.fromCommit, ctx.headCommit);
+            if (precomputedDiff &&
+                precomputedDiff.added.length +
+                    precomputedDiff.modified.length +
+                    precomputedDiff.deleted.length ===
+                    0) {
+                const session = await ctx.api.wikiUploadStart(ctx.hubRepoId, {
+                    mode: 'incremental',
+                    fromCommit: ctx.headCommit,
+                    clientVersion: deps.clientVersion,
+                    clientModel: deps.model,
+                });
+                await ctx.api.wikiUploadFinish(ctx.hubRepoId, session.sessionId, {
+                    moduleTree: [],
+                    receivedSlugs: [],
+                });
+                return { sessionId: session.sessionId, pagesPersisted: 0, failedSlugs: [] };
+            }
+        }
+    }
     const runner = deps.createClaudeRunner();
     info(`Fetching graph context from Hub (${ctx.hubFullName})...`);
     const [prompts, groupingCtx] = await Promise.all([
@@ -122,7 +293,7 @@ export async function runWikiUpload(opts, deps) {
         ctx.api.wikiGroupingContext(ctx.hubRepoId),
     ]);
     // Phase 1: Module tree
-    info('Phase 1/3: generating module tree with Claude Code...');
+    info('Phase 1/3: generating module tree with Claude Code (one LLM call, typically 30s–2min)...');
     const groupingPrompt = fillTemplate(prompts.grouping.user, {
         COMMUNITY_GROUPS: groupingCtx.communityGroups,
         INTER_COMMUNITY_EDGES: groupingCtx.interCommunityEdges,
@@ -130,16 +301,52 @@ export async function runWikiUpload(opts, deps) {
         FILE_LIST: groupingCtx.filesWithExports,
         DIRECTORY_TREE: groupingCtx.directoryTree,
     });
-    const moduleTreeRaw = await runner.run(`${prompts.grouping.system}\n\n${groupingPrompt}`, {
+    const moduleTreeRaw = await withHeartbeat('  module tree', 10_000, () => runner.run(`${prompts.grouping.system}\n\n${groupingPrompt}\n\nReturn the result as a JSON object with a "modules" array. Each entry has a "name" (human-readable module title) and "files" (array of repo-relative file paths).`, {
         cwd: ctx.repoRoot,
         model: deps.model,
         allowedTools: [],
-    });
-    const rawModules = parseModuleTree(moduleTreeRaw.text);
-    const modules = applyModuleSplitting(rawModules);
+        outputFormat: { type: 'json_schema', schema: MODULE_TREE_SCHEMA },
+    }));
+    info(`  module tree generated in ${formatDuration(moduleTreeRaw.durationMs)}`);
+    const communityMapping = groupingCtx.communityMapping ?? [];
+    const filesWithExportsRaw = groupingCtx.filesWithExportsRaw ?? [];
+    // Try structured output first, then free-form JSON parse, then community/directory fallback.
+    let rawModules = buildModulesFromStructured(moduleTreeRaw.structuredOutput);
+    if (rawModules.length === 0) {
+        try {
+            rawModules = parseModuleTree(moduleTreeRaw.text);
+        }
+        catch {
+            const fb = fallbackGrouping(filesWithExportsRaw, communityMapping);
+            rawModules = Object.entries(fb).map(([title, files]) => ({
+                slug: slugify(title),
+                title,
+                files,
+            }));
+        }
+    }
+    if (rawModules.length === 0)
+        throw new GnxError(ErrorCode.GENERATION_FAILED, 'module tree had no valid modules');
+    // Sweep any files the LLM silently dropped into an "Other" bucket so they
+    // still get documented. Matches Hub generator.ts:499-502.
+    rawModules = ensureAllFilesAssigned(rawModules, filesWithExportsRaw, (slug, title, files) => ({
+        slug,
+        title,
+        files,
+    }));
+    const modules = await applyModuleSplitting(rawModules, communityMapping, ctx.repoRoot);
     const { leaves, parents } = flattenModuleTree(modules);
     const allPageNodes = [...leaves, ...parents];
-    const moduleRegistry = allPageNodes.map((m) => `- [${m.title}](${m.slug}.md)`).join('\n');
+    const moduleRegistryMap = buildModuleRegistry(allPageNodes.map((n) => ({
+        name: n.title,
+        slug: n.slug,
+        files: n.files ?? [],
+        children: n.children?.map((c) => ({
+            name: c.title,
+            slug: c.slug,
+            files: c.files ?? [],
+        })),
+    })), filesWithExportsRaw);
     const generatedPages = new Map();
     info(`Phase 2/3: generating ${leaves.length} leaf page(s) + ${parents.length} parent page(s)...`);
     if (opts.abortSignal?.aborted)
@@ -162,10 +369,7 @@ export async function runWikiUpload(opts, deps) {
                 processes: 'No execution flows detected.',
             };
         }
-        const reg = allPageNodes
-            .filter((m) => m.slug !== node.slug)
-            .map((m) => `- [${m.title}](${m.slug}.md)`)
-            .join('\n');
+        const reg = formatModuleRegistry(moduleRegistryMap, node.slug);
         const pagePrompt = fillTemplate(prompts.module.user, {
             MODULE_NAME: node.title,
             SOURCE_CODE: leafCtx.sourceCode,
@@ -180,7 +384,16 @@ export async function runWikiUpload(opts, deps) {
             model: deps.model,
             allowedTools: [],
         });
-        const content = `# ${node.title}\n\n${extractPageMarkdown(result.text)}`;
+        let diagramSection = '';
+        const mermaid = leafCtx.mermaid;
+        if (mermaid?.callGraph) {
+            diagramSection += `\n\n## Internal Call Graph\n\n\`\`\`mermaid\n${mermaid.callGraph}\n\`\`\``;
+        }
+        for (const seq of (mermaid?.sequenceDiagrams ?? []).slice(0, 3)) {
+            diagramSection += `\n\n## Workflow\n\n\`\`\`mermaid\n${seq}\n\`\`\``;
+        }
+        let content = `# ${node.title}\n\n${extractPageMarkdown(result.text)}${diagramSection}`;
+        content = validateAndFixCrossReferences(content, moduleRegistryMap);
         generatedPages.set(node.slug, content);
         return { title: node.title, contentMd: content };
     };
@@ -192,7 +405,7 @@ export async function runWikiUpload(opts, deps) {
             .map((child) => {
             const content = generatedPages.get(child.slug);
             return content
-                ? `#### ${child.title}\n${content.slice(0, 800).trim()}`
+                ? `#### ${child.title}\n${extractSummary(content, 800)}`
                 : `#### ${child.title}\n(Documentation not yet generated)`;
         })
             .join('\n\n');
@@ -204,10 +417,7 @@ export async function runWikiUpload(opts, deps) {
         catch {
             parentCtx = { intraCalls: 'None', processes: 'No execution flows detected.' };
         }
-        const reg = allPageNodes
-            .filter((m) => m.slug !== node.slug)
-            .map((m) => `- [${m.title}](${m.slug}.md)`)
-            .join('\n');
+        const reg = formatModuleRegistry(moduleRegistryMap, node.slug);
         const parentPrompt = fillTemplate(prompts.parent.user, {
             MODULE_NAME: node.title,
             CHILDREN_DOCS: childDocs,
@@ -220,51 +430,56 @@ export async function runWikiUpload(opts, deps) {
             model: deps.model,
             allowedTools: [],
         });
-        const content = `# ${node.title}\n\n${extractPageMarkdown(result.text)}`;
+        let parentDiagramSection = '';
+        const parentMermaid = parentCtx?.mermaid;
+        if (parentMermaid?.callGraph) {
+            parentDiagramSection += `\n\n## Cross-Module Call Graph\n\n\`\`\`mermaid\n${parentMermaid.callGraph}\n\`\`\``;
+        }
+        let content = `# ${node.title}\n\n${extractPageMarkdown(result.text)}${parentDiagramSection}`;
+        content = validateAndFixCrossReferences(content, moduleRegistryMap);
         generatedPages.set(node.slug, content);
         return { title: node.title, contentMd: content };
     };
-    // Phase 3: Overview page
+    // Phase 3: Overview page (Phase 5.2 — deterministic, no LLM call).
+    // Skips the per-repo overview LLM round-trip in favour of stitching
+    // together each module's first-paragraph summary plus the architecture
+    // Mermaid diagram. Saves ~1 minute per generation; quality is comparable
+    // because the LLM was largely rephrasing the leaf summaries we already
+    // have in `generatedPages`.
     const generateOverview = async () => {
         if (opts.abortSignal?.aborted)
             throw new GnxError(ErrorCode.USER_ABORTED, 'aborted during overview generation');
-        const moduleSummaries = modules
-            .map((m) => {
+        const overviewModules = modules.map((m) => {
             const content = generatedPages.get(m.slug);
-            return content
-                ? `#### ${m.title}\n${content.slice(0, 600).trim()}`
-                : `#### ${m.title}\n(Documentation pending)`;
-        })
-            .join('\n\n');
+            return {
+                slug: m.slug,
+                title: m.title,
+                summary: content ? extractSummary(content, 600) : '',
+            };
+        });
+        // Architecture diagram still comes from the Hub's overview context
+        // endpoint, which precomputes inter-module Mermaid edges from the graph.
         const moduleFiles = {};
         for (const m of modules) {
             const files = m.children ? m.children.flatMap((c) => c.files ?? []) : (m.files ?? []);
             if (files.length > 0)
                 moduleFiles[m.title] = files;
         }
-        let overviewCtx;
+        let architectureMermaid = '';
         try {
-            overviewCtx = await ctx.api.wikiOverviewContext(ctx.hubRepoId, moduleFiles);
+            const overviewCtx = await ctx.api.wikiOverviewContext(ctx.hubRepoId, moduleFiles);
+            const overviewMermaid = overviewCtx?.mermaid;
+            architectureMermaid = overviewMermaid?.architecture ?? '';
         }
         catch {
-            overviewCtx = {
-                interModuleEdges: 'No inter-module call edges detected',
-                topProcesses: 'No execution flows detected.',
-            };
+            // Architecture diagram is best-effort; proceed without it on failure.
         }
-        const overviewPrompt = fillTemplate(prompts.overview.user, {
-            PROJECT_INFO: `Repository: ${ctx.hubFullName}`,
-            MODULE_SUMMARIES: moduleSummaries,
-            MODULE_EDGES: overviewCtx.interModuleEdges,
-            TOP_PROCESSES: overviewCtx.topProcesses,
-            MODULE_REGISTRY: moduleRegistry,
-        });
-        const result = await runner.run(`${prompts.overview.system}\n\n${overviewPrompt}`, {
-            cwd: ctx.repoRoot,
-            model: deps.model,
-            allowedTools: [],
+        const contentMd = composeOverview({
+            repoName: `${ctx.hubFullName} — Wiki`,
+            modules: overviewModules,
+            architectureMermaid,
         });
-        return { title: 'Overview', contentMd: extractPageMarkdown(result.text) };
+        return { title: 'Overview', contentMd };
     };
     // Execute: leaves → parents → overview
     const overviewNode = { slug: 'overview', title: 'Overview', files: [] };
@@ -283,7 +498,134 @@ export async function runWikiUpload(opts, deps) {
         summary: m.summary,
         files: m.files,
     }));
-    info('Phase 3/3: streaming pages to Hub + generating overview...');
+    // Dry-run: stream every generated page to disk as it completes, so partial
+    // output is preserved on timeout/interrupt. Never touches the Hub upload
+    // session. Pages land in completion order (not tree order); the TOC at the
+    // top of the file is in tree order and uses slug anchors so you can jump.
+    if (opts.dryRunOutputPath) {
+        const concurrency = resolveConcurrency(opts.concurrency);
+        const total = orderedModules.length;
+        let doneCount = 0;
+        let failedCount = 0;
+        const runStartAt = Date.now();
+        // Write header + TOC up front (titles are all known after module-tree phase)
+        await fs.writeFile(opts.dryRunOutputPath, formatDryRunHeader({
+            repoFullName: ctx.hubFullName,
+            headCommit: ctx.headCommit,
+            model: deps.model,
+            modules: orderedModules.map((n) => ({ title: n.title, slug: n.slug })),
+        }), 'utf-8');
+        info(`  streaming output to ${opts.dryRunOutputPath}`);
+        // Serialize appends so concurrent leaves don't interleave writes.
+        let writeLock = Promise.resolve();
+        const appendPage = (page) => {
+            writeLock = writeLock.then(() => fs.appendFile(opts.dryRunOutputPath, formatDryRunPage(page), 'utf-8'));
+            return writeLock;
+        };
+        const tryGenerate = async (node) => {
+            if (opts.abortSignal?.aborted)
+                throw new GnxError(ErrorCode.USER_ABORTED, 'aborted during dry-run generation');
+            info(`  [${doneCount + 1}/${total}] ${node.title} — generating...`);
+            let page;
+            try {
+                const result = await generatePageByType(node);
+                page = { title: result.title, slug: node.slug, contentMd: result.contentMd };
+            }
+            catch (err) {
+                failedCount++;
+                page = {
+                    title: node.title,
+                    slug: node.slug,
+                    contentMd: `# ${node.title}\n\n_(Generation failed: ${err instanceof Error ? err.message : String(err)})_`,
+                };
+            }
+            await appendPage(page);
+            doneCount++;
+            const elapsed = formatDuration(Date.now() - runStartAt);
+            const pct = Math.round((doneCount / total) * 100);
+            info(`  [${doneCount}/${total}] ${node.title} — done · ${pct}% · total ${elapsed}`);
+        };
+        try {
+            // Phase 2a: leaves in parallel (they don't depend on each other)
+            info(`  running ${leaves.length} leaf page(s) at concurrency ${concurrency}...`);
+            await runConcurrent(leaves, tryGenerate, {
+                concurrency,
+                abortSignal: opts.abortSignal,
+                onRateLimit: (c) => warn(`  rate limited — concurrency → ${c}`),
+            });
+            // Phase 2b (Phase 5.1 mirror): parents in parallel. Children's content
+            // is already in `generatedPages` after the leaf phase resolves, so
+            // parents can fan out without races.
+            if (parents.length > 0) {
+                info(`  running ${parents.length} parent page(s) at concurrency ${concurrency}...`);
+                await runConcurrent(parents, tryGenerate, {
+                    concurrency,
+                    abortSignal: opts.abortSignal,
+                    onRateLimit: (c) => warn(`  rate limited — concurrency → ${c}`),
+                });
+            }
+            // Phase 3: overview single (depends on leaves + parents)
+            await tryGenerate(overviewNode);
+        }
+        finally {
+            // Flush any pending appends even if we're bailing out early so partial
+            // output on disk is consistent.
+            await writeLock.catch(() => { });
+        }
+        return {
+            sessionId: '(dry-run)',
+            pagesPersisted: doneCount - failedCount,
+            failedSlugs: [],
+        };
+    }
+    // Incremental path: regenerate only affected modules using local git diff.
+    // Falls through to full gen below on any signal the state can't support it.
+    if (opts.mode === 'incremental') {
+        // Pre-populate generatedPages from the Hub so generateOverview sees
+        // real summaries for unchanged modules, not "(Documentation pending)".
+        await Promise.all(allPageNodes.map(async (node) => {
+            const existing = await ctx.api.wikiPage(ctx.hubRepoId, node.slug);
+            if (existing?.content)
+                generatedPages.set(node.slug, existing.content);
+        }));
+        const regenerateModule = async (node) => {
+            const moduleNode = { slug: node.slug, title: node.name, files: node.files };
+            const treeNode = parents.find((p) => p.slug === node.slug);
+            if (treeNode?.children)
+                return generateParentPage(treeNode);
+            return generateLeafPage(moduleNode);
+        };
+        const regenerateOverview = async () => generateOverview();
+        try {
+            const incResult = await tryIncrementalUpload({
+                repoId: ctx.hubRepoId,
+                repoRoot: ctx.repoRoot,
+                headCommit: ctx.headCommit,
+                clientVersion: deps.clientVersion,
+                clientModel: deps.model,
+                api: ctx.api,
+                regenerateModule: regenerateModule,
+                regenerateOverview: regenerateOverview,
+                precomputedStatus,
+                precomputedDiff,
+            });
+            if (incResult.status === 'ok') {
+                return {
+                    sessionId: incResult.sessionId,
+                    pagesPersisted: incResult.pagesPersisted,
+                    failedSlugs: [],
+                };
+            }
+            // else fall through to full gen
+        }
+        catch (err) {
+            if (opts.abortSignal?.aborted) {
+                throw new GnxError(ErrorCode.USER_ABORTED, 'user aborted', { cause: err });
+            }
+            // Incremental path threw — fall through to full gen as a safety net.
+        }
+    }
+    info(`Phase 3/3: streaming ${orderedModules.length} page(s) to Hub...`);
     let activeSessionId = null;
     const onAbort = async () => {
         if (!activeSessionId)
@@ -296,20 +638,50 @@ export async function runWikiUpload(opts, deps) {
         }
     };
     opts.abortSignal?.addEventListener('abort', onAbort, { once: true });
+    const total = orderedModules.length;
+    const titleBySlug = new Map(orderedModules.map((m) => [m.slug, m.title]));
+    const pageStartAt = new Map();
+    const runStartAt = Date.now();
+    let startedCount = 0;
+    let doneCount = 0;
+    const sessionConcurrency = resolveConcurrency(opts.concurrency);
     try {
         return await runWikiUploadSession({
             api: ctx.api,
             repoId: ctx.hubRepoId,
-            mode: opts.mode ?? 'full',
+            mode: 'full',
             fromCommit: ctx.headCommit,
             clientVersion: deps.clientVersion,
             clientModel: deps.model,
             modules: orderedModules,
             moduleTree,
             generatePage: generatePageByType,
+            parallelCount: leaves.length,
+            concurrency: sessionConcurrency,
+            onRateLimit: (c) => warn(`rate limited — concurrency → ${c}`),
             onSessionStart: (id) => {
                 activeSessionId = id;
             },
+            onPageStart: (slug) => {
+                startedCount += 1;
+                pageStartAt.set(slug, Date.now());
+                const title = titleBySlug.get(slug) ?? slug;
+                info(`[${startedCount}/${total}] ${title} — generating...`);
+            },
+            onPageDone: (slug, bytes) => {
+                doneCount += 1;
+                const startedAt = pageStartAt.get(slug) ?? Date.now();
+                const elapsed = formatDuration(Date.now() - startedAt);
+                const totalElapsed = formatDuration(Date.now() - runStartAt);
+                const pct = Math.round((doneCount / total) * 100);
+                const title = titleBySlug.get(slug) ?? slug;
+                info(`[${doneCount}/${total}] ${title} — uploaded (${formatBytes(bytes)}, ${elapsed}) · ${pct}% · total ${totalElapsed}`);
+            },
+            onPageFail: (slug, err) => {
+                const title = titleBySlug.get(slug) ?? slug;
+                const msg = err instanceof Error ? err.message : String(err);
+                warn(`[${startedCount}/${total}] ${title} — failed: ${msg}`);
+            },
         });
     }
     catch (err) {