sphereai-cli 1.0.0

package/README.md

@@ -0,0 +1,529 @@
+# SphereAI CLI
+
+A command-line interface tool for interacting with the SphereAI API.
+
+## Features
+
+- **Key-Based Authentication** - Authenticate using UserChannelKey (recommended)
+- **OAuth2 Authentication** - Secure browser-based authentication flow with local callback server (legacy)
+- **JWT Token Management** - Secure token storage with automatic user info extraction from token payload
+- **File Tracking** - Git-like file tracking system with .sphereignore support
+- **Multiple Output Formats** - JSON and table formats for all commands
+- **Environment Override** - Support for environment variables and command-line options
+- **Offline User Info** - User information extracted from JWT token (no API calls needed)
+
+## Installation
+
+### From npm (Global Installation)
+
+```bash
+npm install -g sphereai-cli
+```
+
+### From Source
+
+```bash
+# Clone the repository
+git clone <repository-url>
+cd SphereAI.CLI
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Link globally for local development
+npm link
+```
+
+## Quick Start
+
+### 1. Configure API URLs
+
+Set the required API URLs using environment variables:
+
+```bash
+# Main API URL (for prompts and other resources)
+export SPHEREAI_API_URL=https://api.develop.sphereai.nava.com.br
+
+# CLI API URL (for key-based authentication)
+export SPHEREAI_CLI_API_URL=https://cli.api.develop.sphereai.nava.com.br
+```
+
+Or create a `.env` file in your project directory:
+
+```bash
+# Main API URL (for prompts and other resources after authentication)
+SPHEREAI_API_URL=https://api.develop.sphereai.nava.com.br
+
+# CLI API URL (for key-based authentication)
+SPHEREAI_CLI_API_URL=https://cli.api.develop.sphereai.nava.com.br
+
+# OAuth2 URL (for legacy OAuth authentication)
+SPHEREAI_AUTH_URL=http://localhost:3000/login?callback=http://localhost:3001/callback
+SPHEREAI_OAUTH_CALLBACK_PORT=3001
+```
+
+### 2. Authentication
+
+#### Option A: UserChannelKey Authentication (Recommended)
+
+Authenticate using your UserChannelKey:
+
+```bash
+sphereai auth login YOUR_USER_CHANNEL_KEY
+```
+
+This will:
+1. Send your key to the CLI API endpoint `https://cli.api.develop.sphereai.nava.com.br/api/v1/Auth`
+2. Receive a JWT token and user information
+3. Save the token securely to `~/.config/sphereai-cli/config.json`
+4. Display user and channel information
+
+Example response:
+```
+✔ Successfully authenticated!
+✓ Logged in as: John Doe
+ℹ Channel: Production Channel
+ℹ Token expires in: 3600 seconds
+ℹ Token expiration: 1/13/2025, 10:00:00 AM
+```
+
+#### Option B: OAuth2 Flow (Legacy)
+
+For legacy OAuth2 authentication:
+
+```bash
+export SPHEREAI_AUTH_URL=https://your-auth-url.com/authorize
+sphereai auth login-oauth
+```
+
+This will:
+1. Open your browser to the authorization page
+2. Start a local callback server on port 3001
+3. Save the token securely to `~/.config/sphereai-cli/config.json`
+
+#### Option C: Manual Token Setting
+
+If you already have a JWT token:
+
+```bash
+sphereai auth set-token YOUR_JWT_TOKEN
+```
+
+### 3. Verify Authentication
+
+```bash
+sphereai auth whoami
+```
+
+This command extracts your user information directly from the JWT token payload (no API call required), displaying:
+- User ID
+- Channel ID
+- Name
+- Channel Name
+- Role
+- Account creation date
+
+## Commands
+
+### Authentication Commands
+
+| Command | Description |
+|---------|-------------|
+| `sphereai auth login <key>` | Authenticate using UserChannelKey (recommended) |
+| `sphereai auth login-oauth` | Authenticate using OAuth2 flow (legacy) |
+| `sphereai auth logout` | Clear stored credentials |
+| `sphereai auth whoami` | Display current user information |
+| `sphereai auth set-token <token>` | Manually set authentication token |
+| `sphereai auth config` | Display current configuration |
+
+#### Authentication Examples
+
+```bash
+# Authenticate with UserChannelKey (recommended)
+sphereai auth login YOUR_USER_CHANNEL_KEY
+
+# OAuth2 login (legacy - requires SPHEREAI_AUTH_URL)
+sphereai auth login-oauth
+
+# Set token manually
+sphereai auth set-token YOUR_JWT_TOKEN
+
+# Check current user
+sphereai auth whoami
+
+# Check current user (with JSON output)
+sphereai auth whoami --output json
+
+# View configuration
+sphereai auth config
+
+# Logout (clear stored token)
+sphereai auth logout
+```
+
+### File Management Commands
+
+| Command | Description |
+|---------|-------------|
+| `sphereai files add [path]` | Add files to tracking (defaults to current directory) |
+| `sphereai files list` | List all tracked files |
+| `sphereai files remove <path>` | Remove a file from tracking |
+| `sphereai files clear` | Clear all tracked files |
+| `sphereai files status` | Show status of tracked files |
+| `sphereai files ignore` | Show .sphereignore patterns |
+
+#### File Management Examples
+
+```bash
+# Add all files from current directory (respects .sphereignore)
+sphereai files add .
+
+# Add a specific file
+sphereai files add src/index.ts
+
+# Add files from a specific directory
+sphereai files add src/
+
+# List tracked files
+sphereai files list
+
+# List tracked files with details
+sphereai files list --verbose
+
+# Show status of tracked files
+sphereai files status
+
+# Remove a file from tracking
+sphereai files remove src/index.ts
+
+# Clear all tracked files (with confirmation)
+sphereai files clear --force
+
+# Show .sphereignore patterns
+sphereai files ignore
+
+# Reload .sphereignore patterns
+sphereai files ignore --reload
+```
+
+#### .sphereignore File
+
+The `.sphereignore` file works similar to `.gitignore`. Create a `.sphereignore` file in your project root to specify patterns for files that should be ignored when adding files to tracking.
+
+**Example .sphereignore:**
+
+```gitignore
+# Dependencies
+node_modules/
+
+# Build outputs
+dist/
+build/
+
+# Environment variables
+.env
+.env.*
+
+# Logs
+*.log
+
+# IDE
+.vscode/
+.idea/
+
+# OS files
+.DS_Store
+```
+
+**Pattern Syntax:**
+
+- Use `#` for comments
+- Directory patterns: `node_modules/`
+- Wildcard patterns: `*.log`, `*.env.*`
+- Exact matches: `.DS_Store`
+
+If no `.sphereignore` file exists, the following default patterns are used:
+
+- `node_modules`, `.git`, `dist`, `build`
+- `.env`, `.env.*`, `*.log`
+- `.DS_Store`, `coverage`, `.vscode`, `.idea`
+
+## Global Options
+
+All commands support these global options:
+
+| Option | Description | Environment Variable |
+|--------|-------------|---------------------|
+| `--token <token>` | Override stored authentication token | `SPHEREAI_TOKEN` |
+| `--output <format>` | Output format: `json` or `table` | - |
+
+## Environment Variables
+
+| Variable | Description | Required | Default |
+|----------|-------------|----------|---------|
+| `SPHEREAI_API_URL` | Main API URL for resources (prompts, etc.) | Yes | - |
+| `SPHEREAI_CLI_API_URL` | CLI API URL for key-based authentication | Yes (for login) | - |
+| `SPHEREAI_TOKEN` | Override stored authentication token | No | - |
+| `SPHEREAI_AUTH_URL` | OAuth2 authorization URL (legacy) | No | - |
+| `SPHEREAI_OAUTH_CALLBACK_PORT` | OAuth2 callback port (legacy) | No | 3001 |
+
+### Examples
+
+```bash
+# Set required environment variables
+export SPHEREAI_API_URL="https://api.develop.sphereai.nava.com.br"
+export SPHEREAI_CLI_API_URL="https://cli.api.develop.sphereai.nava.com.br"
+
+# Use custom token
+sphereai --token YOUR_TOKEN auth whoami
+
+# JSON output
+sphereai auth whoami --output json
+```
+
+## Configuration
+
+### Configuration File
+
+The CLI stores configuration in: `~/.config/sphereai-cli/config.json`
+
+This file contains:
+- JWT authentication token
+- API base URL
+- OAuth2 authorization URL
+- OAuth callback port (default: 3000)
+
+**Note**: User information is extracted from the JWT token payload when needed, so it's always up-to-date with your current token.
+
+### View Configuration
+
+```bash
+sphereai auth config
+```
+
+### Clear Configuration
+
+```bash
+sphereai auth logout
+```
+
+## Output Formats
+
+### Table Format (Default)
+
+Human-readable formatted tables with colors.
+
+```bash
+sphereai auth whoami
+```
+
+### JSON Format
+
+Machine-readable JSON output for scripting and automation.
+
+```bash
+sphereai auth whoami --output json
+```
+
+## Error Handling
+
+The CLI provides clear error messages for common issues:
+
+- **401 Unauthorized**: Authentication required or token expired
+- **403 Forbidden**: Insufficient permissions
+- **404 Not Found**: Resource does not exist
+- **400 Bad Request**: Validation errors with detailed field information
+- **500 Internal Server Error**: Server-side issues
+
+### Debug Mode
+
+Enable debug output for troubleshooting:
+
+```bash
+DEBUG=1 sphereai auth whoami
+```
+
+## Examples
+
+### Complete Authentication Workflow
+
+```bash
+# 1. Set API URLs (in .env file or environment variables)
+export SPHEREAI_API_URL=https://api.develop.sphereai.nava.com.br
+export SPHEREAI_CLI_API_URL=https://cli.api.develop.sphereai.nava.com.br
+
+# 2. Authenticate using UserChannelKey
+sphereai auth login YOUR_USER_CHANNEL_KEY
+
+# 3. Check authentication
+sphereai auth whoami
+
+# 4. View configuration
+sphereai auth config
+
+# 5. Use JSON output
+sphereai auth whoami --output json
+
+# 6. Logout when done
+sphereai auth logout
+```
+
+### Scripting with JSON Output
+
+```bash
+#!/bin/bash
+
+# Get current user info as JSON
+user=$(sphereai auth whoami --output json)
+
+# Parse with jq (requires jq to be installed)
+user_id=$(echo "$user" | jq -r '.id')
+user_email=$(echo "$user" | jq -r '.email')
+user_role=$(echo "$user" | jq -r '.role')
+
+echo "User ID: $user_id"
+echo "Email: $user_email"
+echo "Role: $user_role"
+```
+
+## Development
+
+### Prerequisites
+
+- Node.js >= 14.0.0
+- npm or yarn
+
+### Setup
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Development mode (watch for changes)
+npm run dev
+
+# Link for local testing
+npm link
+```
+
+### Project Structure
+
+```
+src/
+├── commands/                    # CLI command implementations
+│   ├── auth.ts                 # Authentication commands
+│   ├── prompts.ts              # Prompt management commands
+│   └── files.ts                # File tracking commands
+├── services/                    # Core services
+│   ├── api-client.ts           # HTTP client wrapper
+│   ├── cli-api-client.ts       # CLI auth API client
+│   ├── auth-service.ts         # OAuth2 flow handler
+│   ├── config-service.ts       # Configuration management
+│   └── file-tracking-service.ts # File tracking management
+├── types/                       # TypeScript type definitions
+│   └── api-types.ts            # API type definitions
+├── utils/                       # Utility functions
+│   ├── formatters.ts           # Output formatting
+│   ├── errors.ts               # Error handling
+│   └── sphereignore.ts         # .sphereignore parser
+└── index.ts                     # CLI entry point
+```
+
+### Building
+
+```bash
+# Clean build directory
+npm run clean
+
+# Compile TypeScript
+npm run build
+
+# The compiled output will be in the dist/ directory
+```
+
+## Troubleshooting
+
+### Port Already in Use
+
+If OAuth2 callback port (3000) is in use:
+
+```bash
+# The error message will suggest closing other instances
+# Or you can change the port in config (future enhancement)
+```
+
+### Token Expired
+
+```bash
+# Re-authenticate
+sphereai auth login --email user@example.com --password secret
+```
+
+### Authentication Issues
+
+```bash
+# Check current configuration
+sphereai auth config
+
+# Clear all authentication data and reconfigure
+sphereai auth logout
+sphereai auth set-auth-url https://your-auth-url.com/authorize
+sphereai auth login
+```
+
+### Clear Configuration
+
+```bash
+# Logout to clear all stored data
+sphereai auth logout
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run tests and build
+5. Submit a pull request
+
+## License
+
+ISC
+
+## Support
+
+For issues and questions, please refer to your SphereAI system administrator.
+
+## Security
+
+### JWT Token Storage
+The CLI stores JWT tokens in your local configuration file (`~/.config/sphereai-cli/config.json`). The token contains encoded user information that is decoded locally when needed.
+
+### Token Claims
+The JWT token includes the following claims that are used by the CLI:
+- `sub` - User ID
+- `customer_id` - Customer ID
+- `unique_name` - User name
+- `email` - User email
+- `role` - User role (Admin/User)
+- `iat` - Issued at timestamp
+- `exp` - Expiration timestamp
+
+The `whoami` command decodes these claims locally without making API calls, providing instant user information display.
+
+## Changelog
+
+### Version 1.0.0
+- Initial release
+- OAuth2 authentication support with browser-based flow
+- JWT token-based user information (decoded locally)
+- Credential-based authentication
+- Token management (set, view, clear)
+- JSON and table output formats
+- Comprehensive error handling with user-friendly messages

package/dist/commands/auth.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function registerAuthCommands(program: Command): void;
+//# sourceMappingURL=auth.d.ts.map

package/dist/commands/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/commands/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AASpC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAyM3D"}