gitnexushub 0.4.2 → 0.4.4

package/dist/api.d.ts

@@ -72,6 +72,55 @@ export interface SyncJobStatus {
     phase: string | null;
     error: string | null;
 }
+export interface ResolveRepoResult {
+    repoId: string;
+    fullName: string;
+    status: string;
+    indexedAt: string | null;
+    lastCommit: string | null;
+    permissions: {
+        read: boolean;
+        write: boolean;
+    };
+}
+export interface WikiUploadStartParams {
+    mode: 'full' | 'incremental';
+    fromCommit?: string;
+    clientVersion?: string;
+    clientModel?: string;
+}
+export interface WikiUploadStartResult {
+    sessionId: string;
+    status: 'active';
+    startedAt: string;
+}
+export interface WikiUploadPagePayload {
+    slug: string;
+    title: string;
+    contentMd: string;
+}
+export interface WikiUploadFinishParams {
+    moduleTree: unknown;
+    receivedSlugs: string[];
+}
+export interface WikiConfig {
+    serverGenerationEnabled: boolean;
+    clientUploadAvailable: boolean;
+    clientCommand: string;
+}
+export interface WikiUploadSessionRow {
+    id: string;
+    userId: string;
+    status: 'active' | 'finished' | 'aborted' | 'stale';
+    mode: 'full' | 'incremental';
+    pagesReceived: number;
+    startedAt: string;
+    finishedAt: string | null;
+}
+export interface WikiUploadStatus {
+    active: WikiUploadSessionRow | null;
+    last: WikiUploadSessionRow | null;
+}
 export declare class HubAPI {
     private hubUrl;
     private token;
@@ -81,6 +130,7 @@ export declare class HubAPI {
     private get authHeaders();
     private request;
     private post;
+    private postJson;
     getMe(): Promise<UserProfile>;
     listRepos(): Promise<HubRepo[]>;
     getConnectContext(repoFullName: string): Promise<ConnectContext>;
@@ -92,4 +142,41 @@ export declare class HubAPI {
         tarball: NodeJS.ReadableStream;
     }): Promise<SyncResult>;
     syncStatus(repoId: string, jobId: string): Promise<SyncJobStatus>;
+    resolveRepoByRemote(remote: string): Promise<ResolveRepoResult>;
+    wikiUploadStart(repoId: string, params: WikiUploadStartParams): Promise<WikiUploadStartResult>;
+    wikiUploadPage(repoId: string, sessionId: string, page: WikiUploadPagePayload): Promise<{
+        slug: string;
+        pagesReceived: number;
+    }>;
+    wikiUploadFinish(repoId: string, sessionId: string, params: WikiUploadFinishParams): Promise<{
+        sessionId: string;
+        pagesPersisted: number;
+    }>;
+    wikiUploadAbort(repoId: string, sessionId: string): Promise<{
+        sessionId: string;
+        status: string;
+    }>;
+    wikiUploadStatus(repoId: string): Promise<WikiUploadStatus>;
+    getWikiConfig(): Promise<WikiConfig>;
+    wikiGroupingContext(repoId: string): Promise<any>;
+    wikiLeafContext(repoId: string, moduleName: string, filePaths: string[]): Promise<any>;
+    wikiOverviewContext(repoId: string, moduleFiles: Record<string, string[]>): Promise<any>;
+    wikiPromptTemplates(repoId: string): Promise<{
+        grouping: {
+            system: string;
+            user: string;
+        };
+        module: {
+            system: string;
+            user: string;
+        };
+        parent: {
+            system: string;
+            user: string;
+        };
+        overview: {
+            system: string;
+            user: string;
+        };
+    }>;
 }

package/dist/api.js

@@ -49,6 +49,22 @@ export class HubAPI {
         }
         return res.json();
     }
