gitnexushub 0.4.2 → 0.4.4

package/dist/wiki/real-deps.d.ts

@@ -0,0 +1,9 @@
+import { createClaudeRunner } from './claude.js';
+import type { ResolveContextDeps } from './resolve-context.js';
+export declare const REAL_CLIENT_VERSION: string;
+export declare const REAL_DEFAULT_MODEL: string;
+export declare function buildRealDeps(cwd: string): ResolveContextDeps & {
+    createClaudeRunner: typeof createClaudeRunner;
+    clientVersion: string;
+    model: string;
+};

package/dist/wiki/real-deps.js

@@ -0,0 +1,63 @@
+import { execFileSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { HubAPI } from '../api.js';
+import { loadConfig as loadConnectConfig } from '../config.js';
+import { createClaudeRunner } from './claude.js';
+export const REAL_CLIENT_VERSION = 'gnx/' + (process.env.npm_package_version ?? 'dev');
+export const REAL_DEFAULT_MODEL = process.env.GNX_WIKI_MODEL ?? 'claude-sonnet-4-6';
+function runGit(cwd, args) {
+    try {
+        return execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'ignore'] })
+            .toString('utf-8')
+            .trim();
+    }
+    catch {
+        return null;
+    }
+}
+export function buildRealDeps(cwd) {
+    return {
+        cwd,
+        loadConfig: loadConnectConfig,
+        getGitRoot: (c) => runGit(c, ['rev-parse', '--show-toplevel']),
+        getGitRemoteUrl: (c) => runGit(c, ['remote', 'get-url', 'origin']),
+        getGitHead: (c) => runGit(c, ['rev-parse', 'HEAD']),
+        getGitDirty: (c) => {
+            const out = runGit(c, ['status', '--porcelain']);
+            return (out?.length ?? 0) > 0;
+        },
+        buildApi: (hubUrl, token) => new HubAPI(hubUrl, token),
+        verifyClaudeCodeInstalled: async () => {
+            try {
+                execFileSync('claude', ['--version'], { stdio: 'ignore' });
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        verifyClaudeCodeMcpRegistered: async (hubUrl) => {
+            try {
+                const claudeJson = path.join(os.homedir(), '.claude.json');
+                if (!fs.existsSync(claudeJson))
+                    return false;
+                const parsed = JSON.parse(fs.readFileSync(claudeJson, 'utf-8'));
+                const mcpServers = parsed?.mcpServers ?? {};
+                for (const key of Object.keys(mcpServers)) {
+                    const entry = mcpServers[key];
+                    if (entry?.url && String(entry.url).startsWith(hubUrl))
+                        return true;
+                }
+                return false;
+            }
+            catch {
+                return false;
+            }
+        },
+        createClaudeRunner,
+        clientVersion: REAL_CLIENT_VERSION,
+        model: REAL_DEFAULT_MODEL,
+    };
+}

package/dist/wiki/resolve-context.d.ts

@@ -0,0 +1,31 @@
+import type { HubAPI } from '../api.js';
+export interface WikiContext {
+    repoRoot: string;
+    headCommit: string;
+    isDirty: boolean;
+    canonicalRemote: string;
+    hubRepoId: string;
+    hubFullName: string;
+    hubIndexedCommit: string | null;
+    hubIndexedStatus: string;
+    hubUrl: string;
+    api: HubAPI;
+}
+export interface ResolveContextDeps {
+    cwd: string;
+    loadConfig: () => Promise<{
+        hubToken?: string;
+        hubUrl?: string;
+    }>;
+    getGitRemoteUrl: (cwd: string) => string | null;
+    getGitRoot: (cwd: string) => string | null;
+    getGitHead: (cwd: string) => string | null;
+    getGitDirty: (cwd: string) => boolean;
+    buildApi: (hubUrl: string, token: string) => HubAPI;
+    verifyClaudeCodeInstalled: () => Promise<boolean>;
+    verifyClaudeCodeMcpRegistered: (hubUrl: string) => Promise<boolean>;
+}
+export interface ResolveContextOptions {
+    skipClaudeChecks?: boolean;
+}
+export declare function resolveWikiContext(deps: ResolveContextDeps, opts?: ResolveContextOptions): Promise<WikiContext>;

package/dist/wiki/resolve-context.js

@@ -0,0 +1,82 @@
+import { canonicalizeGitRemote } from '../git-remote.js';
+import { GnxError, ErrorCode } from './errors.js';
+export async function resolveWikiContext(deps, opts = {}) {
+    const repoRoot = deps.getGitRoot(deps.cwd);
+    if (!repoRoot) {
+        throw new GnxError(ErrorCode.NOT_GIT_REPO, 'not a git repository', {
+            hint: 'cd into your project, or run: gnx wiki <path>',
+        });
+    }
+    const headCommit = deps.getGitHead(repoRoot);
+    if (!headCommit) {
+        throw new GnxError(ErrorCode.NO_COMMITS, 'git repository has no commits yet', {
+            hint: 'commit something before generating a wiki',
+        });
+    }
+    const rawRemote = deps.getGitRemoteUrl(repoRoot);
+    if (!rawRemote) {
+        throw new GnxError(ErrorCode.NO_REMOTE, "no 'origin' remote found", {
+            hint: 'add one with: git remote add origin <url>',
+        });
+    }
+    if (rawRemote.startsWith('/') ||
+        /^[a-zA-Z]:[\\/]/.test(rawRemote) ||
+        rawRemote.startsWith('file://')) {
+        throw new GnxError(ErrorCode.LOCAL_PATH_REMOTE, `origin points at a local path ('${rawRemote}')`, { hint: 'gnx needs a public/forge URL to match against the Hub' });
+    }
+    const canonicalRemote = canonicalizeGitRemote(rawRemote);
+    if (!canonicalRemote) {
+        throw new GnxError(ErrorCode.UNPARSEABLE_REMOTE, `origin is '${rawRemote}' which isn't a recognized git URL`, { hint: 'pass --remote <name> to use a different remote' });
+    }
+    const isDirty = deps.getGitDirty(repoRoot);
+    const config = await deps.loadConfig();
+    if (!config.hubToken) {
+        throw new GnxError(ErrorCode.NOT_CONNECTED, 'not connected to the Hub', {
+            hint: 'run: gnx connect <token>',
+        });
+    }
+    const hubUrl = config.hubUrl || 'https://gitnexus-enterprise-production.up.railway.app';
+    if (!opts.skipClaudeChecks) {
+        if (!(await deps.verifyClaudeCodeInstalled())) {
+            throw new GnxError(ErrorCode.CLAUDE_NOT_INSTALLED, "Claude Code isn't installed or on PATH", {
+                hint: 'install: https://claude.com/claude-code',
+            });
+        }
+        if (!(await deps.verifyClaudeCodeMcpRegistered(hubUrl))) {
+            throw new GnxError(ErrorCode.CLAUDE_MCP_MISSING, "Claude Code isn't wired to the Hub MCP server", { hint: 're-run: gnx connect' });
+        }
+    }
+    const api = deps.buildApi(hubUrl, config.hubToken);
+    let resolve;
+    try {
+        resolve = await api.resolveRepoByRemote(canonicalRemote);
+    }
+    catch (err) {
+        const msg = err?.message ?? String(err);
+        if (msg.includes('404') || msg.toLowerCase().includes('not found')) {
+            throw new GnxError(ErrorCode.REPO_NOT_ON_HUB, `${canonicalRemote} isn't indexed on the Hub`, {
+                hint: 'add it with: gnx index <owner>/<repo>',
+                cause: err,
+            });
+        }
+        throw new GnxError(ErrorCode.NETWORK, `Hub request failed: ${msg}`, { cause: err });
+    }
+    if (resolve.status !== 'ready') {
+        throw new GnxError(ErrorCode.REPO_NOT_INDEXED, `${resolve.fullName} is on the Hub but still ${resolve.status}`, { hint: 'wait for indexing, or run: gnx sync --wait' });
+    }
+    if (!resolve.permissions.write) {
+        throw new GnxError(ErrorCode.REPO_READ_ONLY, `you have read-only access to ${resolve.fullName}`, { hint: 'wiki uploads require write access — ask an owner to grant write' });
+    }
+    return {
+        repoRoot,
+        headCommit,
+        isDirty,
+        canonicalRemote,
+        hubRepoId: resolve.repoId,
+        hubFullName: resolve.fullName,
+        hubIndexedCommit: resolve.lastCommit,
+        hubIndexedStatus: resolve.status,
+        hubUrl,
+        api,
+    };
+}

package/dist/wiki/session.d.ts

@@ -0,0 +1,34 @@
+import type { HubAPI } from '../api.js';
+export interface ModuleNode {
+    slug: string;
+    title: string;
+    summary?: string;
+    files?: string[];
+}
+export interface GeneratePageFn {
+    (node: ModuleNode): Promise<{
+        title: string;
+        contentMd: string;
+    }>;
+}
+export interface RunSessionDeps {
+    api: HubAPI;
+    repoId: string;
+    mode: 'full' | 'incremental';
+    fromCommit: string;
+    clientVersion: string;
+    clientModel: string;
+    modules: ModuleNode[];
+    moduleTree: unknown;
+    generatePage: GeneratePageFn;
+    onSessionStart?: (sessionId: string) => void;
+    onPageStart?: (slug: string) => void;
+    onPageDone?: (slug: string, bytes: number) => void;
+    onPageFail?: (slug: string, err: unknown) => void;
+}
+export interface RunSessionResult {
+    sessionId: string;
+    pagesPersisted: number;
+    failedSlugs: string[];
+}
+export declare function runWikiUploadSession(deps: RunSessionDeps): Promise<RunSessionResult>;

package/dist/wiki/session.js

@@ -0,0 +1,73 @@
+import { GnxError, ErrorCode } from './errors.js';
+export async function runWikiUploadSession(deps) {
+    const { api, repoId } = deps;
+    const started = await api.wikiUploadStart(repoId, {
+        mode: deps.mode,
+        fromCommit: deps.fromCommit,
+        clientVersion: deps.clientVersion,
+        clientModel: deps.clientModel,
+    });
+    const sessionId = started.sessionId;
+    deps.onSessionStart?.(sessionId);
+    const receivedSlugs = [];
+    const failedSlugs = [];
+    let aborted = false;
+    const abortOnce = async (reason) => {
+        if (aborted)
+            return;
+        aborted = true;
+        try {
+            await api.wikiUploadAbort(repoId, sessionId);
+        }
+        catch {
+            /* ignore secondary errors */
+        }
+        throw reason instanceof Error
+            ? reason
+            : new GnxError(ErrorCode.GENERATION_FAILED, String(reason));
+    };
+    for (const mod of deps.modules) {
+        deps.onPageStart?.(mod.slug);
+        let page;
+        try {
+            page = await deps.generatePage(mod);
+        }
+        catch (err) {
+            failedSlugs.push(mod.slug);
+            deps.onPageFail?.(mod.slug, err);
+            try {
+                page = await deps.generatePage(mod);
+                failedSlugs.splice(failedSlugs.indexOf(mod.slug), 1);
+            }
+            catch (err2) {
+                deps.onPageFail?.(mod.slug, err2);
+                continue;
+            }
+        }
+        if (!page.contentMd || !page.contentMd.trim()) {
+            failedSlugs.push(mod.slug);
+            deps.onPageFail?.(mod.slug, new Error('empty generation result'));
+            continue;
+        }
+        try {
+            await api.wikiUploadPage(repoId, sessionId, {
+                slug: mod.slug,
+                title: page.title,
+                contentMd: page.contentMd,
+            });
+            receivedSlugs.push(mod.slug);
+            deps.onPageDone?.(mod.slug, Buffer.byteLength(page.contentMd, 'utf8'));
+        }
+        catch (err) {
+            await abortOnce(err);
+        }
+    }
+    if (receivedSlugs.length === 0) {
+        await abortOnce(new GnxError(ErrorCode.GENERATION_FAILED, 'no pages were generated successfully'));
+    }
+    const finished = await api.wikiUploadFinish(repoId, sessionId, {
+        moduleTree: deps.moduleTree,
+        receivedSlugs,
+    });
+    return { sessionId, pagesPersisted: finished.pagesPersisted, failedSlugs };
+}

package/dist/wiki/status-command.d.ts

@@ -0,0 +1,8 @@
+import type { ResolveContextDeps } from './resolve-context.js';
+export declare function runWikiStatus(deps: ResolveContextDeps): Promise<{
+    fullName: string;
+    canonicalRemote: string;
+    hubIndexedCommit: string | null;
+    active: unknown;
+    last: unknown;
+}>;

package/dist/wiki/status-command.js

@@ -0,0 +1,12 @@
+import { resolveWikiContext } from './resolve-context.js';
+export async function runWikiStatus(deps) {
+    const ctx = await resolveWikiContext(deps, { skipClaudeChecks: true });
+    const status = await ctx.api.wikiUploadStatus(ctx.hubRepoId);
+    return {
+        fullName: ctx.hubFullName,
+        canonicalRemote: ctx.canonicalRemote,
+        hubIndexedCommit: ctx.hubIndexedCommit,
+        active: status.active,
+        last: status.last,
+    };
+}

package/dist/wiki/upload-command.d.ts

@@ -0,0 +1,19 @@
+import type { ClaudeRunner } from './claude.js';
+import { type ResolveContextDeps } from './resolve-context.js';
+export interface RunWikiUploadOptions {
+    cwd: string;
+    mode?: 'full' | 'incremental';
+    model?: string;
+    abortSignal?: AbortSignal;
+}
+export interface RunWikiUploadDeps extends ResolveContextDeps {
+    createClaudeRunner: () => ClaudeRunner;
+    clientVersion: string;
+    model: string;
+}
+export interface RunWikiUploadResult {
+    pagesPersisted: number;
+    failedSlugs: string[];
+    sessionId: string;
+}
+export declare function runWikiUpload(opts: RunWikiUploadOptions, deps: RunWikiUploadDeps): Promise<RunWikiUploadResult>;

package/dist/wiki/upload-command.js

@@ -0,0 +1,320 @@
+import { resolveWikiContext } from './resolve-context.js';
+import { runWikiUploadSession } from './session.js';
+import { GnxError, ErrorCode } from './errors.js';
+import { info } from '../cli-helpers.js';
+function slugify(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '');
+}
+function parseModuleTree(raw) {
+    const cleaned = raw
+        .trim()
+        .replace(/^```(?:json)?\s*/i, '')
+        .replace(/```$/, '')
+        .trim();
+    let parsed;
+    try {
+        parsed = JSON.parse(cleaned);
+    }
+    catch (err) {
+        throw new GnxError(ErrorCode.GENERATION_FAILED, 'module tree response was not valid JSON', {
+            cause: err,
+        });
+    }
+    if (parsed && !Array.isArray(parsed.modules) && typeof parsed === 'object') {
+        const modules = [];
+        for (const [name, files] of Object.entries(parsed)) {
+            if (!Array.isArray(files))
+                continue;
+            const slug = slugify(name);
+            if (!slug)
+                continue;
+            modules.push({
+                slug,
+                title: name,
+                files: files.filter((f) => typeof f === 'string'),
+            });
+        }
+        if (modules.length > 0)
+            return modules;
+    }
+    throw new GnxError(ErrorCode.GENERATION_FAILED, 'module tree had no valid modules');
+}
+const SPLIT_FILE_THRESHOLD = 20;
+function splitBySubdirectory(parentName, files) {
+    const subGroups = new Map();
+    for (const fp of files) {
+        const parts = fp.replace(/\\/g, '/').split('/');
+        const subDir = parts.length > 2 ? parts.slice(0, 2).join('/') : parts[0];
+        let group = subGroups.get(subDir);
+        if (!group) {
+            group = [];
+            subGroups.set(subDir, group);
+        }
+        group.push(fp);
+    }
+    const basenames = Array.from(subGroups.keys()).map((s) => s.split('/').pop());
+    const hasCollisions = new Set(basenames).size < basenames.length;
+    return Array.from(subGroups.entries()).map(([subDir, subFiles]) => {
+        const label = hasCollisions ? subDir.replace(/\//g, '-') : subDir.split('/').pop();
+        return {
+            slug: slugify(`${parentName}-${label}`),
+            title: `${parentName} — ${label}`,
+            files: subFiles,
+        };
+    });
+}
+function applyModuleSplitting(modules) {
+    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 = [];
+            }
+        }
+    }
+    return modules;
+}
+function flattenModuleTree(tree) {
+    const leaves = [];
+    const parents = [];
+    for (const node of tree) {
+        if (node.children && node.children.length > 0) {
+            for (const child of node.children)
+                leaves.push(child);
+            parents.push(node);
+        }
+        else {
+            leaves.push(node);
+        }
+    }
+    return { leaves, parents };
+}
+function extractPageMarkdown(raw) {
+    const trimmed = raw.trim();
+    if (trimmed.startsWith('```')) {
+        return trimmed
+            .replace(/^```(?:markdown)?\s*/i, '')
+            .replace(/```$/, '')
+            .trim();
+    }
+    return trimmed;
+}
+function fillTemplate(template, vars) {
+    let result = template;
+    for (const [key, value] of Object.entries(vars)) {
+        result = result.replaceAll(`{{${key}}}`, value);
+    }
+    return result;
+}
+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');
+    const runner = deps.createClaudeRunner();
+    info(`Fetching graph context from Hub (${ctx.hubFullName})...`);
+    const [prompts, groupingCtx] = await Promise.all([
+        ctx.api.wikiPromptTemplates(ctx.hubRepoId),
+        ctx.api.wikiGroupingContext(ctx.hubRepoId),
+    ]);
+    // Phase 1: Module tree
+    info('Phase 1/3: generating module tree with Claude Code...');
+    const groupingPrompt = fillTemplate(prompts.grouping.user, {
+        COMMUNITY_GROUPS: groupingCtx.communityGroups,
+        INTER_COMMUNITY_EDGES: groupingCtx.interCommunityEdges,
+        CROSS_COMMUNITY_PROCESSES: groupingCtx.crossCommunityProcesses,
+        FILE_LIST: groupingCtx.filesWithExports,
+        DIRECTORY_TREE: groupingCtx.directoryTree,
+    });
+    const moduleTreeRaw = await runner.run(`${prompts.grouping.system}\n\n${groupingPrompt}`, {
+        cwd: ctx.repoRoot,
+        model: deps.model,
+        allowedTools: [],
+    });
+    const rawModules = parseModuleTree(moduleTreeRaw.text);
+    const modules = applyModuleSplitting(rawModules);
+    const { leaves, parents } = flattenModuleTree(modules);
+    const allPageNodes = [...leaves, ...parents];
+    const moduleRegistry = allPageNodes.map((m) => `- [${m.title}](${m.slug}.md)`).join('\n');
+    const generatedPages = new Map();
+    info(`Phase 2/3: generating ${leaves.length} leaf page(s) + ${parents.length} parent page(s)...`);
+    if (opts.abortSignal?.aborted)
+        throw new GnxError(ErrorCode.USER_ABORTED, 'aborted before page generation');
+    // Phase 2a: Leaf pages
+    const generateLeafPage = async (node) => {
+        if (opts.abortSignal?.aborted)
+            throw new GnxError(ErrorCode.USER_ABORTED, 'aborted during page generation');
+        const filePaths = node.files ?? [];
+        let leafCtx;
+        try {
+            leafCtx = await ctx.api.wikiLeafContext(ctx.hubRepoId, node.title, filePaths);
+        }
+        catch {
+            leafCtx = {
+                sourceCode: '',
+                intraCalls: 'None',
+                outgoingCalls: 'None',
+                incomingCalls: '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 pagePrompt = fillTemplate(prompts.module.user, {
+            MODULE_NAME: node.title,
+            SOURCE_CODE: leafCtx.sourceCode,
+            INTRA_CALLS: leafCtx.intraCalls,
+            OUTGOING_CALLS: leafCtx.outgoingCalls,
+            INCOMING_CALLS: leafCtx.incomingCalls,
+            PROCESSES: leafCtx.processes,
+            MODULE_REGISTRY: reg,
+        });
+        const result = await runner.run(`${prompts.module.system}\n\n${pagePrompt}`, {
+            cwd: ctx.repoRoot,
+            model: deps.model,
+            allowedTools: [],
+        });
+        const content = `# ${node.title}\n\n${extractPageMarkdown(result.text)}`;
+        generatedPages.set(node.slug, content);
+        return { title: node.title, contentMd: content };
+    };
+    // Phase 2b: Parent pages
+    const generateParentPage = async (node) => {
+        if (opts.abortSignal?.aborted)
+            throw new GnxError(ErrorCode.USER_ABORTED, 'aborted during parent page generation');
+        const childDocs = (node.children ?? [])
+            .map((child) => {
+            const content = generatedPages.get(child.slug);
+            return content
+                ? `#### ${child.title}\n${content.slice(0, 800).trim()}`
+                : `#### ${child.title}\n(Documentation not yet generated)`;
+        })
+            .join('\n\n');
+        const allChildFiles = (node.children ?? []).flatMap((c) => c.files ?? []);
+        let parentCtx;
+        try {
+            parentCtx = await ctx.api.wikiLeafContext(ctx.hubRepoId, node.title, allChildFiles);
+        }
+        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 parentPrompt = fillTemplate(prompts.parent.user, {
+            MODULE_NAME: node.title,
+            CHILDREN_DOCS: childDocs,
+            CROSS_MODULE_CALLS: parentCtx.intraCalls ?? 'None',
+            CROSS_PROCESSES: parentCtx.processes ?? 'No execution flows detected.',
+            MODULE_REGISTRY: reg,
+        });
+        const result = await runner.run(`${prompts.parent.system}\n\n${parentPrompt}`, {
+            cwd: ctx.repoRoot,
+            model: deps.model,
+            allowedTools: [],
+        });
+        const content = `# ${node.title}\n\n${extractPageMarkdown(result.text)}`;
+        generatedPages.set(node.slug, content);
+        return { title: node.title, contentMd: content };
+    };
+    // Phase 3: Overview page
+    const generateOverview = async () => {
+        if (opts.abortSignal?.aborted)
+            throw new GnxError(ErrorCode.USER_ABORTED, 'aborted during overview generation');
+        const moduleSummaries = 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');
+        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;
+        try {
+            overviewCtx = await ctx.api.wikiOverviewContext(ctx.hubRepoId, moduleFiles);
+        }
+        catch {
+            overviewCtx = {
+                interModuleEdges: 'No inter-module call edges detected',
+                topProcesses: 'No execution flows detected.',
+            };
+        }
+        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: [],
+        });
+        return { title: 'Overview', contentMd: extractPageMarkdown(result.text) };
+    };
+    // Execute: leaves → parents → overview
+    const overviewNode = { slug: 'overview', title: 'Overview', files: [] };
+    const orderedModules = [...leaves, ...parents, overviewNode];
+    const generatePageByType = async (node) => {
+        if (node.slug === 'overview' && (node.files ?? []).length === 0)
+            return generateOverview();
+        const treeNode = parents.find((p) => p.slug === node.slug);
+        if (treeNode?.children)
+            return generateParentPage(treeNode);
+        return generateLeafPage(node);
+    };
+    const moduleTree = orderedModules.map((m) => ({
+        name: m.title,
+        slug: m.slug,
+        summary: m.summary,
+        files: m.files,
+    }));
+    info('Phase 3/3: streaming pages to Hub + generating overview...');
+    let activeSessionId = null;
+    const onAbort = async () => {
+        if (!activeSessionId)
+            return;
+        try {
+            await ctx.api.wikiUploadAbort(ctx.hubRepoId, activeSessionId);
+        }
+        catch {
+            /* ignore secondary errors */
+        }
+    };
+    opts.abortSignal?.addEventListener('abort', onAbort, { once: true });
+    try {
+        return await runWikiUploadSession({
+            api: ctx.api,
+            repoId: ctx.hubRepoId,
+            mode: opts.mode ?? 'full',
+            fromCommit: ctx.headCommit,
+            clientVersion: deps.clientVersion,
+            clientModel: deps.model,
+            modules: orderedModules,
+            moduleTree,
+            generatePage: generatePageByType,
+            onSessionStart: (id) => {
+                activeSessionId = id;
+            },
+        });
+    }
+    catch (err) {
+        if (opts.abortSignal?.aborted)
+            throw new GnxError(ErrorCode.USER_ABORTED, 'user aborted', { cause: err });
+        throw err;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexushub",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "Connect your editor to GitNexus Hub — one command MCP setup + project context",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",
@@ -35,6 +35,7 @@
     "prepare": "npm run build"
   },
   "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.109",
     "commander": "^12.0.0",
     "picocolors": "^1.1.1",
     "tar-stream": "^3.1.8"