@vdntio/clai 0.1.0-alpha.1

package/dist/ai/providers/openrouter.js

@@ -0,0 +1,142 @@
+// OpenRouter API Provider Implementation
+// Supports retry logic with exponential backoff for 429 rate limit errors
+import { AIError } from '../types.js';
+const OPENROUTER_URL = 'https://openrouter.ai/api/v1/chat/completions';
+const TIMEOUT_MS = 60_000;
+const MAX_RETRIES = 3;
+/**
+ * Sleep helper for retry delays
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * OpenRouter provider implementation
+ * Handles API calls with authentication, timeout, and retry logic
+ */
+export class OpenRouterProvider {
+    name = 'openrouter';
+    apiKey;
+    constructor(apiKey) {
+        this.apiKey = apiKey;
+    }
+    /**
+     * Check if provider is available (has API key)
+     */
+    isAvailable() {
+        return !!this.apiKey && this.apiKey.length > 0;
+    }
+    /**
+     * Send completion request to OpenRouter
+     * Retries on 429 rate limit with exponential backoff
+     */
+    async complete(request) {
+        let lastError = null;
+        for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+            try {
+                const response = await this.makeRequest(request);
+                if (response.ok) {
+                    const json = await response.json();
+                    return this.parseResponse(json);
+                }
+                // Handle specific status codes
+                const body = await response.text();
+                // 429: Rate limited - retry with backoff
+                if (response.status === 429 && attempt < MAX_RETRIES - 1) {
+                    const delay = 1000 * Math.pow(2, attempt); // 1s, 2s, 4s
+                    await sleep(delay);
+                    continue;
+                }
+                // Other errors: throw immediately
+                throw this.mapError(response.status, body);
+            }
+            catch (err) {
+                // If it's already an AIError, rethrow immediately
+                if (err instanceof AIError) {
+                    throw err;
+                }
+                // Network or other errors
+                lastError = err;
+                // Only retry network errors on first attempt
+                if (attempt === 0 && lastError.message?.includes('fetch')) {
+                    continue;
+                }
+                // Otherwise, throw on last attempt
+                if (attempt === MAX_RETRIES - 1) {
+                    throw new AIError(`Network error: ${lastError.message || 'Unknown error'}`);
+                }
+            }
+        }
+        throw lastError || new AIError('Unknown error during API call');
+    }
+    /**
+     * Make the actual HTTP request
+     */
+    async makeRequest(request) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), TIMEOUT_MS);
+        try {
+            return await fetch(OPENROUTER_URL, {
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${this.apiKey}`,
+                    'Content-Type': 'application/json',
+                    'HTTP-Referer': 'https://github.com/clai',
+                    'X-Title': 'clai',
+                },
+                body: JSON.stringify({
+                    model: request.model,
+                    messages: request.messages,
+                    ...(request.temperature !== undefined && {
+                        temperature: request.temperature,
+                    }),
+                    ...(request.maxTokens !== undefined && {
+                        max_tokens: request.maxTokens,
+                    }),
+                }),
+                signal: controller.signal,
+            });
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * Map HTTP status to appropriate AIError
+     */
+    mapError(status, body) {
+        switch (status) {
+            case 401:
+            case 403:
+                return new AIError(`Authentication error (${status}): ${body || 'Invalid API key'}`, status);
+            case 408:
+            case 504:
+                return new AIError(`Timeout error (${status}): ${body || 'Request timed out'}`, status);
+            case 429:
+                return new AIError(`Rate limit exceeded (${status}): ${body || 'Too many requests'}`, status);
+            default:
+                return new AIError(`API error (${status}): ${body || 'Unknown error'}`, status);
+        }
+    }
+    /**
+     * Parse successful response JSON
+     */
+    parseResponse(json) {
+        const response = json;
+        const content = response.choices?.[0]?.message?.content;
+        if (!content) {
+            throw new AIError('Invalid response: no content in choices');
+        }
+        return {
+            content,
+            model: response.model,
+            usage: response.usage
+                ? {
+                    promptTokens: response.usage.prompt_tokens ?? 0,
+                    completionTokens: response.usage.completion_tokens ?? 0,
+                    totalTokens: response.usage.total_tokens ?? 0,
+                }
+                : undefined,
+        };
+    }
+}

package/dist/ai/types.d.ts

@@ -0,0 +1,46 @@
+import { ClaiError } from '../error/index.js';
+/**
+ * Chat message for OpenAI-compatible API
+ */
+export interface ChatMessage {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+}
+/**
+ * Request to send to AI provider
+ */
+export interface ChatRequest {
+    model: string;
+    messages: ChatMessage[];
+    temperature?: number;
+    maxTokens?: number;
+}
+/**
+ * Response from AI provider
+ */
+export interface ChatResponse {
+    content: string;
+    model?: string;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+}
+/**
+ * Provider interface for future extensibility
+ * Allows adding other providers (Anthropic, Ollama, etc.) in the future
+ */
+export interface AIProvider {
+    name: string;
+    isAvailable(): boolean;
+    complete(request: ChatRequest): Promise<ChatResponse>;
+}
+/**
+ * Error class for AI operations
+ * Exit code 4 as per PRD (API error)
+ */
+export declare class AIError extends ClaiError {
+    readonly statusCode?: number;
+    constructor(message: string, statusCode?: number, cause?: Error);
+}

package/dist/ai/types.js

@@ -0,0 +1,15 @@
+// AI Types and Interfaces for the clai CLI
+import { ClaiError } from '../error/index.js';
+/**
+ * Error class for AI operations
+ * Exit code 4 as per PRD (API error)
+ */
+export class AIError extends ClaiError {
+    statusCode;
+    constructor(message, statusCode, cause) {
+        super(message, 4, cause);
+        this.name = 'AIError';
+        this.statusCode = statusCode;
+        Object.setPrototypeOf(this, AIError.prototype);
+    }
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,19 @@
+export type ColorMode = 'auto' | 'always' | 'never';
+export interface Cli {
+    instruction: string;
+    model?: string;
+    provider?: string;
+    quiet: boolean;
+    verbose: number;
+    noColor: boolean;
+    color: ColorMode;
+    interactive: boolean;
+    force: boolean;
+    dryRun: boolean;
+    context?: string;
+    offline: boolean;
+    numOptions: number;
+    debug: boolean;
+    debugFile?: string;
+}
+export declare function parseCli(argv?: string[]): Cli;

package/dist/cli/index.js

@@ -0,0 +1,71 @@
+import { Command, InvalidArgumentError } from 'commander';
+import { UsageError } from '../error/index.js';
+function parseNumOptions(value) {
+    const num = parseInt(value, 10);
+    if (isNaN(num)) {
+        throw new InvalidArgumentError('Must be a number');
+    }
+    // Clamp to 1-10
+    return Math.max(1, Math.min(10, num));
+}
+function parseColorMode(value) {
+    if (value === 'auto' || value === 'always' || value === 'never') {
+        return value;
+    }
+    throw new InvalidArgumentError('Must be auto, always, or never');
+}
+export function parseCli(argv = process.argv) {
+    const program = new Command();
+    program
+        .name('clai')
+        .description('AI-powered CLI that converts natural language into executable shell commands')
+        .version('0.1.0', '-V, --version', 'Output the version number')
+        .argument('[instruction]', 'Natural language instruction')
+        .option('-m, --model <model>', 'Override AI model')
+        .option('-p, --provider <provider>', 'Override AI provider')
+        .option('-q, --quiet', 'Minimal output', false)
+        .option('-v, --verbose', 'Increase verbosity (can be repeated)', (_, prev) => prev + 1, 0)
+        .option('--no-color', 'Disable color output')
+        .option('--color <mode>', 'Color mode: auto, always, never', parseColorMode, 'auto')
+        .option('-i, --interactive', 'Interactive mode (prompt execute/copy/abort)', false)
+        .option('-f, --force', 'Skip dangerous command confirmation', false)
+        .option('-n, --dry-run', 'Only print command(s), no execute', false)
+        .option('-c, --context <file>', 'Optional context file path')
+        .option('--offline', 'Offline mode (not implemented)', false)
+        .option('-o, --options <count>', 'Number of command options (1-10)', parseNumOptions, 1)
+        .option('-d, --debug', 'Print prompt/request to stderr', false)
+        .option('--debug-file [path]', 'Enable file logging (optional path)')
+        .configureOutput({
+        writeOut: (str) => process.stdout.write(str),
+        writeErr: (str) => process.stderr.write(str),
+        outputError: (str, write) => write(`Error: ${str}`),
+    });
+    program.parse(argv);
+    const opts = program.opts();
+    const args = program.args;
+    // instruction is required unless help/version was shown
+    const instruction = args[0];
+    if (!instruction) {
+        throw new UsageError('missing required argument: instruction');
+    }
+    // --no-color overrides --color
+    const noColor = opts.color === false; // commander sets this when --no-color is used
+    const colorMode = noColor ? 'never' : opts.color;
+    return {
+        instruction,
+        model: opts.model,
+        provider: opts.provider,
+        quiet: opts.quiet,
+        verbose: opts.verbose,
+        noColor,
+        color: colorMode,
+        interactive: opts.interactive,
+        force: opts.force,
+        dryRun: opts.dryRun,
+        context: opts.context,
+        offline: opts.offline,
+        numOptions: opts.options,
+        debug: opts.debug,
+        debugFile: opts.debugFile,
+    };
+}

package/dist/config/index.d.ts

@@ -0,0 +1,12 @@
+import { FileConfig, Config } from './types.js';
+import { Cli } from '../cli/index.js';
+import { ClaiError } from '../error/index.js';
+export declare class ConfigError extends ClaiError {
+    constructor(message: string, code?: number);
+}
+export declare function loadFileConfig(): FileConfig;
+export declare function clearConfigCache(): void;
+export declare function buildConfig(fileConfig: FileConfig, cli: Cli): Config;
+export declare function getConfig(cli: Cli): Config;
+export declare function getProviderApiKey(providerName: string, config: Config): string | undefined;
+export declare function getProviderModel(providerName: string, config: Config): string;

package/dist/config/index.js

@@ -0,0 +1,363 @@
+import { readFileSync, accessSync, constants, statSync } from 'fs';
+import { homedir } from 'os';
+import { resolve, join } from 'path';
+import TOML from '@iarna/toml';
+import { FileConfigSchema, } from './types.js';
+import { ClaiError } from '../error/index.js';
+// Config cache to avoid reloading
+let configCache = null;
+// Default config values
+const DEFAULT_CONFIG = {
+    provider: {
+        default: 'openrouter',
+        fallback: [],
+    },
+    context: {
+        maxFiles: 10,
+        maxHistory: 3,
+        redactPaths: false,
+        redactUsername: false,
+    },
+    safety: {
+        confirmDangerous: true,
+        dangerousPatterns: [],
+    },
+    ui: {
+        color: 'auto',
+        interactive: false,
+        promptTimeout: 30000,
+    },
+    providers: {},
+};
+// Config file paths in order of precedence (lowest to highest)
+function getConfigPaths() {
+    const paths = [];
+    // 1. /etc/clai/config.toml (lowest priority)
+    paths.push('/etc/clai/config.toml');
+    // 2. ~/.config/clai/config.toml
+    const home = homedir();
+    if (home) {
+        paths.push(join(home, '.config', 'clai', 'config.toml'));
+    }
+    // 3. $XDG_CONFIG_HOME/clai/config.toml
+    const xdgConfig = process.env.XDG_CONFIG_HOME;
+    if (xdgConfig) {
+        paths.push(join(xdgConfig, 'clai', 'config.toml'));
+    }
+    // 4. ./.clai.toml (highest priority)
+    paths.push(resolve('.clai.toml'));
+    return paths;
+}
+// Check if file has correct permissions (Unix 0600)
+function checkFilePermissions(path) {
+    // Only check on Unix-like systems
+    if (process.platform === 'win32') {
+        return;
+    }
+    try {
+        const stats = statSync(path);
+        const mode = stats.mode;
+        // Check if permissions are 0600 (owner read/write only)
+        const expectedMode = 0o600;
+        const actualMode = mode & 0o777;
+        if (actualMode !== expectedMode) {
+            throw new ConfigError(`Config file ${path} has insecure permissions ${actualMode.toString(8)}. Must be 0600.`, 3);
+        }
+    }
+    catch (err) {
+        if (err instanceof ConfigError) {
+            throw err;
+        }
+        // If we can't stat the file, that's ok - it might not exist
+    }
+}
+// Custom error class with exit code
+export class ConfigError extends ClaiError {
+    constructor(message, code = 3) {
+        super(message, code);
+        this.name = 'ConfigError';
+        Object.setPrototypeOf(this, ConfigError.prototype);
+    }
+}
+// Check if file exists and is readable
+function fileExists(path) {
+    try {
+        accessSync(path, constants.R_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// Load a single config file
+function loadConfigFile(path) {
+    if (!fileExists(path)) {
+        return {};
+    }
+    // Check permissions on Unix
+    checkFilePermissions(path);
+    try {
+        const content = readFileSync(path, 'utf-8');
+        const parsed = TOML.parse(content);
+        // Transform kebab-case to camelCase for compatibility
+        const transformed = transformConfig(parsed);
+        // Validate with Zod
+        const result = FileConfigSchema.safeParse(transformed);
+        if (!result.success) {
+            throw new ConfigError(`Invalid config file ${path}: ${result.error.message}`, 3);
+        }
+        return result.data;
+    }
+    catch (err) {
+        if (err instanceof ConfigError) {
+            throw err;
+        }
+        if (err instanceof Error) {
+            throw new ConfigError(`Failed to parse config file ${path}: ${err.message}`, 3);
+        }
+        throw err;
+    }
+}
+// Transform config keys from kebab-case to camelCase
+function transformConfig(obj) {
+    if (Array.isArray(obj)) {
+        return obj.map(transformConfig);
+    }
+    if (obj && typeof obj === 'object') {
+        const result = {};
+        for (const [key, value] of Object.entries(obj)) {
+            // Convert kebab-case to camelCase
+            const camelKey = key.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+            result[camelKey] = transformConfig(value);
+        }
+        return result;
+    }
+    return obj;
+}
+// Deep merge two objects
+function deepMerge(target, source) {
+    const result = { ...target };
+    for (const key in source) {
+        if (source[key] !== undefined) {
+            if (typeof source[key] === 'object' &&
+                !Array.isArray(source[key]) &&
+                source[key] !== null &&
+                typeof result[key] === 'object' &&
+                !Array.isArray(result[key]) &&
+                result[key] !== null) {
+                result[key] = deepMerge(result[key], source[key]);
+            }
+            else {
+                result[key] = source[key];
+            }
+        }
+    }
+    return result;
+}
+// Load environment variables that override config
+function loadEnvConfig() {
+    const envConfig = {};
+    // Provider settings
+    if (process.env.CLAI_PROVIDER_DEFAULT || process.env.CLAI_PROVIDER_FALLBACK) {
+        envConfig.provider = {
+            default: process.env.CLAI_PROVIDER_DEFAULT ?? DEFAULT_CONFIG.provider.default,
+            fallback: process.env.CLAI_PROVIDER_FALLBACK
+                ? process.env.CLAI_PROVIDER_FALLBACK.split(',').map((s) => s.trim())
+                : DEFAULT_CONFIG.provider.fallback,
+        };
+    }
+    // Context settings
+    if (process.env.CLAI_CONTEXT_MAX_FILES ||
+        process.env.CLAI_CONTEXT_MAX_HISTORY ||
+        process.env.CLAI_CONTEXT_REDACT_PATHS ||
+        process.env.CLAI_CONTEXT_REDACT_USERNAME) {
+        envConfig.context = {
+            maxFiles: process.env.CLAI_CONTEXT_MAX_FILES
+                ? parseInt(process.env.CLAI_CONTEXT_MAX_FILES, 10) ||
+                    DEFAULT_CONFIG.context.maxFiles
+                : DEFAULT_CONFIG.context.maxFiles,
+            maxHistory: process.env.CLAI_CONTEXT_MAX_HISTORY
+                ? parseInt(process.env.CLAI_CONTEXT_MAX_HISTORY, 10) ||
+                    DEFAULT_CONFIG.context.maxHistory
+                : DEFAULT_CONFIG.context.maxHistory,
+            redactPaths: process.env.CLAI_CONTEXT_REDACT_PATHS
+                ? process.env.CLAI_CONTEXT_REDACT_PATHS === 'true'
+                : DEFAULT_CONFIG.context.redactPaths,
+            redactUsername: process.env.CLAI_CONTEXT_REDACT_USERNAME
+                ? process.env.CLAI_CONTEXT_REDACT_USERNAME === 'true'
+                : DEFAULT_CONFIG.context.redactUsername,
+        };
+    }
+    // Safety settings
+    if (process.env.CLAI_SAFETY_CONFIRM_DANGEROUS ||
+        process.env.CLAI_SAFETY_DANGEROUS_PATTERNS) {
+        envConfig.safety = {
+            confirmDangerous: process.env.CLAI_SAFETY_CONFIRM_DANGEROUS
+                ? process.env.CLAI_SAFETY_CONFIRM_DANGEROUS !== 'false'
+                : DEFAULT_CONFIG.safety.confirmDangerous,
+            dangerousPatterns: process.env.CLAI_SAFETY_DANGEROUS_PATTERNS
+                ? process.env.CLAI_SAFETY_DANGEROUS_PATTERNS.split(',').map((s) => s.trim())
+                : DEFAULT_CONFIG.safety.dangerousPatterns,
+        };
+    }
+    // UI settings
+    if (process.env.CLAI_UI_COLOR || process.env.CLAI_UI_PROMPT_TIMEOUT) {
+        const color = process.env.CLAI_UI_COLOR;
+        const promptTimeout = process.env.CLAI_UI_PROMPT_TIMEOUT
+            ? parseInt(process.env.CLAI_UI_PROMPT_TIMEOUT, 10)
+            : undefined;
+        envConfig.ui = {
+            color: color === 'auto' || color === 'always' || color === 'never'
+                ? color
+                : DEFAULT_CONFIG.ui.color,
+            interactive: DEFAULT_CONFIG.ui.interactive,
+            debugLogFile: DEFAULT_CONFIG.ui.debugLogFile,
+            promptTimeout: promptTimeout !== undefined && !isNaN(promptTimeout)
+                ? Math.max(0, Math.min(300000, promptTimeout))
+                : DEFAULT_CONFIG.ui.promptTimeout,
+        };
+    }
+    return envConfig;
+}
+// Load file config (with caching)
+export function loadFileConfig() {
+    if (configCache) {
+        return configCache;
+    }
+    // Start with defaults
+    let config = { ...DEFAULT_CONFIG };
+    // Load config files in order (lowest to highest priority)
+    const configPaths = getConfigPaths();
+    for (const path of configPaths) {
+        try {
+            const fileConfig = loadConfigFile(path);
+            if (Object.keys(fileConfig).length > 0) {
+                config = deepMerge(config, fileConfig);
+            }
+        }
+        catch (err) {
+            if (err instanceof ConfigError && err.code === 3) {
+                throw err;
+            }
+            // Non-fatal errors for missing files
+        }
+    }
+    // Apply environment overrides
+    const envConfig = loadEnvConfig();
+    config = deepMerge(config, envConfig);
+    // Cache the result
+    configCache = config;
+    return config;
+}
+// Clear config cache (useful for testing)
+export function clearConfigCache() {
+    configCache = null;
+}
+// Build runtime config from file config + CLI
+export function buildConfig(fileConfig, cli) {
+    // Determine effective color mode
+    let color = fileConfig.ui?.color ?? DEFAULT_CONFIG.ui.color;
+    if (cli.noColor) {
+        color = 'never';
+    }
+    else if (cli.color !== 'auto') {
+        color = cli.color;
+    }
+    // Interactive mode: file can enable, CLI can only add
+    const interactive = (fileConfig.ui?.interactive ?? DEFAULT_CONFIG.ui.interactive) ||
+        cli.interactive;
+    // Clamp numOptions to 1-10
+    const numOptions = Math.max(1, Math.min(10, cli.numOptions));
+    // Resolve debug log file path
+    let debugLogFile;
+    if (cli.debugFile !== undefined) {
+        // CLI --debug-file (empty string means use default)
+        if (cli.debugFile === '') {
+            debugLogFile = join(homedir(), '.cache', 'clai', 'debug.log');
+        }
+        else {
+            debugLogFile = resolve(cli.debugFile);
+        }
+    }
+    else if (fileConfig.ui?.debugLogFile) {
+        // From file config
+        const home = homedir();
+        debugLogFile = fileConfig.ui.debugLogFile
+            .replace(/^~\//, home + '/')
+            .replace(/^~$/, home);
+    }
+    return {
+        provider: fileConfig.provider ?? DEFAULT_CONFIG.provider,
+        context: fileConfig.context ?? DEFAULT_CONFIG.context,
+        safety: fileConfig.safety ?? DEFAULT_CONFIG.safety,
+        ui: {
+            color,
+            debugLogFile,
+            interactive,
+            numOptions,
+            promptTimeout: fileConfig.ui?.promptTimeout ?? DEFAULT_CONFIG.ui.promptTimeout,
+        },
+        providers: fileConfig.providers ?? DEFAULT_CONFIG.providers,
+        // CLI overrides
+        model: cli.model,
+        providerName: cli.provider,
+        quiet: cli.quiet,
+        verbose: cli.verbose,
+        force: cli.force,
+        dryRun: cli.dryRun,
+        contextFile: cli.context,
+        offline: cli.offline,
+        debug: cli.debug,
+        debugFile: cli.debugFile,
+        instruction: cli.instruction,
+    };
+}
+// Main entry point: load and build complete config
+export function getConfig(cli) {
+    const fileConfig = loadFileConfig();
+    return buildConfig(fileConfig, cli);
+}
+// Get API key for a provider (with env var resolution)
+export function getProviderApiKey(providerName, config) {
+    const providerConfig = config.providers[providerName];
+    if (!providerConfig) {
+        // Fallback to OPENROUTER_API_KEY for openrouter
+        if (providerName === 'openrouter') {
+            return process.env.OPENROUTER_API_KEY;
+        }
+        return undefined;
+    }
+    // Priority: apiKey (with env var substitution) > apiKeyEnv > env var
+    if (providerConfig.apiKey) {
+        // Resolve env var references like ${VAR} or $VAR
+        let apiKey = providerConfig.apiKey;
+        apiKey = apiKey.replace(/\$\{([^}]+)\}/g, (_, varName) => process.env[varName] || '');
+        apiKey = apiKey.replace(/\$([A-Za-z_][A-Za-z0-9_]*)/g, (_, varName) => process.env[varName] || '');
+        if (apiKey)
+            return apiKey;
+    }
+    if (providerConfig.apiKeyEnv) {
+        return process.env[providerConfig.apiKeyEnv];
+    }
+    // Fallback for openrouter
+    if (providerName === 'openrouter') {
+        return process.env.OPENROUTER_API_KEY;
+    }
+    return undefined;
+}
+// Get model for a provider
+export function getProviderModel(providerName, config) {
+    // Priority: CLI --model > provider config > default
+    if (config.model) {
+        return config.model;
+    }
+    const providerConfig = config.providers[providerName];
+    if (providerConfig?.model) {
+        return providerConfig.model;
+    }
+    // Default models by provider
+    if (providerName === 'openrouter') {
+        return 'qwen/qwen3-coder';
+    }
+    return 'gpt-4o-mini';
+}