arceus-s 1.6.4

package/dist/core/wiki/llm-client.d.ts

@@ -0,0 +1,83 @@
+/**
+ * LLM Client for Wiki Generation
+ *
+ * OpenAI-compatible API client using native fetch.
+ * Supports OpenAI, Azure, LiteLLM, Ollama, and any OpenAI-compatible endpoint.
+ *
+ * Config priority: CLI flags > env vars > defaults
+ */
+export type LLMProvider = 'openai' | 'openrouter' | 'azure' | 'custom' | 'cursor';
+export interface LLMConfig {
+    apiKey: string;
+    baseUrl: string;
+    model: string;
+    maxTokens: number;
+    temperature: number;
+    /** Provider type — controls auth header behaviour */
+    provider?: 'openai' | 'openrouter' | 'azure' | 'custom' | 'cursor';
+    /** Azure api-version query param (e.g. '2024-10-21'). Appended to URL when set. */
+    apiVersion?: string;
+    /** When true, strips sampling params and uses max_completion_tokens instead of max_tokens */
+    isReasoningModel?: boolean;
+    /** Per-attempt fetch timeout in ms (default: 60_000). */
+    requestTimeoutMs?: number;
+    /** Max fetch attempts before giving up (default: 3). */
+    maxAttempts?: number;
+}
+export interface LLMResponse {
+    content: string;
+    promptTokens?: number;
+    completionTokens?: number;
+}
+/**
+ * Resolve LLM configuration from env vars, saved config, and optional overrides.
+ * Priority: overrides (CLI flags) > env vars > ~/.arc/config.json > error
+ *
+ * If no API key is found, returns config with empty apiKey (caller should handle).
+ */
+export declare function resolveLLMConfig(overrides?: Partial<LLMConfig>): Promise<LLMConfig>;
+/**
+ * Estimate token count from text (rough heuristic: ~4 chars per token).
+ */
+export declare function estimateTokens(text: string): number;
+/**
+ * Validate that a base URL supplied for LLM API calls is a safe HTTP/HTTPS
+ * endpoint (CWE-918 / CodeQL js/http-to-file-access).
+ *
+ * Allowed:
+ *  - https:// with any hostname (public LLM APIs, Azure, OpenRouter, …)
+ *  - http:// restricted to localhost / 127.0.0.1 (local servers: Ollama, LiteLLM, …)
+ *
+ * Rejected:
+ *  - file://, data:, javascript:, and any other non-HTTP scheme
+ *  - http:// aimed at non-loopback hosts (avoids SSRF against internal networks)
+ *
+ * Throws with a descriptive message on validation failure so callers surface a
+ * clear error rather than an opaque network error.
+ */
+export declare function validateLLMBaseUrl(baseUrl: string): void;
+/**
+ * Returns true if the given base URL is an Azure OpenAI endpoint.
+ * Uses proper hostname matching to avoid spoofed URLs like
+ * "https://myresource.openai.azure.com.evil.com/v1".
+ */
+export declare function isAzureProvider(baseUrl: string): boolean;
+/**
+ * Returns true if the model name matches a known reasoning model pattern,
+ * or if the explicit override is true.
+ * Pass override=false to force non-reasoning even for o-series names.
+ */
+export declare function isReasoningModel(model: string, override?: boolean): boolean;
+/**
+ * Build the full chat completions URL, appending ?api-version when provided.
+ */
+export declare function buildRequestUrl(baseUrl: string, apiVersion: string | undefined): string;
+export interface CallLLMOptions {
+    onChunk?: (charsReceived: number) => void;
+}
+/**
+ * Call an OpenAI-compatible LLM API.
+ * Uses streaming when onChunk callback is provided for real-time progress.
+ * Retries up to 3 times on transient failures (429, 5xx, network errors).
+ */
+export declare function callLLM(prompt: string, config: LLMConfig, systemPrompt?: string, options?: CallLLMOptions): Promise<LLMResponse>;

package/dist/core/wiki/llm-client.js

