@rahul05ranjan/dhruv-cli 1.3.0 → 1.5.0

package/dist/commands/status.js

@@ -0,0 +1,83 @@
+import chalk from 'chalk';
+import { loadConfig } from '../config/config.js';
+import { printSuccess, printError, printInfo } from '../utils/ux.js';
+import { getOllamaStatus, listModels } from '../core/ai.js';
+export async function status() {
+    const config = loadConfig();
+    if (config.responseFormat === 'json') {
+        try {
+            const models = await listModels();
+            const server = await getOllamaStatus();
+            const configuredModelAvailable = models.includes(config.model);
+            process.stdout.write(`${JSON.stringify({
+                ok: configuredModelAvailable,
+                command: 'status',
+                model: config.model,
+                responseFormat: config.responseFormat,
+                verbose: config.verbose,
+                theme: config.theme,
+                availableModels: models,
+                configuredModelAvailable,
+                endpoint: server.endpoint,
+                version: server.version ?? null,
+                ollama: 'connected',
+                nextSteps: configuredModelAvailable ? [] : [`ollama pull ${config.model}`],
+            })}\n`);
+            if (!configuredModelAvailable)
+                process.exitCode = 1;
+        }
+        catch (error) {
+            process.exitCode = 1;
+            process.stdout.write(`${JSON.stringify({
+                ok: false,
+                command: 'status',
+                model: config.model,
+                ollama: 'unavailable',
+                error: error.message,
+            })}\n`);
+        }
+        return;
+    }
+    console.log(chalk.blue('🔍 Dhruv CLI Status Check\n'));
+    const server = await getOllamaStatus();
+    printInfo(`Ollama endpoint: ${server.endpoint}`);
+    printInfo(`Ollama version: ${server.version ?? 'unavailable'}\n`);
+    printInfo(`Current configuration:`);
+    console.log(`  Model: ${config.model}`);
+    console.log(`  Response Format: ${config.responseFormat}`);
+    console.log(`  Verbose: ${config.verbose}`);
+    console.log(`  Theme: ${config.theme}\n`);
+    try {
+        printInfo('Testing Ollama connection...');
+        const models = await listModels();
+        printSuccess('✓ Ollama is running and accessible');
+        if (models.length > 0) {
+            printSuccess(`✓ Found ${models.length} available models:`);
+            models.forEach((name) => {
+                const isConfigured = name === config.model;
+                const status = isConfigured ? chalk.green('(configured)') : '';
+                console.log(`  • ${name} ${status}`);
+            });
+        }
+        else {
+            printError('✗ No models found');
+            console.log(chalk.yellow('Install a model using: ollama pull llama2'));
+        }
+        if (models.includes(config.model)) {
+            printSuccess(`✓ Configured model '${config.model}' is available`);
+        }
+        else {
+            process.exitCode = 1;
+            printError(`✗ Configured model '${config.model}' is not available`);
+            if (models.length > 0) {
+                console.log(chalk.yellow(`Available models: ${models.join(', ')}`));
+            }
+        }
+    }
+    catch (error) {
+        printError('✗ Ollama connection failed');
+        console.log(chalk.red(error.message));
+        console.log(chalk.yellow('\nTo start Ollama, run: ollama serve'));
+        console.log(chalk.yellow('To install a model, run: ollama pull llama2'));
+    }
+}

package/dist/commands/suggest.js

