vmcode-cli 1.0.0

package/INSTALLATION_METHODS.md

@@ -0,0 +1,181 @@
+# vmCode Installation Methods
+
+## Summary
+
+vmCode now supports **two installation methods**:
+
+1. **npm install** - Recommended, easiest
+2. **Git clone + setup script** - For development/contributors
+
+Both methods result in a `vmcode` command you can run from anywhere.
+
+---
+
+## Method 1: npm install (Recommended)
+
+```bash
+npm install -g vmcode-cli
+vmcode
+```
+
+**What happens:**
+- Downloads package from npm
+- Runs `scripts/install.js` post-install
+- Checks for Python 3.9+
+- Installs Python dependencies via pip
+- Creates `config.yaml` from example
+- Sets up global `vmcode` command
+
+**Requirements:**
+- Node.js 14+
+- Python 3.9+
+- pip
+
+**Files used:**
+- `package.json` - npm package definition
+- `bin/npm-wrapper.js` - entry point
+- `scripts/install.js` - post-install script
+- `.npmignore` - controls what's published
+
+---
+
+## Method 2: Git Clone + Setup
+
+```bash
+git clone <repository-url>
+cd vmcode
+./setup.sh          # Linux/macOS
+# or
+setup.bat           # Windows
+```
+
+**What happens:**
+- Checks for Python 3.9+
+- Installs Python dependencies via pip
+- Creates `config.yaml` from example
+- Creates `vmcode` command in `~/.local/bin/` (Linux/macOS) or `%USERPROFILE%\bin` (Windows)
+- Adds to PATH (or shows instructions)
+
+**Requirements:**
+- Python 3.9+
+- pip
+
+**Files used:**
+- `setup.sh` - Linux/macOS setup script
+- `setup.bat` - Windows setup script
+
+---
+
+## How the Git Clone Setup Works
+
+### Linux/macOS (`setup.sh`)
+
+1. Creates `~/.local/bin/vmcode` script
+2. Makes it executable
+3. Checks if `~/.local/bin` is in PATH
+4. If not in PATH, shows instructions to add to `~/.bashrc` or `~/.zshrc`
+
+### Windows (`setup.bat`)
+
+1. Creates `%USERPROFILE%\bin\vmcode.bat` batch file
+2. Checks if `%USERPROFILE%\bin` is in PATH
+3. If not in PATH, shows GUI instructions to add to Environment Variables
+
+---
+
+## Files Summary
+
+### npm Installation
+```
+bin/npm-wrapper.js       # npm entry point (launches Python)
+scripts/install.js       # npm post-install (installs deps)
+package.json            # npm package definition
+.npmignore              # npm package exclusions
+```
+
+### Git Clone Installation
+```
+setup.sh                # Linux/macOS setup
+setup.bat               # Windows setup
+```
+
+### Shared (Both methods)
+```
+config.yaml.example       # Configuration template
+requirements.txt         # Python dependencies
+src/                    # Python application
+.gitignore              # Protects config.yaml
+```
+
+---
+
+## Comparison
+
+| Feature | npm | Git Clone |
+|---------|-----|------------|
+| Easiest | ✅ | ❌ |
+| Auto-deps | ✅ | ✅ |
+| Auto-config | ✅ | ✅ |
+| Auto-command | ✅ | ✅ |
+| No npm required | ❌ | ✅ |
+| For contributors | ❌ | ✅ |
+| Published to registry | ✅ | ❌ |
+
+---
+
+## Choosing a Method
+
+**Use npm if:**
+- You want the easiest installation
+- You don't need to modify the code
+- You're an end user
+
+**Use git clone if:**
+- You want to contribute
+- You need to modify the code
+- You don't have npm installed
+- You're developing vmCode
+
+---
+
+## Troubleshooting
+
+### "vmcode: command not found" (npm)
+```bash
+# Check npm global location
+npm config get prefix
+
+# Add to PATH (example for Linux/macOS)
+export PATH="$(npm config get prefix)/bin:$PATH"
+```
+
+### "vmcode: command not found" (git clone)
+```bash
+# For Linux/macOS
+export PATH="$HOME/.local/bin:$PATH"
+# Then reload shell
+source ~/.bashrc  # or ~/.zshrc
+```
+
+### "Python not found"
+- Install Python 3.9+ from https://python.org
+- Make sure it's in your PATH
+
+---
+
+## Uninstallation
+
+### npm
+```bash
+npm uninstall -g vmcode-cli
+```
+
+### Git Clone
+```bash
+# Remove the command
+rm ~/.local/bin/vmcode        # Linux/macOS
+rm %USERPROFILE%\bin\vmcode.bat  # Windows
+
+# Remove the project
+rm -rf vmcode
+```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Vincent Miranda
+
+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,199 @@
+## vmCode
+
+A CLI-based AI coding assistant capable of codebase search, file editing, computer use, and web search.
+
+<img width="1850" height="396" alt="image" src="https://github.com/user-attachments/assets/4f20cc22-a7d9-4423-afbf-15bbe1e29890" />
+
+## Features
+
+- **Multiple LLM Provider Support**: OpenAI, Anthropic, OpenRouter, GLM, Gemini, Kimi, MiniMax, and local models
+- **Tool-Based Interaction**: Code search (`rg`), file editing, directory operations, and web search
+- **Multiple Modes**: Edit (full access), Plan (read-only), and Learn (documentation style)
+- **Parallel Execution**: Run multiple tools concurrently for efficiency
+- **Conversation History**: Markdown logging with context compaction
+- **Approval Workflows**: Safety checks for dangerous commands
+
+## vmCode Free Tier
+
+The `vmcode_free` provider is included as a convenient default option for new users. It uses free LLM models with **no API key required**.
+
+### How It Works
+
+When using `vmcode_free`, your conversations are routed through vmCode's proxy server to access free LLM models:
+
+- All chat messages, code snippets, and file content are sent to the proxy
+- The proxy forwards requests to the underlying LLM provider
+- This enables free access without requiring individual API keys
+
+### Use Cases
+
+- **Quick testing** - Try vmCode immediately without configuration
+- **Evaluation** - Test the tool before committing to a paid provider
+- **Development** - Non-sensitive work where convenience is preferred
+
+### Recommended Setup
+
+For production work or sensitive code, we recommend using other providers. Type `/provider` to see all options
+
+## Installation
+
+### Option 1: npm install (Recommended)
+
+```bash
+# Install globally (requires Python 3.9+)
+npm install -g vmcode-cli
+
+# Run vmcode
+vmcode
+```
+
+Or use npx without installing:
+
+```bash
+npx vmcode-cli
+```
+
+### What Gets Installed
+
+The npm package automatically:
+1. Checks for Python 3.9+ on your system
+2. Installs Python dependencies via pip
+3. Creates `config.yaml` from `config.yaml.example` if missing
+4. Sets up the `vmcode` command globally
+
+**Requirements:**
+- Node.js 14+ (for npm)
+- Python 3.9+ (for the application)
+- pip (to install Python dependencies)
+
+If Python is not found, the installer will guide you through installing it.
+
+### Option 2: Git Clone
+
+```bash
+# Clone the repository
+git clone <repository-url>
+cd vmcode
+
+# Run setup script
+./setup.sh          # Linux/macOS
+# or
+setup.bat           # Windows
+```
+
+The setup script automatically:
+1. Checks for Python 3.9+ on your system
+2. Installs Python dependencies via pip
+3. Creates `config.yaml` from `config.yaml.example` if missing
+4. Sets up the `vmcode` command alias
+
+**Requirements:**
+- Python 3.9+
+- pip (to install Python dependencies)
+
+## Configuration
+
+### Setting API Keys
+
+You have three options to set your API keys:
+
+#### Option 1: Interactive Commands (Recommended)
+
+Run the app and use the built-in commands:
+```
+> /key sk-your-api-key-here
+> /provider openai
+```
+
+#### Option 2: Edit config.yaml Directly
+
+Edit `config.yaml` in the project root and add your keys:
+
+```yaml
+# OpenAI
+OPENAI_API_KEY: "sk-your-key-here"
+OPENAI_MODEL: gpt-4o-mini
+
+# Anthropic (Claude)
+ANTHROPIC_API_KEY: "sk-ant-your-key-here"
+ANTHROPIC_MODEL: claude-3-5-sonnet-20241022
+
+# Or any other supported provider...
+```
+
+**Note:** `config.yaml` is automatically created from `config.yaml.example` on first run and is in `.gitignore` to protect your secrets.
+
+#### Option 3: Environment Variables
+
+Set environment variables (they take precedence over config.yaml):
+
+```bash
+export OPENAI_API_KEY="sk-your-key-here"
+export ANTHROPIC_API_KEY="sk-ant-your-key-here"
+
+vmcode
+```
+
+### Available Environment Variables
+
+- `ANTHROPIC_API_KEY` - Anthropic (Claude) API key
+- `OPENAI_API_KEY` - OpenAI API key
+- `GLM_API_KEY` - GLM (Zhipu AI) API key
+- `GEMINI_API_KEY` - Google Gemini API key
+- `OPENROUTER_API_KEY` - OpenRouter API key
+- `KIMI_API_KEY` - Kimi (Moonshot AI) API key
+- `MINIMAX_API_KEY` - MiniMax API key
+
+## Commands
+
+- `/provider <name>` - Switch LLM provider
+- `/model <name>` - Set model for current provider
+- `/key <api_key>` - Set API key for current provider
+- `/mode <edit|plan|learn>` - Switch interaction mode
+- `/config` - Show all configuration settings
+- `/help` - Display all available commands
+
+/help Menu:
+<img width="1843" height="1349" alt="image" src="https://github.com/user-attachments/assets/631ab805-f012-4bb6-a031-c82a339e94c5" />
+
+
+## Project Structure
+
+```
+vmcode/
+├── bin/
+│   └── npm-wrapper.js  # npm entry point
+├── scripts/
+│   └── install.js      # npm post-install script
+├── config.yaml         # Your API keys and settings (not in git)
+├── requirements.txt    # Python dependencies
+├── package.json        # npm package definition
+├── setup.sh            # Git clone setup script (Linux/macOS)
+├── setup.bat           # Git clone setup script (Windows)
+├── .npmignore          # npm package exclusions
+├── .gitignore          # git exclusions
+├── src/
+│   ├── core/           # Core orchestration and state management
+│   ├── llm/            # LLM client and provider configurations
+│   ├── ui/             # CLI interface and commands
+│   └── utils/          # Utilities (file ops, search, validation)
+└── tests/              # Test suite (for development)
+```
+
+## Security
+
+- `config.yaml` is excluded from git via `.gitignore`
+- Never commit API keys or sensitive configuration
+- Use environment variables for CI/CD or shared environments
+
+## Development
+
+vmCode is currently in active development. Production readiness is in progress with focus on:
+- Comprehensive test coverage
+- Documentation
+- Error handling improvements
+<<<<<<< HEAD
+- Performance optimizationsour License Here]
+=======
+- Performance optimizations
+>>>>>>> df3957ea1d8e3da51ed06e8960637514281db96d

