@compass-ai/nova 1.0.8

package/README.md

@@ -0,0 +1,243 @@
+# Nova CLI
+
+> AI-Powered Development Assistant for Your Terminal by Compass Agentic Platform
+
+[![npm version](https://img.shields.io/npm/v/@compass-ai/nova.svg)](https://www.npmjs.com/package/@compass-ai/nova)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)
+[![TypeScript](https://img.shields.io/badge/typescript-5.5-blue)](https://www.typescriptlang.org/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+Nova brings the power of advanced AI language models directly to your terminal. Write code, debug issues, refactor projects, and understand complex codebases using natural language - all without leaving your command line.
+
+## Why Nova?
+
+- **💬 Natural Conversations** - Describe what you want in plain English, Nova handles the implementation
+- **🔍 Deep Code Understanding** - Intelligent indexing and semantic search across your entire codebase
+- **🔒 Safe by Default** - Three-tier approval system ensures you're always in control of file changes
+- **⚡ Blazingly Fast** - Stream responses in real-time with state-of-the-art language models
+- **🛠️ Built for Developers** - Git integration, shell execution, session management, and more
+
+## Quick Start
+
+### Install
+
+```bash
+npm install -g @compass-ai/nova
+```
+
+### Setup
+
+```bash
+nova setup
+```
+
+You'll be guided through API key configuration and consent management.
+
+### Start Using Nova
+
+```bash
+# In any project directory
+nova
+
+# Then ask Nova to help with anything:
+❯ Help me refactor this authentication module to use JWT
+❯ Find all the files that handle user permissions
+❯ Create a git commit with a descriptive message for my changes
+❯ Explain how the payment processing flow works
+```
+
+## Key Features
+
+### AI-Powered Development
+Nova leverages advanced language models to provide intelligent assistance for:
+- Writing and refactoring code
+- Debugging and fixing issues
+- Explaining complex codebases
+- Generating documentation
+- Creating git commits and PRs
+
+### Smart Codebase Understanding
+- **File Indexing** - Automatically indexes your project structure
+- **Semantic Search** - Find relevant code using natural language
+- **Dependency Analysis** - Understand relationships between files and modules
+- **Context-Aware** - Nova maintains conversation history with 200K token context window
+
+### Safe File Operations
+- **Manual Mode** (Default) - Review every change before it's applied
+- **Auto Mode** - Safe operations approved automatically, risky ones require review
+- **Strict Mode** - Maximum safety, all operations require explicit approval
+- **Automatic Backups** - Changes are backed up before modification
+- **Undo Support** - Roll back changes with `/undo`
+
+### Developer Workflow Integration
+- **Git Operations** - Intelligent commits, PR descriptions, conflict resolution
+- **Shell Execution** - Run commands with cross-platform support
+- **Session Management** - Save, load, and export conversation history
+- **Token Tracking** - Monitor usage and costs in real-time
+
+## Common Use Cases
+
+```bash
+# Code refactoring
+❯ Refactor the user service to follow SOLID principles
+
+# Debugging
+❯ I'm getting a null pointer error in checkout.ts line 45, help me fix it
+
+# Code understanding
+❯ Explain how the authentication flow works in this codebase
+
+# Documentation
+❯ Generate JSDoc comments for all functions in src/utils/
+
+# Git operations
+❯ Create a commit for my changes with a descriptive message
+❯ Help me write a PR description for this feature
+
+# Testing
+❯ Write unit tests for the payment processing module
+```
+
+## Interactive Commands
+
+During a session, use these slash commands:
+
+| Command | Description |
+|---------|-------------|
+| `/help` | Show available commands |
+| `/model [name]` | Switch between sonnet, opus, haiku |
+| `/approve [mode]` | Toggle approval modes |
+| `/save [name]` | Save current session |
+| `/load [name]` | Load a saved session |
+| `/tokens` | View token usage stats |
+| `/undo` | Undo last file operation |
+| `/clear` | Clear conversation history |
+| `/exit` | Exit Nova |
+
+## Custom Slash Commands
+
+Define your own slash commands as Markdown files for frequently used prompts.
+
+### Creating Commands
+
+**Project commands** (shared with team):
+```bash
+mkdir -p .compass/commands
+echo "Analyze this code for performance issues:" > .compass/commands/optimize.md
+```
+
+**Personal commands** (available everywhere):
+```bash
+mkdir -p ~/.compass/commands
+echo "Review this code for security issues:" > ~/.compass/commands/security.md
+```
+
+### Features
+
+- **Arguments**: Use `$ARGUMENTS` for all args, or `$1`, `$2` for positional
+- **File references**: Include files with `@src/file.ts`
+- **Bash execution**: Run commands with `!`git status``
+- **Frontmatter**: Configure with YAML metadata
+
+### Example Command
+
+```markdown
+---
+allowed-tools: Bash(git:*)
+argument-hint: [issue-number]
+description: Fix a GitHub issue
+---
+
+## Context
+- Current branch: !`git branch --show-current`
+- Recent commits: !`git log --oneline -5`
+
+## Task
+Fix issue #$1 following our coding standards.
+```
+
+Usage: `/fix-issue 123`
+
+See [Custom Commands Documentation](docs/custom-commands.md) for full details.
+
+## Configuration
+
+Nova uses a hierarchical configuration system:
+
+1. **Default values** - Sensible built-in defaults
+2. **Global config** - `~/.compass/config.json`
+3. **Project config** - `./.compass/config.json`
+4. **Environment variables** - Override any setting
+
+### Environment Variables
+
+```bash
+ANTHROPIC_API_KEY=your_api_key_here  # When using Anthropic models
+COMPASS_MODEL=sonnet                  # Model configuration
+COMPASS_DEBUG=true                    # Enable debug logging
+NO_COLOR=1                            # Disable colored output
+```
+
+## Privacy & Security
+
+Nova is designed with privacy and security as core principles:
+
+- **Local-First** - All data stored on your machine
+- **Explicit Consent** - Required before any data collection
+- **GDPR Compliant** - Full data export and deletion capabilities
+- **Encrypted Credentials** - API keys stored securely
+- **Automatic Expiration** - Session data expires after 30 days
+
+## AI Model Support
+
+Nova supports multiple AI model providers and configurations. The default setup includes support for state-of-the-art language models with:
+- Large context windows (up to 200K tokens)
+- Streaming responses for real-time feedback
+- Advanced reasoning capabilities
+- Vision and tool use support
+
+## Requirements
+
+- Node.js >= 18.0.0
+- API key for your chosen AI provider (e.g., [Anthropic](https://console.anthropic.com/))
+
+## Troubleshooting
+
+### API Key Issues
+```bash
+# Reconfigure your API key
+nova setup
+```
+
+### Reset to Defaults
+```bash
+nova reset --force
+```
+
+### Enable Debug Mode
+```bash
+COMPASS_DEBUG=true nova
+```
+
+## Contributing
+
+Contributions are welcome! Please read our contributing guidelines before submitting pull requests.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Links
+
+- [npm Package](https://www.npmjs.com/package/@compass-ai/nova)
+- [Report Issues](https://github.com/your-org/nova/issues)
+- [Documentation](docs/README.md)
+- [Compass Official](https://compassap.ai/)
+
+---
+
+**Ready to supercharge your development workflow?** Install Nova and start building with AI assistance today.
+
+```bash
+npm install -g @compass-ai/nova && nova setup
+```