+    async postJson(path, body, extraHeaders = {}) {
+        const res = await fetch(`${this.hubUrl}${path}`, {
+            method: 'POST',
+            headers: {
+                ...this.authHeaders,
+                'Content-Type': 'application/json',
+                ...extraHeaders,
+            },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const err = await res.json().catch(() => ({ error: res.statusText }));
+            throw new Error(err.error || `HTTP ${res.status}`);
+        }
+        return res.json();
+    }
     async getMe() {
         return this.request('/auth/me');
     }
@@ -103,4 +119,39 @@ export class HubAPI {
     async syncStatus(repoId, jobId) {
         return this.request(`/api/repos/${repoId}/sync/${jobId}`);
     }
+    async resolveRepoByRemote(remote) {
+        return this.postJson('/api/repos/resolve', { remote });
+    }
+    async wikiUploadStart(repoId, params) {
+        return this.postJson(`/api/repos/${repoId}/wiki/upload/start`, params);
+    }
+    async wikiUploadPage(repoId, sessionId, page) {
+        return this.postJson(`/api/repos/${repoId}/wiki/upload/page`, { slug: page.slug, title: page.title, content_md: page.contentMd }, { 'X-Wiki-Upload-Session': sessionId });
+    }
+    async wikiUploadFinish(repoId, sessionId, params) {
+        return this.postJson(`/api/repos/${repoId}/wiki/upload/finish`, params, { 'X-Wiki-Upload-Session': sessionId });
+    }
+    async wikiUploadAbort(repoId, sessionId) {
+        return this.postJson(`/api/repos/${repoId}/wiki/upload/abort`, {}, { 'X-Wiki-Upload-Session': sessionId });
+    }
+    async wikiUploadStatus(repoId) {
+        return this.request(`/api/repos/${repoId}/wiki/upload/status`);
+    }
+    async getWikiConfig() {
+        return this.request(`/api/wiki-config`);
+    }
+    async wikiGroupingContext(repoId) {
+        return this.request(`/api/repos/${repoId}/wiki/context/grouping`);
+    }
+    async wikiLeafContext(repoId, moduleName, filePaths) {
+        const params = new URLSearchParams({ name: moduleName, files: filePaths.join(',') });
+        return this.request(`/api/repos/${repoId}/wiki/context/leaf?${params}`);
+    }
+    async wikiOverviewContext(repoId, moduleFiles) {
+        const params = new URLSearchParams({ moduleFiles: JSON.stringify(moduleFiles) });
+        return this.request(`/api/repos/${repoId}/wiki/context/overview?${params}`);
+    }
+    async wikiPromptTemplates(repoId) {
+        return this.request(`/api/repos/${repoId}/wiki/context/prompts`);
+    }
 }

package/dist/git-remote.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Canonicalizes a git remote URL into "host/path" form so that two variants
+ * of the same upstream (https vs ssh, with/without `.git`, with/without creds)
+ * compare equal. Returns null if the input isn't a recognizable git URL.
+ */
+export declare function canonicalizeGitRemote(raw: string): string | null;

package/dist/git-remote.js

@@ -0,0 +1,57 @@
+const CASE_INSENSITIVE_HOSTS = new Set([
+    'github.com',
+    'gitlab.com',
+    'bitbucket.org',
+    'codeberg.org',
+    'gitea.com',
+]);
+/**
+ * Canonicalizes a git remote URL into "host/path" form so that two variants
+ * of the same upstream (https vs ssh, with/without `.git`, with/without creds)
+ * compare equal. Returns null if the input isn't a recognizable git URL.
+ */
+export function canonicalizeGitRemote(raw) {
+    if (!raw || typeof raw !== 'string')
+        return null;
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return null;
+    // Reject local paths before URL parsing
+    if (trimmed.startsWith('/') || /^[a-zA-Z]:[\\/]/.test(trimmed))
+        return null;
+    if (trimmed.startsWith('file://'))
+        return null;
+    let host;
+    let pathPart;
+    // SCP-style: user@host:path
+    const scpMatch = trimmed.match(/^(?:([^@]+)@)?([^:/@]+):([^:].*)$/);
+    if (scpMatch && !trimmed.includes('://')) {
+        host = scpMatch[2];
+        pathPart = scpMatch[3];
+    }
+    else {
+        try {
+            const url = new URL(trimmed);
+            if (!['http:', 'https:', 'ssh:', 'git:'].includes(url.protocol))
+                return null;
+            host = url.hostname;
+            pathPart = url.pathname;
+        }
+        catch {
+            return null;
+        }
+    }
+    if (!host)
+        return null;
+    // Strip leading/trailing slashes and .git suffix
+    pathPart = pathPart
+        .replace(/^\/+/, '')
+        .replace(/\/+$/, '')
+        .replace(/\.git$/i, '');
+    if (!pathPart)
+        return null;
+    // Lowercase host always; lowercase path only for known case-insensitive hosts
+    const lowerHost = host.toLowerCase();
+    const normalizedPath = CASE_INSENSITIVE_HOSTS.has(lowerHost) ? pathPart.toLowerCase() : pathPart;
+    return `${lowerHost}/${normalizedPath}`;
+}

package/dist/index.js

@@ -18,6 +18,7 @@ import { removeProjectContext } from './context.js';
 import { runSync } from './sync-command.js';
 import { ok, info, warn, fail, resolveAuth, DEFAULT_HUB_URL, EDITORS } from './cli-helpers.js';
 import { runConnect } from './connect-command.js';
+import { registerWikiCommand } from './wiki/index.js';
 const BANNER = [
     ' ██████╗ ██╗████████╗███╗   ██╗███████╗██╗  ██╗██╗   ██╗███████╗',
     '██╔════╝ ██║╚══██╔══╝████╗  ██║██╔════╝╚██╗██╔╝██║   ██║██╔════╝',
@@ -110,6 +111,8 @@ program
         process.exit(1);
     }
 });