package/bin/npm-wrapper.js

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+/**
+ * vmCode - npm wrapper for Python application
+ * This script launches the Python vmcode application
+ */
+
+const { spawn } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+// Get the package directory
+const packageDir = __dirname;
+const pythonScript = path.join(packageDir, 'src', 'ui', 'main.py');
+
+function findPython() {
+  const possibleCommands = ['python3', 'python', 'python3.9', 'python3.10', 'python3.11', 'python3.12'];
+  
+  for (const cmd of possibleCommands) {
+    try {
+      const result = spawnSync(cmd, ['--version'], { stdio: 'ignore' });
+      if (result.status === 0) {
+        return cmd;
+      }
+    } catch (e) {
+      // Continue to next command
+    }
+  }
+  
+  return null;
+}
+
+function spawnSync(command, args, options) {
+  const { spawnSync: sync } = require('child_process');
+  return sync(command, args, options);
+}
+
+function checkPythonDependencies(pythonCmd) {
+  // Check if requirements are installed
+  const requirementsFile = path.join(packageDir, 'requirements.txt');
+  
+  if (!fs.existsSync(requirementsFile)) {
+    return true; // No requirements file, assume OK
+  }
+  
+  try {
+    // Try importing a key module to check if dependencies are installed
+    const result = spawnSync(pythonCmd, ['-c', 'import rich, requests, yaml'], {
+      stdio: 'ignore',
+      cwd: packageDir
+    });
+    
+    return result.status === 0;
+  } catch (e) {
+    return false;
+  }
+}
+
+function installPythonDependencies(pythonCmd) {
+  console.log('Installing Python dependencies...');
+  const requirementsFile = path.join(packageDir, 'requirements.txt');
+  
+  const installProcess = spawn(pythonCmd, ['-m', 'pip', 'install', '-r', requirementsFile], {
+    stdio: 'inherit',
+    cwd: packageDir
+  });
+  
+  return new Promise((resolve, reject) => {
+    installProcess.on('close', (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        reject(new Error(`Failed to install Python dependencies (exit code ${code})`));
+      }
+    });
+  });
+}
+
+function showSetupMessage() {
+  console.log('\n' + '='.repeat(60));
+  console.log('vmCode - Terminal-based AI coding assistant');
+  console.log('='.repeat(60));
+  console.log('\nFirst-time setup needed!\n');
+  console.log('1. Python is required (3.9 or later)');
+  console.log('2. Python dependencies need to be installed\n');
+  console.log('To complete setup, run:');
+  console.log('  npm run install\n');
+  console.log('Or manually:');
+  console.log('  python3 -m pip install -r requirements.txt\n');
+  console.log('Then run vmcode again.\n');
+}
+
+function checkConfig() {
+  const configFile = path.join(packageDir, 'config.yaml');
+  const configExample = path.join(packageDir, 'config.yaml.example');
+  
+  if (!fs.existsSync(configFile)) {
+    if (fs.existsSync(configExample)) {
+      console.log('\n⚠️  No config.yaml found!');
+      console.log('Creating from config.yaml.example...\n');
+      
+      try {
+        fs.copyFileSync(configExample, configFile);
+        console.log('✓ config.yaml created');
+        console.log('\nIMPORTANT: Edit config.yaml and add your API keys!');
+        console.log('Or set them via environment variables:');
+        console.log('  export OPENAI_API_KEY="sk-your-key-here"\n');
+      } catch (e) {
+        console.log('Failed to create config.yaml:', e.message);
+      }
+    }
+  }
+}
+
+async function main() {
+  // Find Python executable
+  const pythonCmd = findPython();
+  
+  if (!pythonCmd) {
+    console.error('\n❌ Error: Python 3.9+ is not installed or not in PATH');
+    console.error('Please install Python from https://python.org\n');
+    process.exit(1);
+  }
+  
+  console.log(`✓ Using Python: ${pythonCmd}`);
+  
+  // Check and install Python dependencies
+  if (!checkPythonDependencies(pythonCmd)) {
+    console.log('\n⚠️  Python dependencies not installed');
+    try {
+      await installPythonDependencies(pythonCmd);
+      console.log('✓ Python dependencies installed\n');
+    } catch (e) {
+      console.error('\n❌ Failed to install dependencies:', e.message);
+      console.error('Try running: npm run install\n');
+      process.exit(1);
+    }
+  }
+  
+  // Check/create config
+  checkConfig();
+  
+  // Run the Python application
+  const pythonProcess = spawn(pythonCmd, [pythonScript], {
+    stdio: 'inherit',
+    cwd: packageDir
+  });
+  
+  pythonProcess.on('close', (code) => {
+    process.exit(code || 0);
+  });
+  
+  pythonProcess.on('error', (err) => {
+    console.error('\n❌ Failed to start vmcode:', err.message);
+    process.exit(1);
+  });
+  
+  // Forward signals
+  process.on('SIGINT', () => {
+    pythonProcess.kill('SIGINT');
+  });
+  
+  process.on('SIGTERM', () => {
+    pythonProcess.kill('SIGTERM');
+  });
+}
+
+// Run main function
+main().catch(err => {
+  console.error('\n❌ Unexpected error:', err);
+  process.exit(1);
+});