@@ -1,41 +1,15 @@
-import { askOllama } from '../core/ai.js';
-import ora from 'ora';
-import chalk from 'chalk';
-import { loadConfig } from '../config/config.js';
-import { highlightCode, printError } from '../utils/ux.js';
+import { runCommand } from '../core/command-runner.js';
+import { getSystemMessage } from '../core/prompts.js';
 export async function suggest(query) {
-    const config = loadConfig();
-    const spinner = ora('Generating suggestions...').start();
-    let streamed = '';
-    try {
-        spinner.stop();
-        process.stdout.write(chalk.green('Suggestions: '));
-        await askOllama({
-            prompt: `Suggest: ${query}`,
-            model: config.model,
-            onToken: (token) => {
-                streamed += token;
-                process.stdout.write(chalk.cyan(token));
-            }
-        });
-        process.stdout.write('\n');
-        if (typeof highlightCode === 'function' && streamed.match(/```[a-z]*[\s\S]*?```/)) {
-            // Highlight code blocks if present
-            const codeBlocks = streamed.match(/```([a-z]*)\n([\s\S]*?)```/g) || [];
-            for (const block of codeBlocks) {
-                const [, lang, code] = block.match(/```([a-z]*)\n([\s\S]*?)```/) || [];
-                if (code)
-                    try {
-                        console.log(highlightCode(code, lang || 'js'));
-                    }
-                    catch (err) {
-                        console.error('Highlight error:', err);
-                    }
-            }
-        }
-    }
-    catch (err) {
-        printError('Failed to get suggestions.');
-        console.error(chalk.red(err.message));
-    }
+    await runCommand({
+        name: 'suggest',
+        input: { query },
+        header: '💡 Suggestions: ',
+        buildRequest: (input, model) => ({
+            prompt: input.query,
+            systemMessage: getSystemMessage('suggest'),
+            model,
+        }),
+        footer: `🔧 Need implementation help? Try: dhruv fix "${query}"`,
+    });
 }

package/dist/config/config.d.ts

@@ -1,8 +1,12 @@
+export type ConfigScope = 'local' | 'global';
 export interface DhruvConfig {
     model: string;
     verbose: boolean;
     responseFormat: 'text' | 'json' | 'markdown';
+    timeoutMs: number;
     theme?: 'default' | 'dark' | 'light' | 'mono';
 }
 export declare function loadConfig(): DhruvConfig;
-export declare function saveConfig(config: Partial<DhruvConfig>): void;
+export declare function saveConfig(config: Partial<DhruvConfig>, options?: {
+    scope?: ConfigScope;
+}): void;

package/dist/config/config.js

@@ -1,20 +1,65 @@
 import fs from 'fs';
 import path from 'path';
-const CONFIG_FILE = path.join(process.cwd(), '.dhruv-config.json');
+import os from 'os';
+const LOCAL_CONFIG_FILE = path.join(process.cwd(), '.dhruv-config.json');
+const GLOBAL_CONFIG_FILE = path.join(os.homedir(), '.config', 'dhruv', 'config.json');
 const defaultConfig = {
-    model: 'codellama',
+    model: 'gemma3:270m',
     verbose: false,
     responseFormat: 'text',
+    timeoutMs: 45000,
     theme: 'default',
 };