@@ -0,0 +1,267 @@
+import { logger } from '../logger.js';
+import { CircuitOpenError, ResilientFetchExhaustedError, resilientFetch } from '../../_shared/index.js';
+/**
+ * Resolve LLM configuration from env vars, saved config, and optional overrides.
+ * Priority: overrides (CLI flags) > env vars > ~/.arc/config.json > error
+ *
+ * If no API key is found, returns config with empty apiKey (caller should handle).
+ */
+export async function resolveLLMConfig(overrides) {
+    const { loadCLIConfig } = await import('../../storage/repo-manager.js');
+    const savedConfig = await loadCLIConfig();
+    const apiKey = overrides?.apiKey ||
+        process.env.ARC_API_KEY ||
+        process.env.OPENAI_API_KEY ||
+        savedConfig.apiKey ||
+        '';
+    return {
+        apiKey,
+        baseUrl: overrides?.baseUrl ||
+            process.env.ARC_LLM_BASE_URL ||
+            savedConfig.baseUrl ||
+            'https://openrouter.ai/api/v1',
+        model: overrides?.model ||
+            process.env.ARC_MODEL ||
+            (savedConfig.provider === 'cursor' ? savedConfig.cursorModel : undefined) ||
+            savedConfig.model ||
+            'minimax/minimax-m2.5',
+        maxTokens: overrides?.maxTokens ?? 16_384,
+        temperature: overrides?.temperature ?? 0,
+        provider: overrides?.provider ?? savedConfig.provider ?? 'openai',
+        apiVersion: overrides?.apiVersion || process.env.ARC_AZURE_API_VERSION || savedConfig.apiVersion,
+        isReasoningModel: overrides?.isReasoningModel ?? savedConfig.isReasoningModel,
+    };
+}
+/**
+ * Estimate token count from text (rough heuristic: ~4 chars per token).
+ */
+export function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+/**
+ * Validate that a base URL supplied for LLM API calls is a safe HTTP/HTTPS
+ * endpoint (CWE-918 / CodeQL js/http-to-file-access).
+ *
+ * Allowed:
+ *  - https:// with any hostname (public LLM APIs, Azure, OpenRouter, …)
+ *  - http:// restricted to localhost / 127.0.0.1 (local servers: Ollama, LiteLLM, …)
+ *
+ * Rejected:
+ *  - file://, data:, javascript:, and any other non-HTTP scheme
+ *  - http:// aimed at non-loopback hosts (avoids SSRF against internal networks)
+ *
+ * Throws with a descriptive message on validation failure so callers surface a
+ * clear error rather than an opaque network error.
+ */
+export function validateLLMBaseUrl(baseUrl) {
+    let parsed;
+    try {
+        parsed = new URL(baseUrl);
+    }
+    catch {
+        // Do not include the raw input in the message — it may contain credentials.
+        throw new Error('Invalid LLM base URL: must be a well-formed http:// or https:// URL');
+    }
+    if (!['https:', 'http:'].includes(parsed.protocol)) {
+        // Use parsed.protocol only (scheme), not the full URL, to avoid leaking credentials.
+        throw new Error(`LLM base URL must use http:// or https:// (got ${parsed.protocol})`);
+    }
+    if (parsed.protocol === 'http:') {
+        // Node's URL parser preserves IPv6 brackets in hostname (e.g. "[::1]"),
+        // so strip them before comparing to bare address literals.
+        const host = parsed.hostname.toLowerCase().replace(/^\[|\]$/g, '');
+        if (host !== 'localhost' && host !== '127.0.0.1' && host !== '::1') {
+            // Use parsed.origin (scheme+host+port, no credentials) instead of the full URL.
+            throw new Error(`Insecure http:// LLM base URLs are only allowed for localhost/127.0.0.1. ` +
+                `Use https:// for remote endpoints (got ${parsed.origin})`);
+        }
+    }
+}
+/**
+ * Returns true if the given base URL is an Azure OpenAI endpoint.
+ * Uses proper hostname matching to avoid spoofed URLs like
+ * "https://myresource.openai.azure.com.evil.com/v1".
+ */
+export function isAzureProvider(baseUrl) {
+    try {
+        const { hostname } = new URL(baseUrl);
+        return hostname.endsWith('.openai.azure.com') || hostname.endsWith('.services.ai.azure.com');
+    }
+    catch {
+        // Malformed URL — refuse to call this Azure rather than fall back to a
+        // substring check, which is bypassable by `https://evil.com/?u=.openai.azure.com`
+        // (CodeQL js/incomplete-url-substring-sanitization).
+        return false;
+    }
+}
+/**
+ * Returns true if the model name matches a known reasoning model pattern,
+ * or if the explicit override is true.
+ * Pass override=false to force non-reasoning even for o-series names.
+ */
+export function isReasoningModel(model, override) {
+    if (override !== undefined)
+        return override;
+    // Match known bare reasoning models (o1, o3) and any o-series with -mini/-preview suffix
+    return /^o[1-9]\d*(-mini|-preview)$|^o1$|^o3$/i.test(model);
+}
+/**
+ * Build the full chat completions URL, appending ?api-version when provided.
+ */
+export function buildRequestUrl(baseUrl, apiVersion) {
+    const base = `${baseUrl.replace(/\/+$/, '')}/chat/completions`;
+    return apiVersion ? `${base}?api-version=${encodeURIComponent(apiVersion)}` : base;
+}
+/**
+ * Call an OpenAI-compatible LLM API.
+ * Uses streaming when onChunk callback is provided for real-time progress.
+ * Retries up to 3 times on transient failures (429, 5xx, network errors).
+ */
+export async function callLLM(prompt, config, systemPrompt, options) {
+    // Validate base URL before any fetch (CodeQL js/http-to-file-access)
+    validateLLMBaseUrl(config.baseUrl);
+    const messages = [];
+    if (systemPrompt) {
+        messages.push({ role: 'system', content: systemPrompt });
+    }
+    messages.push({ role: 'user', content: prompt });
+    // Detect Azure endpoint (by provider field or URL pattern)
+    const azure = config.provider === 'azure' || isAzureProvider(config.baseUrl);
+    // Warn when using Azure legacy deployment URL without api-version
+    if (azure && !config.apiVersion && config.baseUrl.includes('/deployments/')) {
+        logger.warn('[arc] Warning: Azure legacy deployment URL detected but no api-version set. Add --api-version 2024-10-21 or use the v1 API format.');
+    }
+    // Detect reasoning model (o1, o3, o4-mini etc.) or explicit override
+    const reasoning = isReasoningModel(config.model, config.isReasoningModel);
+    const url = buildRequestUrl(config.baseUrl, azure ? config.apiVersion : undefined);
+    const useStream = !!options?.onChunk;
+    // Build request body — reasoning models reject temperature and use max_completion_tokens
+    const body = {
+        model: config.model,
+        messages,
+    };
+    // max_tokens is deprecated; use max_completion_tokens for all models
+    body.max_completion_tokens = config.maxTokens;
+    // Only send temperature for non-Azure providers — some Azure models reject non-default values
+    if (!reasoning && !azure && config.temperature !== undefined) {
+        body.temperature = config.temperature;
+    }
+    if (useStream)
+        body.stream = true;
+    // Build auth headers — Azure uses api-key header, everyone else uses Authorization: Bearer
+    const authHeaders = azure
+        ? { 'api-key': config.apiKey }
+        : { Authorization: `Bearer ${config.apiKey}` };
+    // Network resilience (bounded retries with exponential-backoff jitter,
+    // 5xx + 429 + Retry-After handling, in-process circuit breaker on the
+    // LLM endpoint) is delegated to resilientFetch. Provider-specific
+    // error parsing (Azure content filter, empty-content checks) stays
+    // here since it requires response-body inspection.
+    let response;
+    try {
+        response = await resilientFetch(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                ...authHeaders,
+            },
+            body: JSON.stringify(body),
+            // Per-attempt timeout. Without this each retry can hang
+            // indefinitely on a frozen TCP connection — the per-call
+            // signal is the only timeout `resilientFetch` honors;
+            // `capDelayMs` only bounds the *backoff* between attempts.
+            // Default 60s; raise via --timeout for slow models or large pages.
+            signal: AbortSignal.timeout(config.requestTimeoutMs ?? 60_000),
+        }, {
+            breakerKey: `wiki-llm-${new URL(url).host}`,
+            retry: { maxAttempts: config.maxAttempts ?? 3, baseDelayMs: 2_000, capDelayMs: 30_000 },
+        });
+    }
+    catch (err) {
+        if (err instanceof CircuitOpenError) {
+            throw new Error(`LLM endpoint circuit open: retry in ${Math.ceil(err.retryAfterMs / 1000)}s. ${err.message}`);
+        }
+        if (err instanceof ResilientFetchExhaustedError) {
+            const errorText = await err.response.text().catch(() => 'unknown error');
+            throw new Error(`LLM API error (${err.response.status} after retries): ${errorText.slice(0, 500)}`);
+        }
+        throw err;
+    }
+    if (!response.ok) {
+        const errorText = await response.text().catch(() => 'unknown error');
+        // Azure content filter — surface a clear message instead of a generic API error.
+        if (azure &&
+            response.status === 400 &&
+            (errorText.includes('content_filter') || errorText.includes('ResponsibleAIPolicyViolation'))) {
+            throw new Error(`Azure content filter blocked this request. The prompt triggered content policy. Details: ${errorText.slice(0, 300)}`);
+        }
+        // Any other non-OK response here is a terminal 4xx — resilientFetch
+        // already retried 5xx/429 to exhaustion and would have thrown above.
+        throw new Error(`LLM API error (${response.status}): ${errorText.slice(0, 500)}`);
+    }
+    // Streaming path
+    if (useStream && response.body) {
+        return await readSSEStream(response.body, options.onChunk);
+    }
+    // Non-streaming path
+    const json = (await response.json());
+    const choice = json.choices?.[0];
+    if (!choice?.message?.content) {
+        throw new Error('LLM returned empty response');
+    }
+    return {
+        content: choice.message.content,
+        promptTokens: json.usage?.prompt_tokens,
+        completionTokens: json.usage?.completion_tokens,
+    };
+}
+/**
+ * Read an SSE stream from an OpenAI-compatible streaming response.
+ */
+async function readSSEStream(body, onChunk) {
+    const decoder = new TextDecoder();
+    const reader = body.getReader();
+    let content = '';
+    let buffer = '';
+    let contentFilterTriggered = false;
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split('\n');
+        buffer = lines.pop() || '';
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed || !trimmed.startsWith('data: '))
+                continue;
+            const data = trimmed.slice(6);
+            if (data === '[DONE]')
+                continue;
+            try {
+                const parsed = JSON.parse(data);
+                const choice = parsed.choices?.[0];
+                // Detect content filter finish reason — skip delta from this chunk
+                if (choice?.finish_reason === 'content_filter') {
+                    contentFilterTriggered = true;
+                    continue;
+                }
+                const delta = choice?.delta?.content;
+                if (delta) {
+                    content += delta;
+                    onChunk(content.length);
+                }
+            }
+            catch {
+                // Skip malformed SSE chunks
+            }
+        }
+    }
+    if (contentFilterTriggered) {
+        throw new Error('content filter triggered mid-stream. The generated content was blocked by content policy. Adjust your prompt and retry.');
+    }
+    if (!content) {
+        throw new Error('LLM returned empty streaming response');
+    }
+    return { content };
+}