+// ─── wiki commands ────────────────────────────────────────────────
+registerWikiCommand(program);
 program.parse();
 // ─── Disconnect Flow ──────────────────────────────────────────────
 async function runDisconnect(opts) {

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

@@ -0,0 +1,7 @@
+import type { ResolveContextDeps } from './resolve-context.js';
+export declare function runWikiAbort(deps: ResolveContextDeps): Promise<{
+    sessionId: string;
+    status: string;
+} | {
+    noActive: true;
+}>;

package/dist/wiki/abort-command.js

@@ -0,0 +1,15 @@
+import { resolveWikiContext } from './resolve-context.js';
+import { GnxError, ErrorCode } from './errors.js';
+export async function runWikiAbort(deps) {
+    const ctx = await resolveWikiContext(deps, { skipClaudeChecks: true });
+    const status = await ctx.api.wikiUploadStatus(ctx.hubRepoId);
+    if (!status.active) {
+        return { noActive: true };
+    }
+    try {
+        return await ctx.api.wikiUploadAbort(ctx.hubRepoId, status.active.id);
+    }
+    catch (err) {
+        throw new GnxError(ErrorCode.NETWORK, 'failed to abort session', { cause: err });
+    }
+}

package/dist/wiki/claude.d.ts

@@ -0,0 +1,12 @@
+export interface ClaudeGenerationResult {
+    text: string;
+    durationMs: number;
+}
+export interface ClaudeRunner {
+    run(prompt: string, opts: {
+        cwd: string;
+        model?: string;
+        allowedTools?: string[];
+    }): Promise<ClaudeGenerationResult>;
+}
+export declare function createClaudeRunner(): ClaudeRunner;

package/dist/wiki/claude.js

@@ -0,0 +1,48 @@
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import { GnxError, ErrorCode } from './errors.js';
+const DEFAULT_ALLOWED_TOOLS = [
+    'Read',
+    'Grep',
+    'mcp__gitnexus__context',
+    'mcp__gitnexus__query',
+    'mcp__gitnexus__group_list',
+    'mcp__gitnexus__group_contracts',
+    'mcp__gitnexus__cypher',
+];
+export function createClaudeRunner() {
+    return {
+        async run(prompt, opts) {
+            const start = Date.now();
+            let finalText = '';
+            try {
+                for await (const msg of query({
+                    prompt,
+                    options: {
+                        cwd: opts.cwd,
+                        model: opts.model,
+                        allowedTools: opts.allowedTools ?? DEFAULT_ALLOWED_TOOLS,
+                    },
+                })) {
+                    const m = msg;
+                    if (m.type === 'result' && typeof m.result === 'string') {
+                        finalText = m.result;
+                    }
+                }
+            }
+            catch (err) {
+                const msg = err?.message ?? String(err);
+                if (/auth|login|credentials/i.test(msg)) {
+                    throw new GnxError(ErrorCode.CLAUDE_AUTH_FAILED, 'Claude Code authentication failed', {
+                        hint: 're-authenticate: run `claude /login`',
+                        cause: err,
+                    });
+                }
+                throw new GnxError(ErrorCode.GENERATION_FAILED, `Claude Code error: ${msg}`, {
+                    cause: err,
+                });
+            }
+            const durationMs = Date.now() - start;
+            return { text: finalText, durationMs };
+        },
+    };
+}

package/dist/wiki/errors.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Typed errors with stable exit codes for `gnx wiki *` commands.
+ *
+ * Exit code ranges (keep stable — used by shell scripts / CI):
+ *  10-19   local git problems
+ *  20-29   repo resolution / Hub repo state
+ *  30-39   auth / config problems
+ *  40-49   Claude Code problems
+ *  50-59   network / Hub reachability
+ *  60-69   permissions (403, read-only)
+ *  70-79   session conflict / rate limit
+ *  80-89   upload validation / in-flight failures
+ */
+export declare enum ErrorCode {
+    NOT_GIT_REPO = "NOT_GIT_REPO",
+    NO_COMMITS = "NO_COMMITS",
+    NO_REMOTE = "NO_REMOTE",
+    UNPARSEABLE_REMOTE = "UNPARSEABLE_REMOTE",
+    LOCAL_PATH_REMOTE = "LOCAL_PATH_REMOTE",
+    NOT_CONNECTED = "NOT_CONNECTED",
+    CONFIG_CORRUPT = "CONFIG_CORRUPT",
+    AUTH_INVALID = "AUTH_INVALID",
+    CLAUDE_NOT_INSTALLED = "CLAUDE_NOT_INSTALLED",
+    CLAUDE_MCP_MISSING = "CLAUDE_MCP_MISSING",
+    CLAUDE_AUTH_FAILED = "CLAUDE_AUTH_FAILED",
+    NETWORK = "NETWORK",
+    HUB_UNREACHABLE = "HUB_UNREACHABLE",
+    REPO_NOT_ON_HUB = "REPO_NOT_ON_HUB",
+    REPO_NOT_INDEXED = "REPO_NOT_INDEXED",
+    REPO_READ_ONLY = "REPO_READ_ONLY",
+    SESSION_CONFLICT = "SESSION_CONFLICT",
+    RATE_LIMITED = "RATE_LIMITED",
+    PAGE_VALIDATION = "PAGE_VALIDATION",
+    PAGE_TOO_LARGE = "PAGE_TOO_LARGE",
+    GENERATION_FAILED = "GENERATION_FAILED",
+    USER_ABORTED = "USER_ABORTED",
+    UNKNOWN = "UNKNOWN"
+}
+export interface GnxErrorOptions {
+    hint?: string;
+    cause?: unknown;
+}
+export declare class GnxError extends Error {
+    readonly code: ErrorCode;
+    readonly exitCode: number;
+    readonly hint?: string;
+    readonly cause?: unknown;
+    constructor(code: ErrorCode, message: string, opts?: GnxErrorOptions);
+}

package/dist/wiki/errors.js

@@ -0,0 +1,78 @@
+/**
+ * Typed errors with stable exit codes for `gnx wiki *` commands.
+ *
+ * Exit code ranges (keep stable — used by shell scripts / CI):
+ *  10-19   local git problems
+ *  20-29   repo resolution / Hub repo state
+ *  30-39   auth / config problems
+ *  40-49   Claude Code problems
+ *  50-59   network / Hub reachability
+ *  60-69   permissions (403, read-only)
+ *  70-79   session conflict / rate limit
+ *  80-89   upload validation / in-flight failures
+ */
+export var ErrorCode;
+(function (ErrorCode) {
+    ErrorCode["NOT_GIT_REPO"] = "NOT_GIT_REPO";
+    ErrorCode["NO_COMMITS"] = "NO_COMMITS";
+    ErrorCode["NO_REMOTE"] = "NO_REMOTE";
+    ErrorCode["UNPARSEABLE_REMOTE"] = "UNPARSEABLE_REMOTE";
+    ErrorCode["LOCAL_PATH_REMOTE"] = "LOCAL_PATH_REMOTE";
+    ErrorCode["NOT_CONNECTED"] = "NOT_CONNECTED";
+    ErrorCode["CONFIG_CORRUPT"] = "CONFIG_CORRUPT";
+    ErrorCode["AUTH_INVALID"] = "AUTH_INVALID";
+    ErrorCode["CLAUDE_NOT_INSTALLED"] = "CLAUDE_NOT_INSTALLED";
+    ErrorCode["CLAUDE_MCP_MISSING"] = "CLAUDE_MCP_MISSING";
+    ErrorCode["CLAUDE_AUTH_FAILED"] = "CLAUDE_AUTH_FAILED";
+    ErrorCode["NETWORK"] = "NETWORK";
+    ErrorCode["HUB_UNREACHABLE"] = "HUB_UNREACHABLE";
+    ErrorCode["REPO_NOT_ON_HUB"] = "REPO_NOT_ON_HUB";
+    ErrorCode["REPO_NOT_INDEXED"] = "REPO_NOT_INDEXED";
+    ErrorCode["REPO_READ_ONLY"] = "REPO_READ_ONLY";
+    ErrorCode["SESSION_CONFLICT"] = "SESSION_CONFLICT";
+    ErrorCode["RATE_LIMITED"] = "RATE_LIMITED";
+    ErrorCode["PAGE_VALIDATION"] = "PAGE_VALIDATION";
+    ErrorCode["PAGE_TOO_LARGE"] = "PAGE_TOO_LARGE";
+    ErrorCode["GENERATION_FAILED"] = "GENERATION_FAILED";
+    ErrorCode["USER_ABORTED"] = "USER_ABORTED";
+    ErrorCode["UNKNOWN"] = "UNKNOWN";
+})(ErrorCode || (ErrorCode = {}));
+const EXIT_CODES = {
+    [ErrorCode.NOT_GIT_REPO]: 10,
+    [ErrorCode.NO_COMMITS]: 11,
+    [ErrorCode.NO_REMOTE]: 12,
+    [ErrorCode.UNPARSEABLE_REMOTE]: 13,
+    [ErrorCode.LOCAL_PATH_REMOTE]: 14,
+    [ErrorCode.REPO_NOT_INDEXED]: 20,
+    [ErrorCode.REPO_NOT_ON_HUB]: 21,
+    [ErrorCode.NOT_CONNECTED]: 30,
+    [ErrorCode.CONFIG_CORRUPT]: 31,
+    [ErrorCode.AUTH_INVALID]: 32,
+    [ErrorCode.CLAUDE_NOT_INSTALLED]: 40,
+    [ErrorCode.CLAUDE_MCP_MISSING]: 41,
+    [ErrorCode.CLAUDE_AUTH_FAILED]: 42,
+    [ErrorCode.NETWORK]: 50,
+    [ErrorCode.HUB_UNREACHABLE]: 51,
+    [ErrorCode.REPO_READ_ONLY]: 62,
+    [ErrorCode.SESSION_CONFLICT]: 70,
+    [ErrorCode.RATE_LIMITED]: 72,
+    [ErrorCode.PAGE_VALIDATION]: 80,
+    [ErrorCode.PAGE_TOO_LARGE]: 81,
+    [ErrorCode.GENERATION_FAILED]: 82,
+    [ErrorCode.USER_ABORTED]: 130,
+    [ErrorCode.UNKNOWN]: 1,
+};
+export class GnxError extends Error {
+    code;
+    exitCode;
+    hint;
+    cause;
+    constructor(code, message, opts = {}) {
+        super(message);
+        this.name = 'GnxError';
+        this.code = code;
+        this.exitCode = EXIT_CODES[code];
+        this.hint = opts.hint;
+        this.cause = opts.cause;
+    }
+}

package/dist/wiki/index.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerWikiCommand(program: Command): void;

package/dist/wiki/index.js

@@ -0,0 +1,118 @@
+import pc from 'picocolors';
+import { ok, info, warn, fail } from '../cli-helpers.js';
+import { buildRealDeps, REAL_DEFAULT_MODEL } from './real-deps.js';
+import { runWikiUpload } from './upload-command.js';
+import { runWikiStatus } from './status-command.js';
+import { runWikiAbort } from './abort-command.js';
+import { GnxError } from './errors.js';
+function reportError(err) {
+    if (err instanceof GnxError) {
+        fail(err.message);
+        if (err.hint)
+            console.error(`    ${pc.dim(err.hint)}`);
+        process.exit(err.exitCode);
+    }
+    fail(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+}
+export function registerWikiCommand(program) {
+    const wiki = program
+        .command('wiki')
+        .description('Generate the wiki locally with Claude Code and upload it to the Hub')
+        .option('--mode <mode>', 'full | incremental', 'full')
+        .option('--model <model>', 'Claude model to use', REAL_DEFAULT_MODEL)
+        .action(async (opts) => {
+        const cwd = process.cwd();
+        const deps = buildRealDeps(cwd);
+        if (opts.model)
+            deps.model = opts.model;
+        const ac = new AbortController();
+        let sigCount = 0;
+        let forceExitTimer = null;
+        const onSig = () => {
+            sigCount++;
+            if (sigCount === 1) {
+                warn('interrupt received — cleaning up (Ctrl+C again to force quit)...');
+                ac.abort();
+                forceExitTimer = setTimeout(() => {
+                    warn('cleanup timed out, forcing exit');
+                    process.exit(130);
+                }, 3000);
+                forceExitTimer.unref();
+            }
+            else {
+                if (forceExitTimer)
+                    clearTimeout(forceExitTimer);
+                process.exit(130);
+            }
+        };
+        process.on('SIGINT', onSig);
+        process.on('SIGTERM', onSig);
+        try {
+            info('Resolving repo context...');
+            const result = await runWikiUpload({ cwd, mode: opts.mode, model: opts.model, abortSignal: ac.signal }, deps);
+            ok(`Uploaded ${result.pagesPersisted} pages.`);
+            if (result.failedSlugs.length > 0) {
+                warn(`${result.failedSlugs.length} page(s) failed: ${result.failedSlugs.join(', ')}`);
+            }
+        }
+        catch (err) {
+            if (ac.signal.aborted) {
+                warn('aborted');
+                process.exit(130);
+            }
+            reportError(err);
+        }
+        finally {
+            if (forceExitTimer)
+                clearTimeout(forceExitTimer);
+            process.off('SIGINT', onSig);
+            process.off('SIGTERM', onSig);
+        }
+    });
+    wiki
+        .command('status')
+        .description('Show the wiki upload status for the current repo')
+        .action(async () => {
+        try {
+            const deps = buildRealDeps(process.cwd());
+            const status = await runWikiStatus(deps);
+            info(`Repo: ${pc.bold(status.fullName)} (${status.canonicalRemote})`);
+            info(`Hub indexed commit: ${status.hubIndexedCommit ?? '(none)'}`);
+            if (status.active) {
+                info(`Active session: ${pc.yellow(status.active.id)} ` +
+                    `started ${status.active.startedAt}, ` +
+                    `${status.active.pagesReceived} pages received`);
+            }
+            else {
+                info('No active upload session.');
+            }
+            if (status.last) {
+                info(`Last session: ${status.last.status}, ` +
+                    `${status.last.pagesReceived} pages, ` +
+                    `started ${status.last.startedAt}`);
+            }
+        }
+        catch (err) {
+            reportError(err);
+        }
+    });
+    wiki
+        .command('abort')
+        .description('Abort the active wiki upload session for the current repo')
+        .action(async () => {
+        try {
+            const deps = buildRealDeps(process.cwd());
+            const result = await runWikiAbort(deps);
+            if ('noActive' in result) {
+                info('No active session to abort.');
+            }
+            else {
+                ok(`Aborted session ${result.sessionId}`);
+            }
+        }
+        catch (err) {
+            reportError(err);
+        }
+    });
+}

package/dist/wiki/prompts.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Prompt templates for client-side wiki generation via Claude Code headless.
+ *
+ * The runner passes these prompts to Claude Code with the user's repo as cwd
+ * and read-only tools (Read, Grep) plus the gitnexus MCP tools available.
+ * Graph context comes from the Hub via MCP — no local LadybugDB needed.
+ */
+export declare function renderModuleTreePrompt(fullName: string): string;
+export declare function renderPagePrompt(fullName: string, moduleSlug: string, moduleTitle: string): string;
+export declare const MODULE_TREE_PROMPT_TEMPLATE: string;
+export declare const PAGE_PROMPT_TEMPLATE: string;

package/dist/wiki/prompts.js

@@ -0,0 +1,72 @@
+/**
+ * Prompt templates for client-side wiki generation via Claude Code headless.
+ *
+ * The runner passes these prompts to Claude Code with the user's repo as cwd
+ * and read-only tools (Read, Grep) plus the gitnexus MCP tools available.
+ * Graph context comes from the Hub via MCP — no local LadybugDB needed.
+ */
+export function renderModuleTreePrompt(fullName) {
+    return `You are generating a repository wiki for the repo "${fullName}".
+
+Your task: produce a JSON module hierarchy for this repo.
+
+Use these MCP tools (they query the live Hub-indexed graph):
+  - mcp__gitnexus__context       — overview of the repo
+  - mcp__gitnexus__group_list    — existing cluster/module groupings
+  - mcp__gitnexus__query         — concept/code search
+
+Output ONLY valid JSON with this exact shape (no prose, no markdown fences):
+
+{
+  "modules": [
+    {
+      "slug": "kebab-case-slug",
+      "title": "Human-Readable Title",
+      "summary": "One-sentence description",
+      "files": ["optional/representative/file.ts"]
+    }
+  ]
+}
+
+Rules:
+- 6–15 top-level modules (adjust based on repo size).
+- "slug" MUST match ^[a-z0-9][a-z0-9/_-]*$ and be unique within the array.
+- Include an "overview" module as the first entry.
+- Group by responsibility, not file type. "parser" > "typescript-files".
+- No duplicates, no empty strings, no trailing punctuation in titles.`;
+}
+export function renderPagePrompt(fullName, moduleSlug, moduleTitle) {
+    return `You are writing a single wiki page for the repo "${fullName}".
+
+Module: "${moduleSlug}" (${moduleTitle})
+
+Use these tools freely:
+  - mcp__gitnexus__context       — caller/callee graph for symbols
+  - mcp__gitnexus__query         — concept search across the codebase
+  - mcp__gitnexus__group_contracts — structural facts about a group
+  - Read, Grep                   — inspect local files in the repo for concrete snippets
+
+Output: a single Markdown document starting with "# ${moduleTitle}" as the H1.
+
+Structure:
+  # ${moduleTitle}
+
+  One-paragraph summary.
+
+  ## Responsibilities
+  - Bulleted list of what this module owns.
+
+  ## Key Components
+  Short sections per major symbol/class/function with a brief explanation.
+  Include short code blocks (<= 20 lines) from the actual repo when illustrative.
+
+  ## How It Fits In
+  How this module connects to the rest of the system (callers, callees, flows).
+
+Rules:
+- Return ONLY the markdown — no preamble, no conclusion, no "Here's the wiki page".
+- Do not invent symbols or file paths. If you're unsure, query the graph.
+- Keep the total length under 50 KB.`;
+}
+export const MODULE_TREE_PROMPT_TEMPLATE = renderModuleTreePrompt('__FULL_NAME__');
+export const PAGE_PROMPT_TEMPLATE = renderPagePrompt('__FULL_NAME__', '__SLUG__', '__TITLE__');