moth-ai 1.0.3

package/README.md

@@ -0,0 +1,319 @@
+# 🦋 Moth AI
+
+[![npm version](https://img.shields.io/npm/v/@kishlay42/moth-ai.svg)](https://www.npmjs.com/package/@kishlay42/moth-ai)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+[![Node.js Version](https://img.shields.io/node/v/@kishlay42/moth-ai.svg)](https://nodejs.org)
+
+**The Intelligent, Local-First CLI Coding Assistant**
+
+Moth AI is a powerful **terminal-native coding assistant** built for developers who value **privacy, speed, and control**. It lives inside your terminal, understands your project context, and helps you **write, debug, refactor, and reason about code** using both **local and cloud LLMs**.
+
+<img width="1095" height="504" alt="Moth AI Screenshot" src="https://github.com/user-attachments/assets/23b83a6b-2b63-45af-b9ec-a6dcb0a89b2f" />
+
+---
+
+## 📦 Installation
+
+### Global Installation (Recommended)
+
+Install Moth AI globally to use it anywhere on your system:
+
+```bash
+npm install -g @kishlay42/moth-ai
+```
+
+After installation, simply run:
+
+```bash
+moth
+```
+
+### Local Installation
+
+Install in a specific project:
+
+```bash
+npm install @kishlay42/moth-ai
+```
+
+Run using npx:
+
+```bash
+npx moth
+```
+
+### Requirements
+
+- **Node.js**: >= 18.0.0
+- **npm**: >= 8.0.0
+
+---
+
+## 🚀 Quick Start
+
+1. **Install Moth AI globally:**
+   ```bash
+   npm install -g @kishlay42/moth-ai
+   ```
+
+2. **Add your first LLM profile:**
+   ```bash
+   moth llm add
+   ```
+   
+   Choose from:
+   - **Local models** (via Ollama) - Free, private, offline
+   - **Cloud providers** (OpenAI, Anthropic, Google) - Requires API key
+
+3. **Start chatting:**
+   ```bash
+   moth
+   ```
+
+4. **Use the command palette:**
+   - Press `Ctrl+U` to access all commands
+   - Switch profiles, toggle autopilot, and more
+
+---
+
+## ✨ Key Features
+
+### 🧠 LLM-Agnostic & Local-First
+
+Use **any LLM**, local or cloud — switch instantly without changing workflows.
+
+- **Local (via Ollama)**  
+  Run models like **Llama 3**, **Mistral**, **Gemma**, and **DeepSeek-Coder** locally  
+  → Zero latency, full privacy, offline-friendly
+
+- **Cloud Providers**  
+  Plug in your own API keys for:
+  - OpenAI (GPT-4 / GPT-4o)
+  - Anthropic (Claude 3.5 Sonnet)
+  - Google (Gemini)
+
+<img width="1093" height="241" alt="LLM Switching" src="https://github.com/user-attachments/assets/2de67c9d-f562-4ce3-8bc6-51e2066b69ae" />
+
+---
+
+### 🤖 Agentic Capabilities
+
+Moth is not just a chatbot — it's an **AI agent**.
+
+- **Task Planning** – Break complex goals into executable steps  
+- **File Editing** – Precise diffs, patches, and refactors  
+- **Terminal Control** – Run builds, tests, and Git commands from chat  
+- **Context-Aware** – Understands your project structure and codebase
+
+---
+
+### 🛡️ Permission-First by Design
+
+You stay in control — always.
+
+- Explicit approval before file edits or command execution  
+- Granular permissions per action  
+- **Autopilot mode** for trusted workflows  
+- Feedback loop to guide the agent instead of blind execution  
+
+---
+
+### 🎭 Moth Profiles
+
+Save and switch between different AI personalities.
+
+- **Coding Profile** – Optimized for TypeScript / Python  
+- **Architecture Profile** – Reasoning-focused for system design  
+- **Fast Profile** – Lightweight local model for quick answers  
+
+---
+
+## � CLI Commands
+
+### Main Commands
+
+```bash
+# Start interactive chat
+moth
+
+# Show help
+moth --help
+
+# Display version
+moth --version
+```
+
+### LLM Profile Management
+
+```bash
+# Add a new LLM profile
+moth llm add
+
+# List all configured profiles
+moth llm list
+
+# Switch to a different profile
+moth llm use
+
+# Remove a profile
+moth llm remove
+```
+
+### Keyboard Shortcuts
+
+- **Ctrl+U** - Open command palette
+- **Ctrl+C** - Exit chat
+- **Arrow Keys** - Navigate command palette
+- **Enter** - Execute selected command
+
+---
+
+## ⚙️ Configuration
+
+Moth AI stores configuration in `~/.moth/config.yaml`
+
+### Example Configuration
+
+```yaml
+profiles:
+  - name: "gpt-4"
+    provider: "openai"
+    model: "gpt-4"
+    apiKey: "sk-..."
+    
+  - name: "local-llama"
+    provider: "ollama"
+    model: "llama3"
+    baseUrl: "http://localhost:11434"
+    
+activeProfile: "gpt-4"
+```
+
+### Setting Up Ollama (Local Models)
+
+1. Install Ollama: https://ollama.ai
+2. Pull a model:
+   ```bash
+   ollama pull llama3
+   ```
+3. Add to Moth:
+   ```bash
+   moth llm add
+   # Select "Ollama" and choose your model
+   ```
+
+### Setting Up Cloud Providers
+
+#### OpenAI
+```bash
+moth llm add
+# Select "OpenAI"
+# Enter your API key from https://platform.openai.com/api-keys
+```
+
+#### Anthropic (Claude)
+```bash
+moth llm add
+# Select "Anthropic"
+# Enter your API key from https://console.anthropic.com/
+```
+
+#### Google (Gemini)
+```bash
+moth llm add
+# Select "Google"
+# Enter your API key from https://makersuite.google.com/app/apikey
+```
+
+---
+
+## 💡 Usage Examples
+
+### Basic Chat
+
+```bash
+moth
+> How do I implement a binary search in TypeScript?
+```
+
+### Code Refactoring
+
+```bash
+moth
+> Refactor src/utils.ts to use async/await instead of promises
+```
+
+### Debugging
+
+```bash
+moth
+> Why is my React component re-rendering infinitely?
+```
+
+### Project Analysis
+
+```bash
+moth
+> Analyze the architecture of this project and suggest improvements
+```
+
+---
+
+## 🔧 Troubleshooting
+
+### Command not found: moth
+
+Make sure the global npm bin directory is in your PATH:
+
+```bash
+npm config get prefix
+```
+
+Add the bin directory to your PATH in `~/.bashrc` or `~/.zshrc`:
+
+```bash
+export PATH="$PATH:$(npm config get prefix)/bin"
+```
+
+### Ollama connection error
+
+Ensure Ollama is running:
+
+```bash
+ollama serve
+```
+
+### API key errors
+
+Verify your API key is correctly configured:
+
+```bash
+moth llm list
+# Check if your profile shows the correct provider
+```
+
+---
+
+## 📝 License
+
+ISC License - see [LICENSE](LICENSE) file for details
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+Repository: https://github.com/kishlay42/Moth-ai
+
+---
+
+## 📚 Links
+
+- **npm Package**: https://www.npmjs.com/package/@kishlay42/moth-ai
+- **GitHub**: https://github.com/kishlay42/Moth-ai
+- **Issues**: https://github.com/kishlay42/Moth-ai/issues
+
+---
+
+**Made with ❤️ for developers who code in the terminal**

package/dist/agent/orchestrator.js

@@ -0,0 +1,141 @@
+import { formatFileForContext, truncateFileContent } from '../utils/fileUtils.js';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+export class AgentOrchestrator {
+    config;
+    state;
+    tools;
+    root;
+    constructor(config, registry, root = process.cwd()) {
+        this.config = config;
+        this.tools = registry;
+        this.root = root;
+        this.state = {
+            history: [],
+            maxSteps: config.maxSteps || 10
+        };
+    }
+    async *run(prompt, history = []) {
+        let currentPrompt = prompt;
+        for (let i = 0; i < this.state.maxSteps; i++) {
+            // Collect all attached files from history
+            const allAttachedFiles = this.collectAttachedFiles(history);
+            // Construct system prompt with tools and file context
+            const systemPrompt = await this.buildSystemPrompt(allAttachedFiles);
+            // Full context: System -> History -> Current State
+            const messages = [
+                { role: 'user', content: systemPrompt }, // In many APIs system prompt is special, here we use user role as generic fallback or modify Client to handle system
+                ...history,
+                { role: 'user', content: currentPrompt }
+            ];
+            // This is a simplified Mock for the ReAct loop to start with
+            // In reality, we need to handle the LLM raw output, parse "Thought" and "Tool Call"
+            // For now, we will rely on a Structured Output or strict parsing if the Provider supports it.
+            // Since we are using Gemini, we can ask for JSON mode or specific formatting.
+            const responseText = await this.callLLM(messages);
+            // Parse response
+            let step;
+            try {
+                step = this.parseResponse(responseText);
+            }
+            catch (e) {
+                yield { thought: "Failed to parse LLM response. Retrying...", toolOutput: `Error: ${e}` };
+                continue;
+            }
+            this.state.history.push(step);
+            yield step;
+            if (step.finalAnswer) {
+                return step.finalAnswer;
+            }
+            if (step.toolCall) {
+                // Execute tool
+                const result = await this.executeTool(step.toolCall.name, step.toolCall.arguments);
+                step.toolOutput = result;
+                // Re-feed result to LLM
+                currentPrompt = `Tool '${step.toolCall.name}' returned: ${result}`;
+            }
+        }
+        return "Max steps reached.";
+    }
+    async buildSystemPrompt(attachedFiles = []) {
+        const toolDefs = this.tools.getDefinitions().map(t => `${t.name}: ${t.description} Params: ${JSON.stringify(t.parameters)}`).join('\n');
+        let fileContext = '';
+        if (attachedFiles.length > 0) {
+            fileContext = await this.buildFileContext(attachedFiles);
+        }
+        return `You are Moth, an intelligent CLI coding assistant.
+You have access to the following tools:
+${toolDefs}
+
+${fileContext}
+
+IMPORTANT GUIDELINES:
+1. For general questions, explanations, or code snippets that don't need to be saved, use "finalAnswer". 
+2. Do NOT use "write_to_file" unless the user explicitly asks to save a file or implies a persistent change.
+3. If the user asks for "Hello World code", just show it in the explanation (finalAnswer). Do NOT create a file for it.
+4. Be concise and helpful.
+5. If files are referenced above, use that context to answer questions about them.
+
+Format your response exactly as a JSON object:
+{
+  "thought": "your reasoning",
+  "toolCall": { "name": "tool_name", "arguments": { ... } }
+}
+OR if you are done/replying:
+{
+  "thought": "reasoning",
+  "finalAnswer": "your response/code/explanation"
+}
+`;
+    }
+    collectAttachedFiles(history) {
+        const files = new Set();
+        for (const msg of history) {
+            if (msg.attachedFiles) {
+                msg.attachedFiles.forEach(f => files.add(f));
+            }
+        }
+        return Array.from(files);
+    }
+    async buildFileContext(filePaths) {
+        const fileContents = ['=== Referenced Files ===\n'];
+        for (const filePath of filePaths) {
+            try {
+                const fullPath = path.join(this.root, filePath);
+                // Security: Prevent breaking out of root
+                if (!fullPath.startsWith(this.root)) {
+                    fileContents.push(`File: ${filePath}\nError: Access denied (outside project root)\n`);
+                    continue;
+                }
+                const content = await fs.readFile(fullPath, 'utf-8');
+                const truncated = truncateFileContent(content, 500);
+                const formatted = formatFileForContext(filePath, truncated);
+                fileContents.push(formatted);
+            }
+            catch (e) {
+                fileContents.push(`File: ${filePath}\nError: ${e.message}\n`);
+            }
+        }
+        return fileContents.join('\n');
+    }
+    async callLLM(messages) {
+        // Direct integration with LLM Client
+        // This assumes Client has a simple chat interface returning string
+        // We might need to adjust LLMClient interface to support non-streaming one-off calls
+        // Placeholder: We will need to implement a 'generate' method on LLMClient
+        // or collect the stream.
+        let fullText = "";
+        for await (const chunk of this.config.model.chatStream(messages)) {
+            fullText += chunk;
+        }
+        return fullText;
+    }
+    parseResponse(text) {
+        // Clean markdown code blocks if present
+        const jsonText = text.replace(/```json/g, '').replace(/```/g, '').trim();
+        return JSON.parse(jsonText);
+    }
+    async executeTool(name, args) {
+        return await this.tools.execute(name, args);
+    }
+}

package/dist/agent/types.js

@@ -0,0 +1 @@
+export {};

package/dist/config/configManager.js

@@ -0,0 +1,62 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import yaml from 'js-yaml';
+import { CONFIG_DIR, ensureConfigDir } from '../utils/paths.js';
+const CONFIG_FILE = path.join(CONFIG_DIR, 'profiles.yaml');
+const DEFAULT_CONFIG = {
+    profiles: [],
+};
+export function loadConfig() {
+    ensureConfigDir();
+    if (!fs.existsSync(CONFIG_FILE)) {
+        saveConfig(DEFAULT_CONFIG);
+        return DEFAULT_CONFIG;
+    }
+    try {
+        const content = fs.readFileSync(CONFIG_FILE, 'utf8');
+        const parsed = yaml.load(content);
+        // ensure structure matches
+        return {
+            profiles: parsed?.profiles || [],
+            activeProfile: parsed?.activeProfile,
+            username: parsed?.username
+        };
+    }
+    catch (e) {
+        // console.error('Failed to load config, using default', e); 
+        // ^ Silence for now or use UI error in future
+        return DEFAULT_CONFIG;
+    }
+}
+export function saveConfig(config) {
+    ensureConfigDir();
+    fs.writeFileSync(CONFIG_FILE, yaml.dump(config), 'utf8');
+}
+export function addProfile(config, profile) {
+    const existingIndex = config.profiles.findIndex(p => p.name === profile.name);
+    if (existingIndex >= 0) {
+        config.profiles[existingIndex] = profile;
+    }
+    else {
+        config.profiles.push(profile);
+    }
+    return config;
+}
+export function removeProfile(config, name) {
+    config.profiles = config.profiles.filter(p => p.name !== name);
+    if (config.activeProfile === name) {
+        config.activeProfile = undefined;
+    }
+    return config;
+}
+export function setActiveProfile(config, name) {
+    const exists = config.profiles.some(p => p.name === name);
+    if (exists) {
+        config.activeProfile = name;
+    }
+    return config;
+}
+export function setUsername(config, username) {
+    config.username = username;
+    return config;
+}

package/dist/config/keychain.js

@@ -0,0 +1,20 @@
+import keytar from 'keytar';
+const SERVICE_NAME = 'moth-cli';
+const LEGACY_SERVICE_NAME = 'saute-cli';
+export async function setApiKey(profileName, key) {
+    await keytar.setPassword(SERVICE_NAME, profileName, key);
+}
+export async function getApiKey(profileName) {
+    let key = await keytar.getPassword(SERVICE_NAME, profileName);
+    if (!key) {
+        // Try legacy service and migrate if found
+        key = await keytar.getPassword(LEGACY_SERVICE_NAME, profileName);
+        if (key) {
+            await keytar.setPassword(SERVICE_NAME, profileName, key);
+        }
+    }
+    return key;
+}
+export async function deleteApiKey(profileName) {
+    return keytar.deletePassword(SERVICE_NAME, profileName);
+}

package/dist/context/ignore.js

@@ -0,0 +1,27 @@
+import ignore from 'ignore';
+import * as fs from 'fs';
+import * as path from 'path';
+export class IgnoreManager {
+    ig = ignore();
+    constructor(root) {
+        this.loadIgnoreFile(root);
+        // Always ignore .git and node_modules
+        this.ig.add(['.git', 'node_modules', '.moth', 'dist', 'coverage']);
+    }
+    loadIgnoreFile(root) {
+        const ignorePath = path.join(root, '.gitignore');
+        if (fs.existsSync(ignorePath)) {
+            try {
+                const content = fs.readFileSync(ignorePath, 'utf8');
+                this.ig.add(content);
+            }
+            catch (error) {
+                console.warn('Failed to load .gitignore:', error);
+            }
+        }
+    }
+    shouldIgnore(filePath) {
+        // ignore package expects relative paths
+        return this.ig.ignores(filePath);
+    }
+}

package/dist/context/manager.js

@@ -0,0 +1,62 @@
+import { ProjectScanner } from './scanner.js';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+export class ContextManager {
+    scanner;
+    root;
+    constructor(root) {
+        this.root = root;
+        this.scanner = new ProjectScanner(root);
+    }
+    async gather(request) {
+        const filePaths = await this.scanner.scan();
+        const files = [];
+        // Simple Scoring: 
+        // 1. Exact filename match (1.0)
+        // 2. Query terms in path (0.5)
+        // 3. Default (0.1)
+        // Normalize query terms
+        const terms = request.query.toLowerCase().split(/\s+/);
+        for (const filePath of filePaths) {
+            let score = 0.1;
+            const lowerPath = filePath.toLowerCase();
+            const basename = path.basename(lowerPath);
+            if (terms.some(t => basename === t)) {
+                score = 1.0;
+            }
+            else if (terms.some(t => lowerPath.includes(t))) {
+                score = 0.5;
+            }
+            // Basic Tiering Logic (Placeholder)
+            // If score > 0.8 => Full
+            // If score > 0.4 => Summary (but we don't have summarizer yet, so Path)
+            // Else => Path
+            let tier = 'path';
+            let content;
+            if (score >= 0.8) {
+                tier = 'full';
+                try {
+                    // Limit file read size for safety
+                    content = await fs.readFile(path.join(this.root, filePath), 'utf8');
+                    // Truncate if too huge? (TODO)
+                }
+                catch (e) {
+                    console.warn(`Failed to read ${filePath}`, e);
+                    tier = 'path';
+                }
+            }
+            files.push({
+                path: filePath,
+                relevance: score,
+                tier,
+                content
+            });
+        }
+        // Sort by relevance
+        files.sort((a, b) => b.relevance - a.relevance);
+        return {
+            files,
+            totalTokens: 0 // Placeholder
+        };
+    }
+}

package/dist/context/scanner.js

@@ -0,0 +1,41 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { IgnoreManager } from './ignore.js';
+export class ProjectScanner {
+    root;
+    ignoreManager;
+    constructor(root) {
+        this.root = root;
+        this.ignoreManager = new IgnoreManager(root);
+    }
+    async scan() {
+        const files = [];
+        await this.scanDir('', files);
+        return files;
+    }
+    async scanDir(relativeDir, fileList) {
+        const fullDir = path.join(this.root, relativeDir);
+        // Check if directory itself is ignored
+        if (relativeDir && this.ignoreManager.shouldIgnore(relativeDir)) {
+            return;
+        }
+        try {
+            const entries = await fs.readdir(fullDir, { withFileTypes: true });
+            for (const entry of entries) {
+                const relativePath = path.join(relativeDir, entry.name);
+                if (this.ignoreManager.shouldIgnore(relativePath)) {
+                    continue;
+                }
+                if (entry.isDirectory()) {
+                    await this.scanDir(relativePath, fileList);
+                }
+                else if (entry.isFile()) {
+                    fileList.push(relativePath);
+                }
+            }
+        }
+        catch (error) {
+            console.warn(`Failed to scan directory ${fullDir}:`, error);
+        }
+    }
+}

package/dist/context/types.js

@@ -0,0 +1 @@
+export {};