package/dist/core/wiki/mermaid-sanitizer.d.ts

@@ -0,0 +1,2 @@
+export declare function sanitizeMermaidMarkdown(markdown: string): string;
+export declare function sanitizeMermaidDiagram(diagram: string): string;

package/dist/core/wiki/mermaid-sanitizer.js

@@ -0,0 +1,100 @@
+const MERMAID_FENCE_RE = /```mermaid\s*\n([\s\S]*?)```/g;
+const NODE_LABEL_RE = /(\[[^\]\n]*(?:\\n)[^\]\n]*\]|\{[^}\n]*(?:\\n)[^}\n]*\}|\([^)\n]*(?:\\n)[^)\n]*\))/g;
+const EDGE_LABEL_RE = /\|([^|\n]+)\|/g;
+const UNSAFE_EDGE_LABEL_RE = /[()[\]{}<>]/;
+const UNSAFE_NODE_ID_RE = /[^A-Za-z0-9_-]/;
+const NODE_ID_RE = /^[A-Za-z0-9_.:/()-]+$/;
+const LINE_PREFIX_RE = /^(\s*(?:(?:[-A-Za-z0-9_]+)\s*:\s*)?)(.*)$/;
+const EDGE_RE = /(\s*(?:[ox])?(?:--+|==+|\.\.+)(?:[>|ox])?\|[^|\n]*\|(?:[>|ox])?|\s*(?:[ox])?(?:--+|==+|\.\.+)(?:[>|ox])?|\s*<--+>?\s*)/g;
+export function sanitizeMermaidMarkdown(markdown) {
+    return markdown.replace(MERMAID_FENCE_RE, (_match, diagram) => {
+        return '```mermaid\n' + sanitizeMermaidDiagram(diagram) + '```';
+    });
+}
+export function sanitizeMermaidDiagram(diagram) {
+    const aliases = new Map();
+    let nextAlias = 1;
+    const aliasFor = (id) => {
+        const existing = aliases.get(id);
+        if (existing)
+            return existing;
+        const base = id.replace(/[^A-Za-z0-9_-]/g, '_').replace(/^_+|_+$/g, '') || 'node';
+        let alias = base;
+        while ([...aliases.values()].includes(alias)) {
+            nextAlias += 1;
+            alias = `${base}_${nextAlias}`;
+        }
+        aliases.set(id, alias);
+        return alias;
+    };
+    return diagram
+        .split('\n')
+        .map((line) => sanitizeMermaidLine(line, aliasFor))
+        .join('\n');
+}
+function sanitizeMermaidLine(line, aliasFor) {
+    let sanitized = replaceLiteralLineBreaksInLabels(line);
+    sanitized = quoteUnsafeEdgeLabels(sanitized);
+    const prefixMatch = sanitized.match(LINE_PREFIX_RE);
+    if (!prefixMatch)
+        return sanitized;
+    const prefix = prefixMatch[1];
+    const body = prefixMatch[2];
+    if (isDirectiveLine(body))
+        return sanitized;
+    const parts = body.split(EDGE_RE);
+    if (parts.length === 1)
+        return sanitized;
+    for (let i = 0; i < parts.length; i += 2) {
+        parts[i] = sanitizeNodeReference(parts[i], aliasFor);
+    }
+    return prefix + parts.join('');
+}
+function replaceLiteralLineBreaksInLabels(line) {
+    return line.replace(NODE_LABEL_RE, (label) => label.replace(/\\n/g, '<br/>'));
+}
+function quoteUnsafeEdgeLabels(line) {
+    return line.replace(EDGE_LABEL_RE, (match, label) => {
+        const trimmed = label.trim();
+        if (!UNSAFE_EDGE_LABEL_RE.test(trimmed))
+            return match;
+        if ((trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+            (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+            return match;
+        }
+        return `|"${escapeMermaidLabel(trimmed)}"|`;
+    });
+}
+function sanitizeNodeReference(segment, aliasFor) {
+    const match = segment.match(/^(\s*)([A-Za-z0-9_.:/()-]+)(.*?)(\s*)$/);
+    if (!match)
+        return segment;
+    const [, leading, id, suffix, trailing] = match;
+    if (!NODE_ID_RE.test(id) || !UNSAFE_NODE_ID_RE.test(id))
+        return segment;
+    const hasInlineLabel = suffix.trim().startsWith('[') || suffix.trim().startsWith('(') || suffix.trim().startsWith('{');
+    if (hasInlineLabel)
+        return `${leading}${aliasFor(id)}${suffix}${trailing}`;
+    return `${leading}${aliasFor(id)}["${escapeMermaidLabel(id)}"]${suffix}${trailing}`;
+}
+function escapeMermaidLabel(label) {
+    return label.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+function isDirectiveLine(line) {
+    const trimmed = line.trim();
+    return (trimmed === '' ||
+        trimmed.startsWith('%%') ||
+        trimmed.startsWith('graph ') ||
+        trimmed.startsWith('flowchart ') ||
+        trimmed.startsWith('sequenceDiagram') ||
+        trimmed.startsWith('classDiagram') ||
+        trimmed.startsWith('stateDiagram') ||
+        trimmed.startsWith('erDiagram') ||
+        trimmed.startsWith('journey') ||
+        trimmed.startsWith('gantt') ||
+        trimmed.startsWith('pie ') ||
+        trimmed.startsWith('mindmap') ||
+        trimmed.startsWith('timeline') ||
+        trimmed.startsWith('subgraph ') ||
+        trimmed === 'end');
+}

package/dist/core/wiki/prompts.d.ts

@@ -0,0 +1,53 @@
+/**
+ * LLM Prompt Templates for Wiki Generation
+ *
+ * All prompts produce deterministic, source-grounded documentation.
+ * Templates use {{PLACEHOLDER}} substitution.
+ */
+export declare const GROUPING_SYSTEM_PROMPT = "You are a documentation architect. Given a list of source files with their exported symbols, group them into logical documentation modules.\n\nRules:\n- Each module should represent a cohesive feature, layer, or domain\n- Every file must appear in exactly one module\n- Module names should be human-readable (e.g. \"Authentication\", \"Database Layer\", \"API Routes\")\n- Aim for 5-15 modules for a typical project. Fewer for small projects, more for large ones\n- Group by functionality, not by file type or directory structure alone\n- Do NOT create modules for tests, configs, or non-source files";
+export declare const GROUPING_USER_PROMPT = "Group these source files into documentation modules.\n\n**Files and their exports:**\n{{FILE_LIST}}\n\n**Directory structure:**\n{{DIRECTORY_TREE}}\n\nRespond with ONLY a JSON object mapping module names to file path arrays. No markdown, no explanation.\nExample format:\n{\n  \"Authentication\": [\"src/auth/login.ts\", \"src/auth/session.ts\"],\n  \"Database\": [\"src/db/connection.ts\", \"src/db/models.ts\"]\n}";
+export declare const MODULE_SYSTEM_PROMPT = "You are a technical documentation writer. Write clear, developer-focused documentation for a code module.\n\nRules:\n- Output ONLY the documentation content \u2014 no meta-commentary like \"I've written...\", \"Here's the documentation...\", \"The documentation covers...\", or similar\n- Start directly with the module heading and content\n- Reference actual function names, class names, and code patterns \u2014 do NOT invent APIs\n- Use the call graph and execution flow data for accuracy, but do NOT mechanically list every edge\n- Include Mermaid diagrams only when they genuinely help understanding. Keep them small (5-10 nodes max)\n- Structure the document however makes sense for this module \u2014 there is no mandatory format\n- Write for a developer who needs to understand and contribute to this code";
+export declare const MODULE_USER_PROMPT = "Write documentation for the **{{MODULE_NAME}}** module.\n\n## Source Code\n\n{{SOURCE_CODE}}\n\n## Call Graph & Execution Flows (reference for accuracy)\n\nInternal calls: {{INTRA_CALLS}}\nOutgoing calls: {{OUTGOING_CALLS}}\nIncoming calls: {{INCOMING_CALLS}}\nExecution flows: {{PROCESSES}}\n\n---\n\nWrite comprehensive documentation for this module. Cover its purpose, how it works, its key components, and how it connects to the rest of the codebase. Use whatever structure best fits this module \u2014 you decide the sections and headings. Include a Mermaid diagram only if it genuinely clarifies the architecture.";
+export declare const PARENT_SYSTEM_PROMPT = "You are a technical documentation writer. Write a summary page for a module that contains sub-modules. Synthesize the children's documentation \u2014 do not re-read source code.\n\nRules:\n- Output ONLY the documentation content \u2014 no meta-commentary like \"I've written...\", \"Here's the documentation...\", \"The documentation covers...\", or similar\n- Start directly with the module heading and content\n- Reference actual components from the child modules\n- Focus on how the sub-modules work together, not repeating their individual docs\n- Keep it concise \u2014 the reader can click through to child pages for detail\n- Include a Mermaid diagram only if it genuinely clarifies how the sub-modules relate";
+export declare const PARENT_USER_PROMPT = "Write documentation for the **{{MODULE_NAME}}** module, which contains these sub-modules:\n\n{{CHILDREN_DOCS}}\n\nCross-module calls: {{CROSS_MODULE_CALLS}}\nShared execution flows: {{CROSS_PROCESSES}}\n\n---\n\nWrite a concise overview of this module group. Explain its purpose, how the sub-modules fit together, and the key workflows that span them. Link to sub-module pages (e.g. `[Sub-module Name](sub-module-slug.md)`) rather than repeating their content. Use whatever structure fits best.";
+export declare const OVERVIEW_SYSTEM_PROMPT = "You are a technical documentation writer. Write the top-level overview page for a repository wiki. This is the first page a new developer sees.\n\nRules:\n- Output ONLY the documentation content \u2014 no meta-commentary like \"I've written...\", \"Here's the documentation...\", \"The page has been rewritten...\", or similar\n- Start directly with the project heading and content\n- Be clear and welcoming \u2014 this is the entry point to the entire codebase\n- Reference actual module names so readers can navigate to their docs\n- Include a high-level Mermaid architecture diagram showing only the most important modules and their relationships (max 10 nodes). A new dev should grasp it in 10 seconds\n- Do NOT create module index tables or list every module with descriptions \u2014 just link to module pages naturally within the text\n- Use the inter-module edges and execution flow data for accuracy, but do NOT dump them raw";
+export declare const OVERVIEW_USER_PROMPT = "Write the overview page for this repository's wiki.\n\n## Project Info\n\n{{PROJECT_INFO}}\n\n## Module Summaries\n\n{{MODULE_SUMMARIES}}\n\n## Reference Data (for accuracy \u2014 do not reproduce verbatim)\n\nInter-module call edges: {{MODULE_EDGES}}\nKey system flows: {{TOP_PROCESSES}}\n\n---\n\nWrite a clear overview of this project: what it does, how it's architected, and the key end-to-end flows. Include a simple Mermaid architecture diagram (max 10 nodes, big-picture only). Link to module pages (e.g. `[Module Name](module-slug.md)`) naturally in the text rather than listing them in a table. If project config was provided, include brief setup instructions. Structure the page however reads best.";
+/**
+ * Replace {{PLACEHOLDER}} tokens in a template string.
+ */
+export declare function fillTemplate(template: string, vars: Record<string, string>): string;
+/**
+ * Format file list with exports for the grouping prompt.
+ */
+export declare function formatFileListForGrouping(files: Array<{
+    filePath: string;
+    symbols: Array<{
+        name: string;
+        type: string;
+    }>;
+}>): string;
+/**
+ * Build a directory tree string from file paths.
+ */
+export declare function formatDirectoryTree(filePaths: string[]): string;
+/**
+ * Format call edges as readable text.
+ */
+export declare function formatCallEdges(edges: Array<{
+    fromFile: string;
+    fromName: string;
+    toFile: string;
+    toName: string;
+}>): string;
+/**
+ * Format process traces as readable text.
+ */
+export declare function formatProcesses(processes: Array<{
+    label: string;
+    type: string;
+    steps: Array<{
+        step: number;
+        name: string;
+        filePath: string;
+    }>;
+}>): string;