@supatest/cli 0.0.2

package/README.md

@@ -0,0 +1,377 @@
+# Supatest AI CLI
+
+> AI-powered test automation for CI/CD - Fix failing tests, analyze logs, and automate debugging with Claude Sonnet 4.5
+
+![Supatest AI Banner](https://img.shields.io/badge/AI-Powered-blue?style=for-the-badge)
+![Node.js](https://img.shields.io/badge/Node.js-18%2B-brightgreen?style=for-the-badge)
+![License](https://img.shields.io/badge/License-ISC-yellow?style=for-the-badge)
+
+## Overview
+
+Supatest AI is a command-line tool that uses Claude's Agent SDK to automatically fix failing tests, debug issues, and perform code-related tasks in your CI/CD pipelines. Simply point it at your logs or describe your issue, and let AI handle the rest.
+
+## Features
+
+- 🤖 **Autonomous AI Agent** - Powered by Claude Sonnet 4.5
+- 🔧 **Auto-Fix Tests** - Analyzes failures and fixes them automatically
+- 📊 **Log Analysis** - Understands error logs and suggests fixes
+- 🚀 **CI/CD Ready** - Perfect for automated pipelines
+- 💻 **File Operations** - Can read, edit, and create files
+- ⚡ **Fast Execution** - Compiled with Bun for speed
+
+## Requirements
+
+Before installing, ensure you have:
+
+- **Node.js 18 or higher** - [Download Node.js](https://nodejs.org/)
+- **Anthropic API Key** - [Get your key](https://console.anthropic.com/)
+
+### Why Node.js?
+
+The Supatest CLI is compiled with Bun for maximum performance, but it uses the Claude Agent SDK which requires Node.js to run the AI agent subprocess. This is similar to how other modern CLI tools (Next.js, Vercel, Turbo) work.
+
+**Verify your Node.js version:**
+```bash
+node --version
+# Should output: v18.0.0 or higher
+```
+
+If you need to install or upgrade Node.js:
+- **macOS**: `brew install node` or download from [nodejs.org](https://nodejs.org/)
+- **Linux**: Use your package manager or [nvm](https://github.com/nvm-sh/nvm)
+- **Windows**: Download installer from [nodejs.org](https://nodejs.org/)
+
+## Installation
+
+### Option 1: npm/pnpm/yarn (Recommended)
+
+Install globally:
+
+```bash
+# npm
+npm install -g @supatest/cli
+
+# pnpm
+pnpm add -g @supatest/cli
+
+# yarn
+yarn global add @supatest/cli
+```
+
+Verify installation:
+```bash
+supatest-ai --version
+```
+
+**Or use npx without installation:**
+
+```bash
+npx @supatest/cli "your task here"
+```
+
+### Option 2: Download Binary
+
+1. **Download the latest release** from the [releases page](#)
+
+2. **Make it executable** (macOS/Linux):
+   ```bash
+   chmod +x supatest-ai
+   ```
+
+3. **Move to your PATH** (optional but recommended):
+   ```bash
+   sudo mv supatest-ai /usr/local/bin/
+   sudo mv claude-code-cli.js /usr/local/bin/
+   ```
+
+4. **Verify installation**:
+   ```bash
+   supatest-ai --version
+   ```
+
+### Option 3: Build from Source
+
+```bash
+# Clone the repository
+git clone https://github.com/your-org/supatest
+cd supatest/cli
+
+# Install dependencies
+pnpm install
+
+# Build with Bun
+pnpm build:bun
+
+# The binary will be in dist/supatest-ai
+./dist/supatest-ai --version
+```
+
+## Configuration
+
+### Set Your Anthropic API Key
+
+You can provide your API key in two ways:
+
+**Option 1: Environment Variable (Recommended)**
+```bash
+export ANTHROPIC_API_KEY="sk-ant-api03-..."
+```
+
+Add this to your `~/.bashrc`, `~/.zshrc`, or `~/.profile` to persist it.
+
+**Option 2: Command-line Flag**
+```bash
+supatest-ai "your task" --api-key="sk-ant-api03-..."
+```
+
+### Optional: Set Default Model
+
+By default, Supatest uses Claude Sonnet 4.5. To use a different model:
+
+```bash
+export ANTHROPIC_MODEL_NAME="claude-haiku-4-5"  # Faster, cheaper
+# or
+export ANTHROPIC_MODEL_NAME="claude-opus-4-5"   # Most capable
+```
+
+## Usage
+
+### Basic Syntax
+
+```bash
+supatest-ai [task] [options]
+```
+
+### Common Examples
+
+#### Fix Failing Tests
+
+```bash
+# Automatically detect and fix test failures
+supatest-ai "run the tests and fix any failures"
+
+# Fix specific test file
+supatest-ai "fix the failing tests in calculator.test.js"
+
+# With verbose logging
+supatest-ai "fix failing tests" --verbose
+```
+
+#### Analyze Log Files
+
+```bash
+# From a log file
+supatest-ai "analyze and fix the errors" --logs error.log
+
+# From stdin (pipe logs)
+npm test 2>&1 | supatest-ai "fix the test failures" --stdin
+
+# CI/CD example
+./run-tests.sh 2>&1 | supatest-ai "analyze failures and suggest fixes" --stdin
+```
+
+#### Code Tasks
+
+```bash
+# Add functionality
+supatest-ai "add error handling to the divide function"
+
+# Refactor code
+supatest-ai "refactor math.js to use modern ES6 syntax"
+
+# Create files
+supatest-ai "create a new test file for the user authentication module"
+
+# Update dependencies
+supatest-ai "update all package imports to use the new package structure"
+```
+
+### Command-line Options
+
+```
+Options:
+  -l, --logs <file>              Path to log file to analyze
+  --stdin                        Read logs from stdin
+  -m, --max-iterations <number>  Maximum number of iterations (default: 100)
+  --api-key <key>               Anthropic API key (or use ANTHROPIC_API_KEY env)
+  --verbose                      Enable verbose logging for debugging
+  -V, --version                  Output the version number
+  -h, --help                     Display help information
+```
+
+## Examples by Use Case
+
+### CI/CD Integration
+
+**GitHub Actions:**
+```yaml
+name: Fix Tests with AI
+on: [push]
+jobs:
+  fix-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+
+      - name: Run tests and fix failures
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        run: |
+          npm test 2>&1 | npx @supatest/cli "fix any test failures" --stdin --verbose
+```
+
+**GitLab CI:**
+```yaml
+fix_tests:
+  image: node:18
+  script:
+    - npm test 2>&1 | npx @supatest/cli "analyze and fix test failures" --stdin
+  variables:
+    ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY
+```
+
+### Local Development
+
+**Quick test fix:**
+```bash
+# Run tests, capture output, and auto-fix
+npm test 2>&1 | tee test.log && supatest-ai "fix failures" --logs test.log
+```
+
+**Debug build errors:**
+```bash
+npm run build 2>&1 | supatest-ai "analyze build errors and fix" --stdin
+```
+
+**Interactive development:**
+```bash
+# Let AI help with your task
+supatest-ai "help me implement pagination for the user list"
+```
+
+## Troubleshooting
+
+### "Node.js 18+ is required"
+
+**Problem:** You see an error about Node.js version.
+
+**Solution:**
+1. Check your version: `node --version`
+2. Install/upgrade Node.js: [nodejs.org](https://nodejs.org/)
+3. Use nvm to manage versions: `nvm install 18`
+
+### "ANTHROPIC_API_KEY environment variable required"
+
+**Problem:** API key not set.
+
+**Solution:**
+```bash
+# Set the environment variable
+export ANTHROPIC_API_KEY="sk-ant-api03-your-key-here"
+
+# Or use the flag
+supatest-ai "task" --api-key="sk-ant-api03-your-key-here"
+```
+
+### "Claude Code process exited with code 1"
+
+**Problem:** The AI agent subprocess failed.
+
+**Solutions:**
+1. Check Node.js is properly installed: `which node`
+2. Verify your API key is valid
+3. Run with `--verbose` to see detailed errors
+4. Ensure you have internet connectivity
+5. Check the task is code-related and actionable
+
+Example verbose run:
+```bash
+supatest-ai "your task" --verbose 2>&1 | tee debug.log
+```
+
+### Task Keeps Running
+
+**Problem:** The agent doesn't stop.
+
+**Solutions:**
+- Use `--max-iterations` to limit turns
+- Make your task more specific
+- Press Ctrl+C to abort
+
+### Files Not Being Modified
+
+**Problem:** Agent doesn't make expected changes.
+
+**Solutions:**
+1. Make your request more specific:
+   - ❌ "fix tests"
+   - ✅ "fix the failing test in calculator.test.js by correcting the divide function"
+
+2. Check file permissions:
+   ```bash
+   ls -la calculator.test.js
+   ```
+
+3. Ensure files exist in the working directory
+
+## Distribution Files
+
+When you build or download Supatest AI, you get:
+
+```
+dist/
+├── supatest-ai           # Main binary (Bun-compiled)
+└── claude-code-cli.js    # Claude Agent SDK CLI (10MB)
+```
+
+**Both files must be distributed together.** The binary needs `claude-code-cli.js` to function.
+
+## System Requirements
+
+- **OS**: macOS, Linux, or Windows (WSL recommended)
+- **Node.js**: 18.0.0 or higher
+- **Memory**: 512MB minimum, 2GB recommended
+- **Disk**: 50MB for binaries
+- **Network**: Internet connection required for API calls
+
+## Development
+
+```bash
+# Run in dev mode
+pnpm dev -- "Your task here"
+
+# Build with TypeScript
+pnpm build
+
+# Build standalone binary
+pnpm build:bun
+
+# Type check
+pnpm type-check
+
+# Clean build artifacts
+pnpm clean:bundle
+```
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/your-org/supatest/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/your-org/supatest/discussions)
+
+## License
+
+ISC License - see LICENSE file for details
+
+## Acknowledgments
+
+Built with:
+- [Claude Agent SDK](https://docs.claude.com/en/docs/agent-sdk/overview) by Anthropic
+- [Bun](https://bun.sh) - Fast JavaScript runtime and bundler
+- [Commander.js](https://github.com/tj/commander.js) - CLI framework
+
+---
+
+**Made with ❤️ for developers who want AI-powered automation**