Metadata-Version: 2.4
Name: spectra-cli
Version: 0.1.1
Summary: Generate production-ready DevOps files for your projects using AI
Home-page: https://github.com/yourusername/spectra-cli
Author: Spectra Team
License-Expression: MIT
Project-URL: Homepage, https://github.com/hamzaparvez-dev/spectra-cli
Project-URL: Documentation, https://github.com/hamzaparvez-dev/spectra-cli#readme
Project-URL: Repository, https://github.com/hamzaparvez-dev/spectra-cli
Project-URL: Issues, https://github.com/hamzaparvez-dev/spectra-cli/issues
Keywords: devops,docker,ci-cd,cli,automation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer[all]>=0.9.0
Requires-Dist: httpx>=0.26.0
Requires-Dist: rich>=13.7.0
Requires-Dist: fastapi>=0.115.0
Requires-Dist: pydantic>=2.9.0
Requires-Dist: uvicorn[standard]>=0.32.0
Requires-Dist: redis>=5.2.0
Requires-Dist: mangum>=0.17.0
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# Spectra CLI

🎯 **Generate production-ready DevOps files for your projects using AI**

Spectra CLI scans your project, identifies the tech stack, and automatically generates production-ready DevOps files including:
- **Dockerfile** - Multi-stage, optimized Docker images
- **docker-compose.yml** - Local development setup
- **GitHub Actions CI/CD** - Automated build and deployment workflows

## Features

- 🔍 **Smart Project Scanning** - Automatically detects your tech stack (Node.js, Python, Java, Go, Rust, PHP, etc.)
- 🤖 **AI-Powered Generation** - Uses Gemini AI to generate production-ready DevOps files
- ⚡ **Lightning Fast** - Instant responses for common stacks via template caching (80% of users)
- 🔄 **Async Processing** - Background job queue for custom stacks with real-time progress
- 🔒 **Production-Ready** - Follows best practices for security and performance
- 🚀 **Zero Configuration** - Works out of the box with sensible defaults

## Installation

### Option 1: Global install (recommended for users)

Install via pipx (isolated global CLI):

```bash
# Install pipx if needed
python3 -m pip install --user pipx && python3 -m pipx ensurepath

# Install the Spectra CLI globally (after PyPI publish)
pipx install spectra-cli

# Use from any project
spectra init
```

If you prefer using pip:

```bash
pip install --user spectra-cli
spectra init
```

### Option 2: Install from Source (Development)

```bash
# Clone the repository
git clone https://github.com/yourusername/spectra-cli.git
cd spectra-cli

# Create a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Install in editable mode
pip install -e .
```

### Option 3: Install via pip (Production)

```bash
pip install spectra-cli
```

## Quick Start

1. **Navigate to your project directory:**
   ```bash
   cd /path/to/your/project
   ```

2. **Run Spectra:**
   ```bash
   spectra init
   ```

3. **That's it!** Spectra will:
   - Scan your project
   - Detect your tech stack
   - Generate Dockerfile, docker-compose.yml, and CI/CD workflows

## Performance

**System Design v2** includes major performance improvements:

- **Template Caching**: Common stacks (Python, Node.js, Go, Rust, Java) get instant responses (<1 second)
- **Async Job Queue**: Custom stacks use background processing with real-time polling
- **No Timeouts**: Architecture solves Vercel timeout issues completely

See [API_V2_DOCS.md](API_V2_DOCS.md) for detailed architecture documentation.

## Configuration

### Environment Variables

**CLI:**
- `SPECTRA_API_URL` - API endpoint URL (default: `https://spectra-cli.vercel.app/`)
  ```bash
  export SPECTRA_API_URL='https://your-api.vercel.app/'
  ```

**API Server (Vercel):**
- `OPENROUTER_API_KEY` - OpenRouter API key (get from https://openrouter.ai/keys - free tier available)
- `UPSTASH_REDIS_URL` - Upstash Redis URL (optional, for production job queue)
- `UPSTASH_REDIS_TOKEN` - Upstash Redis token (optional)

### Command Options

```bash
# Scan a specific directory
spectra init /path/to/project

# Use a custom API URL
spectra init --api-url https://custom-api.example.com/

# Check version
spectra version
```

## Local Development

### Running the API Locally

1. **Install API dependencies:**
   ```bash
   pip install -r api/requirements.txt
   ```

2. **Set OpenRouter API key:**
   ```bash
   export OPENROUTER_API_KEY='your-openrouter-api-key-here'
   ```
   Get your free API key from https://openrouter.ai/keys (no credit card required)

3. **Run the API server:**
   ```bash
   uvicorn api.index:app --host 127.0.0.1 --port 8000
   ```

4. **Test the CLI:**
   ```bash
   export SPECTRA_API_URL='http://127.0.0.1:8000/'
   spectra init
   ```

## Deployment

### Deploy API to Vercel

1. **Install Vercel CLI:**
   ```bash
   npm install -g vercel
   ```

2. **Login to Vercel:**
   ```bash
   vercel login
   ```

3. **Deploy:**
   ```bash
   vercel deploy
   ```

4. **Set environment variables:**
   ```bash
   vercel env add OPENROUTER_API_KEY
   # Paste your OpenRouter API key when prompted
   # Get free key from https://openrouter.ai/keys
   ```

5. **Redeploy to apply changes:**
   ```bash
   vercel --prod
   ```

6. **Update CLI to use production API:**
   ```bash
   export SPECTRA_API_URL='https://your-api.vercel.app/'
   ```

## Project Structure

```
spectra-cli/
├── spectra/              # CLI package
│   ├── __init__.py
│   ├── main.py          # CLI entry point
│   ├── scanner.py       # Project scanner
│   └── client.py        # API client
├── api/                 # Serverless API
│   ├── index.py        # FastAPI app
│   └── requirements.txt
├── requirements.txt     # CLI dependencies
├── pyproject.toml      # Package configuration
├── vercel.json         # Vercel config
└── README.md
```

## Supported Tech Stacks

- **Node.js** - Detected via `package.json`
- **Python** - Detected via `requirements.txt`, `Pipfile`, or `pyproject.toml`
- **Java (Maven)** - Detected via `pom.xml`
- **Java (Gradle)** - Detected via `build.gradle`
- **Go** - Detected via `go.mod`
- **Rust** - Detected via `Cargo.toml`
- **PHP** - Detected via `composer.json`

## Requirements

- Python 3.8 or higher
- OpenRouter API key (for the API server) - Get free key from https://openrouter.ai/keys
- Internet connection (to call the API)
- Upstash Redis (optional, for production job queue)

## Troubleshooting

### CLI can't connect to API

- Check that `SPECTRA_API_URL` is set correctly
- Verify the API server is running (if testing locally)
- Check your network connection

### No files generated

- Ensure your project contains recognizable files (package.json, requirements.txt, etc.)
- Check that the API is responding correctly
- Review API logs for errors

### API errors

- Verify `OPENROUTER_API_KEY` is set correctly on the server
- Get your free API key from https://openrouter.ai/keys (no credit card required)
- Check OpenRouter API status at https://openrouter.ai/status
- For job queue issues, verify `UPSTASH_REDIS_URL` and `UPSTASH_REDIS_TOKEN` are set (optional)
- See [API_V2_DOCS.md](API_V2_DOCS.md) for troubleshooting

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT License - see LICENSE file for details

## Support

For issues and questions:
- Open an issue on GitHub
- Check the documentation
- Review the troubleshooting section

---

Built with ❤️ by the Spectra team

