@vdntio/clai 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vdntio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,98 @@
+# clAI
+
+> ⚠️ **Alpha Release**: This is an early alpha version. Expect bugs and breaking changes.
+
+AI-powered CLI that converts natural language instructions into executable shell commands using OpenRouter.
+
+## Example
+
+```bash
+clai "find all TypeScript files modified in the last 7 days"
+# Outputs: find . -name "*.ts" -mtime -7
+
+clai "list top 10 largest files in current directory"
+# Outputs: du -h * | sort -rh | head -10
+```
+
+## Features
+
+- 🤖 Natural language to shell commands using AI
+- 🎨 Beautiful terminal UI with Ink
+- 🔒 Safety checks for dangerous commands (rm -rf, etc.)
+- 📝 Context-aware (current directory, shell type, git status)
+- ⚡ Fast startup with Bun runtime
+- 🌍 Cross-platform (Linux, macOS, Windows)
+
+## Installation
+
+### npm (Recommended)
+
+```bash
+npm install -g clai@alpha
+```
+
+### Standalone Binary
+
+Download from [Releases](https://github.com/vdntio/clAI/releases)
+
+See [Installation Guide](docs/installation.md) for detailed instructions.
+
+## Quick Start
+
+1. Get an OpenRouter API key from [openrouter.ai](https://openrouter.ai)
+
+2. Set your API key:
+   ```bash
+   export OPENROUTER_API_KEY="your-key-here"
+   ```
+
+3. Run a command:
+   ```bash
+   clai "your natural language instruction"
+   ```
+
+## Configuration
+
+clAI uses TOML config files. Priority order:
+1. `./.clai.toml` (project-level)
+2. `~/.config/clai/config.toml` (user-level)
+3. `/etc/clai/config.toml` (system-level)
+
+Example config:
+```toml
+openrouter_api_key = "sk-..."
+
+[providers.openrouter]
+model = "qwen/qwen3-coder"  # Default model (can override with anthropic/claude-3.5-sonnet, etc.)
+
+[safety]
+confirm_dangerous = true
+```
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Run in development mode
+bun run dev
+
+# Run tests
+bun test
+
+# Build
+bun run build
+```
+
+## OpenRouter Costs
+
+clAI uses OpenRouter's API which charges per token. Default model is `qwen/qwen3-coder` (free tier available). You can override to use other models like `anthropic/claude-3.5-sonnet` (~$3 per million input tokens). Get credits at [openrouter.ai](https://openrouter.ai).
+
+## License
+
+MIT - See [LICENSE](LICENSE) for details.
+
+## Issues & Feedback
+
+Report bugs or request features at [GitHub Issues](https://github.com/vdntio/clAI/issues).

package/dist/ai/index.d.ts

@@ -0,0 +1,24 @@
+import { ContextData } from '../context/types.js';
+import type { Config } from '../config/types.js';
+import { ChatMessage } from './types.js';
+export { AIError, } from './types.js';
+export type { ChatMessage, ChatRequest, ChatResponse, AIProvider, } from './types.js';
+export { buildPrompt } from './prompt.js';
+export { parseResponse } from './parser.js';
+export { OpenRouterProvider } from './providers/index.js';
+export { MockProvider } from './mock.js';
+/**
+ * Generate shell commands from natural language instruction
+ *
+ * @param context - Gathered context (system, directory, history, stdin)
+ * @param instruction - User's natural language instruction
+ * @param config - Runtime configuration
+ * @returns Array of command strings (1 for single mode, N for multi mode)
+ * @throws AIError on API failure or parse error (exit code 4)
+ */
+export declare function generateCommands(context: ContextData, instruction: string, config: Config): Promise<string[]>;
+/**
+ * Format messages for debug output
+ * Returns formatted string showing all messages
+ */
+export declare function formatPromptForDebug(messages: ChatMessage[]): string;

package/dist/ai/index.js

@@ -0,0 +1,78 @@
+// AI module main entry point
+// Provides generateCommands() for converting natural language to shell commands
+import { getProviderApiKey, getProviderModel } from '../config/index.js';
+import { AIError, } from './types.js';
+import { buildPrompt } from './prompt.js';
+import { parseResponse } from './parser.js';
+import { OpenRouterProvider } from './providers/index.js';
+import { MockProvider } from './mock.js';
+// Re-export types for consumers
+export { AIError, } from './types.js';
+export { buildPrompt } from './prompt.js';
+export { parseResponse } from './parser.js';
+export { OpenRouterProvider } from './providers/index.js';
+export { MockProvider } from './mock.js';
+/**
+ * Generate shell commands from natural language instruction
+ *
+ * @param context - Gathered context (system, directory, history, stdin)
+ * @param instruction - User's natural language instruction
+ * @param config - Runtime configuration
+ * @returns Array of command strings (1 for single mode, N for multi mode)
+ * @throws AIError on API failure or parse error (exit code 4)
+ */
+export async function generateCommands(context, instruction, config) {
+    const providerName = config.providerName || config.provider.default;
+    const numOptions = config.ui.numOptions;
+    // Get appropriate provider
+    const provider = getProvider(providerName, config);
+    // Build prompt messages
+    const messages = buildPrompt(context, instruction, numOptions);
+    // Get model (from CLI, config, or default)
+    const model = getProviderModel(providerName, config);
+    // Make API request
+    const request = {
+        model,
+        messages,
+        temperature: 0.1, // Low temperature for more deterministic commands
+    };
+    const response = await provider.complete(request);
+    // Parse response into command(s)
+    return parseResponse(response.content, numOptions > 1);
+}
+/**
+ * Get provider instance based on configuration
+ * Returns mock provider if MOCK_AI=1 is set
+ */
+function getProvider(name, config) {
+    // Check for mock mode
+    if (process.env.MOCK_AI === '1') {
+        return new MockProvider();
+    }
+    // Currently only OpenRouter is supported
+    // Future: add more providers here (Anthropic, Ollama, etc.)
+    if (name === 'openrouter') {
+        const apiKey = getProviderApiKey('openrouter', config);
+        if (!apiKey) {
+            throw new AIError('OpenRouter API key not configured. ' +
+                'Set OPENROUTER_API_KEY environment variable or configure api_key in .clai.toml');
+        }
+        return new OpenRouterProvider(apiKey);
+    }
+    throw new AIError(`Unknown provider: ${name}. ` + 'Currently only "openrouter" is supported.');
+}
+/**
+ * Format messages for debug output
+ * Returns formatted string showing all messages
+ */
+export function formatPromptForDebug(messages) {
+    return messages
+        .map((msg) => {
+        const role = msg.role.charAt(0).toUpperCase() + msg.role.slice(1);
+        const content = msg.content.length > 500
+            ? msg.content.substring(0, 500) + '...'
+            : msg.content;
+        return `[${role}]\n${content}`;
+    })
+        .join('\n\n');
+}

package/dist/ai/mock.d.ts

@@ -0,0 +1,17 @@
+import { AIProvider, ChatRequest, ChatResponse } from './types.js';
+/**
+ * Mock provider for testing
+ * Returns predictable responses without API calls
+ */
+export declare class MockProvider implements AIProvider {
+    name: string;
+    /**
+     * Always available (no API key needed)
+     */
+    isAvailable(): boolean;
+    /**
+     * Return mock response based on request
+     * Detects multi-command mode from system message
+     */
+    complete(request: ChatRequest): Promise<ChatResponse>;
+}

package/dist/ai/mock.js

@@ -0,0 +1,49 @@
+// Mock AI Provider for testing
+// Returns simple echo commands without making real API calls
+// Activated by setting MOCK_AI=1 environment variable
+/**
+ * Mock provider for testing
+ * Returns predictable responses without API calls
+ */
+export class MockProvider {
+    name = 'mock';
+    /**
+     * Always available (no API key needed)
+     */
+    isAvailable() {
+        return true;
+    }
+    /**
+     * Return mock response based on request
+     * Detects multi-command mode from system message
+     */
+    async complete(request) {
+        const systemMsg = request.messages[0]?.content || '';
+        const isMultiCommand = systemMsg.includes('JSON');
+        if (isMultiCommand) {
+            // Extract number of commands from system message
+            const match = systemMsg.match(/exactly (\d+) different/);
+            const numCommands = match?.[1] ? parseInt(match[1], 10) : 3;
+            const commands = Array.from({ length: numCommands }, (_, i) => `echo "mock command ${i + 1}"`);
+            return {
+                content: JSON.stringify({ commands }),
+                model: 'mock',
+                usage: {
+                    promptTokens: 100,
+                    completionTokens: 50,
+                    totalTokens: 150,
+                },
+            };
+        }
+        // Single command
+        return {
+            content: 'echo "mock command"',
+            model: 'mock',
+            usage: {
+                promptTokens: 50,
+                completionTokens: 10,
+                totalTokens: 60,
+            },
+        };
+    }
+}

package/dist/ai/parser.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Parse AI response content into command(s)
+ *
+ * Handles:
+ * - Markdown code fence stripping (```bash, ```sh, ```shell, ```json, ```)
+ * - JSON parsing for multi-command mode: {"commands": [...]} or [...]
+ * - Fallback to single trimmed command
+ *
+ * @param content - Raw response content from AI
+ * @param expectMultiple - Whether to expect multiple commands (numOptions > 1)
+ * @returns Array of command strings
+ * @throws AIError if response is empty or cannot be parsed
+ */
+export declare function parseResponse(content: string, expectMultiple: boolean): string[];

package/dist/ai/parser.js

@@ -0,0 +1,109 @@
+// Response parser for AI output
+import { AIError } from './types.js';
+/**
+ * Parse AI response content into command(s)
+ *
+ * Handles:
+ * - Markdown code fence stripping (```bash, ```sh, ```shell, ```json, ```)
+ * - JSON parsing for multi-command mode: {"commands": [...]} or [...]
+ * - Fallback to single trimmed command
+ *
+ * @param content - Raw response content from AI
+ * @param expectMultiple - Whether to expect multiple commands (numOptions > 1)
+ * @returns Array of command strings
+ * @throws AIError if response is empty or cannot be parsed
+ */
+export function parseResponse(content, expectMultiple) {
+    // 1. Trim whitespace
+    let cleaned = content.trim();
+    if (!cleaned) {
+        throw new AIError('AI returned empty response');
+    }
+    // 2. Strip markdown code fences
+    cleaned = stripCodeFences(cleaned);
+    // Check if empty after stripping fences
+    if (!cleaned) {
+        throw new AIError('AI returned empty response after parsing');
+    }
+    // 3. Try JSON parse for multi-command mode
+    if (expectMultiple) {
+        const commands = tryParseMultipleCommands(cleaned);
+        if (commands.length > 0) {
+            return commands;
+        }
+    }
+    // 4. Fallback: treat as single command
+    cleaned = cleaned.trim();
+    if (!cleaned) {
+        throw new AIError('AI returned empty response after parsing');
+    }
+    return [cleaned];
+}
+/**
+ * Strip markdown code fences from content
+ * Handles multiple fence formats
+ */
+function stripCodeFences(content) {
+    // Pattern 1: ```language\ncontent\n```
+    // Pattern 2: ```\ncontent\n```
+    // Must match the entire string from start to end
+    const lines = content.split('\n');
+    // Check if first line is an opening fence
+    if (lines[0]?.startsWith('```')) {
+        // Check if last line is a closing fence
+        if (lines[lines.length - 1] === '```') {
+            // Remove first and last lines
+            return lines.slice(1, -1).join('\n').trim();
+        }
+        // Single line case: ```content```
+        const singleLineMatch = content.match(/^```[\w]*\s*(.+?)\s*```$/);
+        if (singleLineMatch?.[1]) {
+            return singleLineMatch[1].trim();
+        }
+    }
+    return content;
+}
+/**
+ * Try to parse multiple commands from JSON
+ * Returns empty array if parsing fails
+ */
+function tryParseMultipleCommands(content) {
+    // Try to extract JSON object if content has extra text
+    let jsonContent = content;
+    // Look for JSON object pattern if content has extra text
+    const jsonMatch = content.match(/\{[\s\S]*"commands"[\s\S]*\}/);
+    if (jsonMatch) {
+        jsonContent = jsonMatch[0];
+    }
+    try {
+        const parsed = JSON.parse(jsonContent);
+        // Handle {"commands": [...]}
+        if (parsed.commands && Array.isArray(parsed.commands)) {
+            const cmds = parsed.commands.filter((c) => typeof c === 'string' && c.trim());
+            return cmds.map((c) => c.trim());
+        }
+        // Handle raw array [...]
+        if (Array.isArray(parsed)) {
+            const cmds = parsed.filter((c) => typeof c === 'string' && c.trim());
+            return cmds.map((c) => c.trim());
+        }
+    }
+    catch {
+        // JSON parse failed, try to extract from text
+        // Look for array pattern: ["cmd1", "cmd2"]
+        const arrayMatch = content.match(/\[[\s\S]*\]/);
+        if (arrayMatch) {
+            try {
+                const parsed = JSON.parse(arrayMatch[0]);
+                if (Array.isArray(parsed)) {
+                    const cmds = parsed.filter((c) => typeof c === 'string' && c.trim());
+                    return cmds.map((c) => c.trim());
+                }
+            }
+            catch {
+                // JSON parse failed, continue to other strategies
+            }
+        }
+    }
+    return [];
+}

package/dist/ai/prompt.d.ts

@@ -0,0 +1,12 @@
+import { ContextData } from '../context/types.js';
+import { ChatMessage } from './types.js';
+/**
+ * Build chat messages for AI request
+ * Constructs system and user messages based on context and instruction
+ *
+ * @param context - Gathered system/directory/history/stdin context
+ * @param instruction - User's natural language instruction
+ * @param numOptions - Number of command options to generate (1 for single, >1 for multi)
+ * @returns Array of chat messages for the AI
+ */
+export declare function buildPrompt(context: ContextData, instruction: string, numOptions: number): ChatMessage[];

package/dist/ai/prompt.js

@@ -0,0 +1,76 @@
+// Prompt builder for AI requests
+/**
+ * Build chat messages for AI request
+ * Constructs system and user messages based on context and instruction
+ *
+ * @param context - Gathered system/directory/history/stdin context
+ * @param instruction - User's natural language instruction
+ * @param numOptions - Number of command options to generate (1 for single, >1 for multi)
+ * @returns Array of chat messages for the AI
+ */
+export function buildPrompt(context, instruction, numOptions) {
+    const isMultiCommand = numOptions > 1;
+    // System message differs for single vs multi-command
+    const systemMessage = isMultiCommand
+        ? buildMultiCommandSystemPrompt(numOptions)
+        : buildSingleCommandSystemPrompt();
+    // User message includes context and instruction
+    const userMessage = buildUserPrompt(context, instruction, numOptions);
+    return [
+        { role: 'system', content: systemMessage },
+        { role: 'user', content: userMessage },
+    ];
+}
+/**
+ * Build system prompt for single command generation
+ */
+function buildSingleCommandSystemPrompt() {
+    return `You are a helpful assistant that converts natural language instructions into executable shell commands. Respond with ONLY the command, no explanations or markdown.`;
+}
+/**
+ * Build system prompt for multi-command generation
+ */
+function buildMultiCommandSystemPrompt(numOptions) {
+    return `You are a helpful assistant that converts natural language instructions into executable shell commands. Generate exactly ${numOptions} different command options. Respond ONLY with a JSON object in this format: {"commands": ["cmd1", "cmd2", ...]}. No markdown, no explanations.`;
+}
+/**
+ * Build user prompt with context data
+ */
+function buildUserPrompt(context, instruction, numOptions) {
+    const parts = [];
+    // System context
+    parts.push(`System Context:
+OS: ${context.system.osName} ${context.system.osVersion}
+Architecture: ${context.system.architecture}
+Shell: ${context.system.shell}
+User: ${context.system.user}
+Memory: ${context.system.totalMemoryMb} MB`);
+    // Directory context
+    const filesList = context.files.length > 0
+        ? context.files.slice(0, 20).join(', ')
+        : '(empty directory)';
+    parts.push(`\nDirectory Context:
+Current directory: ${context.cwd}
+Files: ${filesList}`);
+    // History context (if available)
+    if (context.history.length > 0) {
+        const historyList = context.history
+            .map((h, i) => `${i + 1}. ${h}`)
+            .join('\n');
+        parts.push(`\nRecent Shell History:\n${historyList}`);
+    }
+    // Stdin context (if available)
+    if (context.stdin) {
+        parts.push(`\nStdin input:\n${context.stdin}`);
+    }
+    // User instruction
+    parts.push(`\nUser Instruction: ${instruction}`);
+    // Response instruction differs for single vs multi
+    if (numOptions > 1) {
+        parts.push(`\nRespond with exactly ${numOptions} different command options as JSON: {"commands": ["cmd1", "cmd2", ...]}. Order from simplest to most advanced. No markdown or explanations.`);
+    }
+    else {
+        parts.push(`\nRespond ONLY with the executable command. Do not include markdown code fences, explanations, or any other text. Just the command itself.`);
+    }
+    return parts.join('');
+}

package/dist/ai/providers/index.d.ts

@@ -0,0 +1 @@
+export { OpenRouterProvider } from './openrouter.js';

package/dist/ai/providers/index.js

@@ -0,0 +1,2 @@
+// Provider exports
+export { OpenRouterProvider } from './openrouter.js';

package/dist/ai/providers/openrouter.d.ts

@@ -0,0 +1,31 @@
+import { AIProvider, ChatRequest, ChatResponse } from '../types.js';
+/**
+ * OpenRouter provider implementation
+ * Handles API calls with authentication, timeout, and retry logic
+ */
+export declare class OpenRouterProvider implements AIProvider {
+    name: string;
+    private apiKey;
+    constructor(apiKey: string);
+    /**
+     * Check if provider is available (has API key)
+     */
+    isAvailable(): boolean;
+    /**
+     * Send completion request to OpenRouter
+     * Retries on 429 rate limit with exponential backoff
+     */
+    complete(request: ChatRequest): Promise<ChatResponse>;
+    /**
+     * Make the actual HTTP request
+     */
+    private makeRequest;
+    /**
+     * Map HTTP status to appropriate AIError
+     */
+    private mapError;
+    /**
+     * Parse successful response JSON
+     */
+    private parseResponse;
+}