-export function loadConfig() {
-    if (fs.existsSync(CONFIG_FILE)) {
-        return { ...defaultConfig, ...JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf-8')) };
+function readConfigFile(file) {
+    if (fs.existsSync(file)) {
+        try {
+            const fileContent = fs.readFileSync(file, 'utf-8');
+            const parsedConfig = JSON.parse(fileContent);
+            return validateAndMergeConfig(parsedConfig);
+        }
+        catch (error) {
+            console.warn(`Warning: Invalid config file. Using defaults. Error: ${error.message}`);
+            return defaultConfig;
+        }
     }
     return defaultConfig;
 }
-export function saveConfig(config) {
-    const current = loadConfig();
-    fs.writeFileSync(CONFIG_FILE, JSON.stringify({ ...current, ...config }, null, 2));
+export function loadConfig() {
+    if (fs.existsSync(LOCAL_CONFIG_FILE))
+        return readConfigFile(LOCAL_CONFIG_FILE);
+    if (fs.existsSync(GLOBAL_CONFIG_FILE))
+        return readConfigFile(GLOBAL_CONFIG_FILE);
+    return defaultConfig;
+}
+function validateAndMergeConfig(config) {
+    const validatedConfig = { ...defaultConfig };
+    // Validate model
+    if (config.model && typeof config.model === 'string') {
+        validatedConfig.model = config.model;
+    }
+    // Validate verbose
+    if (typeof config.verbose === 'boolean') {
+        validatedConfig.verbose = config.verbose;
+    }
+    // Validate responseFormat
+    if (config.responseFormat && ['text', 'json', 'markdown'].includes(config.responseFormat)) {
+        validatedConfig.responseFormat = config.responseFormat;
+    }
+    if (typeof config.timeoutMs === 'number' && Number.isFinite(config.timeoutMs) && config.timeoutMs > 0) {
+        validatedConfig.timeoutMs = Math.round(config.timeoutMs);
+    }
+    // Validate theme
+    if (config.theme && ['default', 'dark', 'light', 'mono'].includes(config.theme)) {
+        validatedConfig.theme = config.theme;
+    }
+    return validatedConfig;
+}
+export function saveConfig(config, options = {}) {
+    const scope = options.scope ?? 'local';
+    const file = scope === 'global' ? GLOBAL_CONFIG_FILE : LOCAL_CONFIG_FILE;
+    const current = scope === 'global' ? readConfigFile(GLOBAL_CONFIG_FILE) : loadConfig();
+    if (scope === 'global')
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify({ ...current, ...config }, null, 2));
 }
 // Use .js extension for ESM compatibility if imported elsewhere

package/dist/core/ai.d.ts

@@ -1,5 +1,91 @@
-export declare function askOllama({ prompt, model, onToken }: {
+/**
+ * The AI module: everything about talking to a local model lives here.
+ *
+ * Interface (the only surface callers and tests cross):
+ *   ask(request)        -> full response, optionally streaming tokens via onToken
+ *   listModels()        -> available model names
+ *
+ * Everything else — connection handling, streaming, caching, error
+ * translation — is implementation. Two adapters satisfy the interface:
+ * the HTTP adapter (production, talks to the local Ollama server) and the
+ * in-memory adapter (tests). No third adapter exists.
+ */
+import { Ollama } from 'ollama';
+/** Typed errors: the runner maps these to user-facing hints, never by string matching. */
+export type AIError = {
+    kind: 'connection';
+    cause: string;
+} | {
+    kind: 'model-not-found';
+    model: string;
+} | {
+    kind: 'empty-response';
+    model: string;
+} | {
+    kind: 'timeout';
+    timeoutMs: number;
+} | {
+    kind: 'cancelled';
+} | {
+    kind: 'request';
+    cause: string;
+};
+export interface AIRequest {
     prompt: string;
+    systemMessage?: string;
+    context?: string;
     model?: string;
     onToken?: (token: string) => void;
-}): Promise<string>;
+    signal?: AbortSignal;
+}
+/** The seam. Both adapters implement this; commands and tests depend on it, never on Ollama. */
+export interface AIClient {
+    ask(request: AIRequest): Promise<string>;
+    listModels(): Promise<string[]>;
+}
+/**
+ * HTTP adapter: production. Standardizes on the Ollama client package —
+ * the raw-HTTP path existed only to work around a LangChain prompt-template
+ * issue, and that integration is gone.
+ */
+export declare class OllamaAIClient implements AIClient {
+    private client;
+    constructor(client?: Ollama);
+    ask(request: AIRequest): Promise<string>;
+    listModels(): Promise<string[]>;
+}
+/**
+ * In-memory adapter: tests. Satisfies the same interface with no network,
+ * which is what makes AI behavior testable without Ollama installed.
+ */
+export declare class InMemoryAIClient implements AIClient {
+    private responses;
+    private store;
+    /** Failures to simulate, keyed by prompt substring. */
+    failures: Map<string, AIError>;
+    /** Count of computations performed (not cache reads) — lets tests observe cache hits. */
+    computations: number;
+    /** Simulated clock for expiry tests. */
+    now: () => number;
+    /** TTL override for tests; defaults to the production expiry. */
+    ttlMs: number;
+    constructor(responses?: Map<string, string>);
+    ask(request: AIRequest): Promise<string>;
+    listModels(): Promise<string[]>;
+}
+export declare function getAIClient(): AIClient;
+/** Test seam setter: swaps the adapter the module hands out. */
+export declare function setAIClient(client: AIClient): void;
+/**
+ * The interface commands call. Kept as module functions so callers don't
+ * reach for a client object; the client is resolved internally.
+ */
+export declare function ask(request: AIRequest): Promise<string>;
+export declare function listModels(): Promise<string[]>;
+export interface OllamaStatus {
+    endpoint: string;
+    version?: string;
+}
+export declare function getOllamaStatus(): Promise<OllamaStatus>;
+/** Default model, from configuration — one source of truth. */
+export declare function defaultModel(): string;

package/dist/core/ai.js

@@ -1,43 +1,244 @@
+/**
+ * The AI module: everything about talking to a local model lives here.
+ *
+ * Interface (the only surface callers and tests cross):
+ *   ask(request)        -> full response, optionally streaming tokens via onToken
+ *   listModels()        -> available model names
+ *
+ * Everything else — connection handling, streaming, caching, error
+ * translation — is implementation. Two adapters satisfy the interface:
+ * the HTTP adapter (production, talks to the local Ollama server) and the
+ * in-memory adapter (tests). No third adapter exists.
+ */
 import { Ollama } from 'ollama';
 import fs from 'fs';
 import path from 'path';
 import crypto from 'crypto';
-const CACHE_DIR = path.join(process.cwd(), '.dhruv-cache');
-if (!fs.existsSync(CACHE_DIR))
-    fs.mkdirSync(CACHE_DIR);
-function getCacheKey(prompt, model) {
-    const hash = crypto.createHash('sha256').update(`${model || 'default'}:${prompt}`).digest('hex');
-    return path.join(CACHE_DIR, hash);
-}
-export async function askOllama({ prompt, model, onToken }) {
-    const cacheKey = getCacheKey(prompt, model);
-    if (fs.existsSync(cacheKey)) {
-        const cached = fs.readFileSync(cacheKey, 'utf-8');
-        if (onToken)
-            onToken(cached);
+import { loadConfig } from '../config/config.js';
+import { metricsCollector } from './metrics.js';
+const CACHE_EXPIRY_MS = 24 * 60 * 60 * 1000; // 24 hours
+const MAX_CACHE_FILES = 100;
+function cacheDir() {
+    return path.join(process.cwd(), '.dhruv-cache');
+}
+function cacheKey(request, model) {
+    const hash = crypto
+        .createHash('sha256')
+        .update(`${model}:${request.systemMessage ?? ''}:${request.context ?? ''}:${request.prompt}`)
+        .digest('hex');
+    return path.join(cacheDir(), hash);
+}
+function readCache(request, model) {
+    const file = cacheKey(request, model);
+    try {
+        const cached = fs.readFileSync(file, 'utf-8');
+        const stats = fs.statSync(file);
+        if (Date.now() - stats.mtimeMs > CACHE_EXPIRY_MS) {
+            fs.unlinkSync(file);
+            return undefined;
+        }
         return cached;
     }
+    catch {
+        return undefined;
+    }
+}
+function writeCache(request, model, response) {
+    try {
+        const dir = cacheDir();
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(cacheKey(request, model), response);
+    }
+    catch {
+        // Cache write failures never fail the request.
+    }
+}
+/** Wired up (the old cleanupCache was never called); runs opportunistically after a cache write. */
+function cleanupCache() {
     try {
-        let result = '';
-        const ollama = new Ollama();
-        // Await the iterator, then stream
-        const iterator = await ollama.generate({ model: model || 'codellama', prompt, stream: true });
-        for await (const chunk of iterator) {
-            let token = '';
-            if (typeof chunk === 'object' && chunk !== null && 'response' in chunk) {
-                token = chunk.response;
+        const dir = cacheDir();
+        if (!fs.existsSync(dir))
+            return;
+        const entries = fs
+            .readdirSync(dir)
+            .map((name) => {
+            const file = path.join(dir, name);
+            return { file, mtimeMs: fs.statSync(file).mtimeMs };
+        })
+            .filter((entry) => {
+            if (Date.now() - entry.mtimeMs > CACHE_EXPIRY_MS) {
+                fs.unlinkSync(entry.file);
+                return false;
+            }
+            return true;
+        })
+            .sort((a, b) => a.mtimeMs - b.mtimeMs);
+        const excess = entries.length - MAX_CACHE_FILES;
+        if (excess > 0) {
+            for (const entry of entries.slice(0, excess))
+                fs.unlinkSync(entry.file);
+        }
+    }
+    catch {
+        // Ignore cleanup errors.
+    }
+}
+function toAIError(err, model) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (message.includes('ECONNREFUSED') || message.includes('fetch failed') || message.includes('ENOTFOUND')) {
+        return { kind: 'connection', cause: message };
+    }
+    if (message.includes('returned empty response'))
+        return { kind: 'empty-response', model };
+    if (message.includes('not found'))
+        return { kind: 'model-not-found', model };
+    return { kind: 'request', cause: message };
+}
+/**
+ * HTTP adapter: production. Standardizes on the Ollama client package —
+ * the raw-HTTP path existed only to work around a LangChain prompt-template
+ * issue, and that integration is gone.
+ */
+export class OllamaAIClient {
+    constructor(client) {
+        this.client = client ?? new Ollama();
+    }
+    async ask(request) {
+        const model = request.model ?? loadConfig().model;
+        const fullPrompt = request.systemMessage
+            ? `System: ${request.systemMessage}\n\n${request.context ? `Context: ${request.context}\n\n` : ''}Query: ${request.prompt}`
+            : request.prompt;
+        const cached = readCache(request, model);
+        if (cached !== undefined) {
+            metricsCollector.recordCacheHit('ai-response');
+            if (request.onToken)
+                request.onToken(cached);
+            return cached;
+        }
+        metricsCollector.recordCacheMiss('ai-response');
+        try {
+            const streaming = Boolean(request.onToken);
+            let result = '';
+            if (streaming) {
+                const stream = await this.client.generate({ model, prompt: fullPrompt, stream: true });
+                const abort = () => stream.abort();
+                request.signal?.addEventListener('abort', abort, { once: true });
+                try {
+                    for await (const chunk of stream) {
+                        const token = typeof chunk === 'object' && chunk !== null && 'response' in chunk ? chunk.response : '';
+                        if (!token)
+                            continue;
+                        result += token;
+                        if (request.onToken)
+                            request.onToken(token);
+                    }
+                }
+                finally {
+                    request.signal?.removeEventListener('abort', abort);
+                }
             }
-            else if (typeof chunk === 'string') {
-                token = chunk;
+            else {
+                const response = await this.client.generate({ model, prompt: fullPrompt, stream: false });
+                result = response.response ?? '';
             }
-            if (onToken)
-                onToken(token);
-            result += token;
+            if (!result.trim()) {
+                throw new Error(`Model '${model}' not found or returned empty response`);
+            }
+            writeCache(request, model, result.trim());
+            cleanupCache();
+            return result.trim();
+        }
+        catch (err) {
+            throw toAIError(err, model);
+        }
+    }
+    async listModels() {
+        try {
+            const models = await this.client.list();
+            return (models.models ?? []).map((m) => m.name);
+        }
+        catch (err) {
+            throw toAIError(err, 'unknown');
+        }
+    }
+}
+/**
+ * In-memory adapter: tests. Satisfies the same interface with no network,
+ * which is what makes AI behavior testable without Ollama installed.
+ */
+export class InMemoryAIClient {
+    constructor(responses = new Map()) {
+        this.responses = responses;
+        this.store = new Map();
+        /** Failures to simulate, keyed by prompt substring. */
+        this.failures = new Map();
+        /** Count of computations performed (not cache reads) — lets tests observe cache hits. */
+        this.computations = 0;
+        /** Simulated clock for expiry tests. */
+        this.now = () => Date.now();
+        /** TTL override for tests; defaults to the production expiry. */
+        this.ttlMs = CACHE_EXPIRY_MS;
+    }
+    async ask(request) {
+        const model = request.model ?? 'test-model';
+        for (const [substring, failure] of this.failures) {
+            if (request.prompt.includes(substring))
+                throw failure;
+        }
+        const key = `${model}:${request.systemMessage ?? ''}:${request.context ?? ''}:${request.prompt}`;
+        const hit = this.store.get(key);
+        if (hit && this.now() - hit.createdAt <= this.ttlMs) {
+            if (request.onToken)
+                request.onToken(hit.response);
+            return hit.response;
         }
-        fs.writeFileSync(cacheKey, result.trim());
-        return result.trim();
+        this.computations += 1;
+        const response = this.responses.get(request.prompt) ?? `response:${request.prompt}`;
+        this.store.set(key, { response, createdAt: this.now() });
+        if (request.onToken)
+            request.onToken(response);
+        return response;
     }
-    catch (err) {
-        throw new Error('Ollama AI error: ' + err.message);
+    async listModels() {
+        return ['test-model', 'other-model'];
     }
 }
+/** Default client: the HTTP adapter. Tests inject InMemoryAIClient instead. */
+let defaultClient;
+export function getAIClient() {
+    if (!defaultClient)
+        defaultClient = new OllamaAIClient();
+    return defaultClient;
+}
+/** Test seam setter: swaps the adapter the module hands out. */
+export function setAIClient(client) {
+    defaultClient = client;
+}
+/**
+ * The interface commands call. Kept as module functions so callers don't
+ * reach for a client object; the client is resolved internally.
+ */
+export async function ask(request) {
+    return getAIClient().ask(request);
+}
+export async function listModels() {
+    return getAIClient().listModels();
+}
+export async function getOllamaStatus() {
+    const endpoint = (process.env.OLLAMA_HOST ?? 'http://127.0.0.1:11434').replace(/\/$/, '');
+    try {
+        const response = await fetch(`${endpoint}/api/version`, { signal: AbortSignal.timeout(1000) });
+        if (!response.ok)
+            return { endpoint };
+        const body = await response.json();
+        return { endpoint, version: typeof body.version === 'string' ? body.version : undefined };
+    }
+    catch {
+        return { endpoint };
+    }
+}
+/** Default model, from configuration — one source of truth. */
+export function defaultModel() {
+    return loadConfig().model;
+}

package/dist/core/command-catalog.d.ts

@@ -0,0 +1,10 @@
+export interface CommandCatalogEntry {
+    name: string;
+    description: string;
+    menuLabel: string;
+    options?: string[];
+}
+export declare const commandCatalog: CommandCatalogEntry[];
+export declare function commandDescription(name: string): string;
+export declare function completionCommands(): string;
+export declare function completionOptions(): string;

package/dist/core/command-catalog.js

@@ -0,0 +1,27 @@
+export const commandCatalog = [
+    { name: 'explain', description: 'Explain a concept or command', menuLabel: 'Explain' },
+    { name: 'suggest', description: 'Get AI-powered suggestions', menuLabel: 'Suggest' },
+    { name: 'fix', description: 'Get a fix for a coding issue or error', menuLabel: 'Fix' },
+    { name: 'review', description: 'Review code in a file or directory', menuLabel: 'Review', options: ['--diff'] },
+    { name: 'optimize', description: 'Optimize a file (e.g., package.json)', menuLabel: 'Optimize' },
+    { name: 'security-check', description: 'Run a security check on code', menuLabel: 'Security Check', options: ['--strict'] },
+    { name: 'generate', description: 'Generate code/tests for a file', menuLabel: 'Generate', options: ['--apply', '--output', '--overwrite'] },
+    { name: 'init', description: 'Interactive setup/configuration wizard', menuLabel: 'Init (Setup)' },
+    { name: 'status', description: 'Check Ollama connection and available models', menuLabel: 'Status' },
+    { name: 'health', description: 'Run comprehensive health check', menuLabel: 'Health Check', options: ['--details'] },
+    { name: 'metrics', description: 'Display CLI usage metrics', menuLabel: 'Metrics', options: ['--raw', '--reset'] },
+    { name: 'project-type', description: 'Detect and print the current project type', menuLabel: 'Project Type' },
+    { name: 'menu', description: 'Interactive command palette', menuLabel: 'Menu' },
+    { name: 'completion', description: 'Generate shell completion script', menuLabel: 'Shell Completion' },
+];
+export function commandDescription(name) {
+    return commandCatalog.find((command) => command.name === name)?.description ?? name;
+}
+export function completionCommands() {
+    return commandCatalog.map((command) => command.name).join(' ');
+}
+export function completionOptions() {
+    const options = new Set(['--help', '--version', '--model', '--verbose', '--json', '--timeout']);
+    commandCatalog.forEach((command) => command.options?.forEach((option) => options.add(option)));
+    return [...options].join(' ');
+}

package/dist/core/command-runner.d.ts

@@ -0,0 +1,17 @@
+import { AIRequest } from '../core/ai.js';
+/** What makes a command distinct. The runner owns everything else. */
+export interface CommandSpec {
+    /** Commander command name, for validation, logging, and metrics. */
+    name: string;
+    /** The user-facing arguments, validated as a unit. */
+    input: Record<string, string>;
+    /** Builds the AI request from validated input. */
+    buildRequest: (input: Record<string, string>, model: string) => AIRequest;
+    /** Header line under the banner, e.g. "📚 Explanation:". */
+    header: string;
+    /** Footer hint shown after success. */
+    footer?: string;
+    /** Post-processing on the full response (e.g. saving generated test files). */
+    onComplete?: (response: string, input: Record<string, string>) => void;
+}
+export declare function runCommand(spec: CommandSpec): Promise<void>;