@codecora/cli 0.0.3

package/README.md

@@ -0,0 +1,242 @@
+# CORA CLI
+
+> AI-powered code review before you commit.
+
+CORA CLI brings AI code review to your local development workflow. Get instant feedback on your code changes before they leave your machine.
+
+## ✅ Verified & Tested
+
+All CLI features have been tested and verified working:
+
+| Feature | Status | Description |
+|---------|--------|-------------|
+| Authentication | ✅ | `cora auth status` shows user info, session validity, expiration |
+| Code Review | ✅ | Reviews staged/unstaged changes with token usage tracking |
+| Output Formats | ✅ | Pretty (default), JSON, Compact formats |
+| Git Hooks | ✅ | Automatic pre-commit review on every commit |
+| Mock Mode | ✅ | Testing without using API credits |
+| Error Handling | ✅ | Graceful handling of network errors and invalid input |
+
+**Response includes:**
+- Issues with severity (critical, major, minor, info)
+- Token breakdown (input/output/execution time)
+- Quota information
+- AI-generated summaries and suggested fixes
+
+## Features
+
+- **Pre-commit Review** - Review code changes before committing
+- **Instant Feedback** - Get AI analysis in seconds
+- **Privacy-first** - Your code diffs are analyzed directly by your AI provider
+- **Git Hooks** - Automatic review on every commit
+- **Cross-platform** - Works on macOS, Linux, and Windows
+
+## Installation
+
+### Option 1: Using npm/bun (Requires Node.js 20+)
+
+```bash
+# Using npm
+npm install -g @codecora/cli
+
+# Using bun
+bun install -g @cora/cli
+```
+
+### Option 2: Standalone Binary (No Node.js Required)
+
+Download the appropriate binary for your platform from the [releases page](https://github.com/ajianaz/cora/releases):
+
+| Platform | Download |
+|----------|----------|
+| macOS (Intel) | `cora-macos-x64` |
+| macOS (Apple Silicon) | `cora-macos-arm64` |
+| Linux (x64) | `cora-linux-x64` |
+| Windows (x64) | `cora-win-x64.exe` |
+
+```bash
+# Example for macOS
+curl -L https://github.com/ajianaz/cora/releases/latest/download/cora-macos-arm64 -o cora
+chmod +x cora
+sudo mv cora /usr/local/bin/
+```
+
+## Quick Start
+
+```bash
+# 1. Login to CORA
+cora auth login
+
+# 2. Review staged changes
+cora review
+
+# 3. Enable automatic pre-commit review (optional)
+cora enable
+```
+
+## Usage
+
+### Authentication
+
+```bash
+# Login via GitHub OAuth
+cora auth login
+
+# Check authentication status
+cora auth status
+
+# Logout
+cora auth logout
+
+# View/set configuration
+cora auth config [key] [value]
+```
+
+**Important:** For CLI authentication to work, you must add `http://localhost:4200/callback` to your GitHub App's redirect URIs:
+
+1. Go to your GitHub App settings
+2. Navigate to **General** → **Homepage URL**
+3. Add `http://localhost:4200/callback` to the redirect URIs
+
+### Review Code
+
+```bash
+# Review staged changes (default)
+cora review
+
+# Review unstaged changes
+cora review --unstaged
+
+# Review specific files
+cora review --files src/app.ts src/utils.ts
+
+# Mock mode for testing
+cora review --mock
+
+# JSON output for CI/CD
+cora review --format json
+```
+
+### Git Hooks
+
+```bash
+# Install pre-commit hook
+cora hook install
+
+# Uninstall hook
+cora hook uninstall
+
+# List installed hooks
+cora hook list
+
+# Quick enable/disable
+cora enable    # Install pre-commit hook
+cora disable   # Uninstall pre-commit hook
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `-w, --workspace <id>` | Workspace ID |
+| `-r, --repository <name>` | Repository name (owner/repo) |
+| `-b, --branch <name>` | Branch name |
+| `-s, --staged` | Review staged changes (default) |
+| `-u, --unstaged` | Review unstaged changes |
+| `-f, --files <files...>` | Review specific files |
+| `-m, --max-tokens <number>` | Maximum tokens to use |
+| `-i, --include-walkthrough` | Include full walkthrough |
+| `--mock` | Mock mode for testing |
+| `--format <format>` | Output format (pretty, json, compact) |
+
+## Configuration
+
+Configuration is stored in `~/.codecora/`:
+
+- `auth.json` - Session token and user info
+- `config.json` - Preferences and settings
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `CORA_SKIP` | Skip pre-commit hook when set to 1 |
+| `CORA_SERVER` | Override server URL |
+| `CORA_WORKSPACE` | Override workspace ID |
+| `CORA_API_KEY` | API key for CI/CD authentication (see [API Keys Documentation](../../../docs/API_KEYS.md)) |
+
+## CI/CD Integration
+
+### Using API Keys (Recommended)
+
+For CI/CD workflows, use API Keys instead of session tokens:
+
+```yaml
+# Example: GitHub Actions
+- name: Run CORA Review
+  run: |
+    npm install -g @codecora/cli
+    cora review --format json > review-results.json
+  env:
+    CORA_API_KEY: ${{ secrets.CORA_API_KEY }}
+    CORA_SERVER_URL: https://codecora.dev
+```
+
+**Benefits of API Keys:**
+- No interactive login required
+- Can be scoped to specific permissions
+- Can have expiration dates
+- Revocable without affecting other workflows
+
+**Create API Key:** Visit Dashboard → API Keys to generate a key for CI/CD.
+
+See [API Keys Documentation](../../../docs/API_KEYS.md) for complete guide.
+
+## Troubleshooting
+
+### Authentication Errors
+
+```bash
+# Check your authentication status
+cora auth status
+
+# Re-authenticate if needed
+cora auth login
+```
+
+### Hook Not Running
+
+```bash
+# Verify hook is installed
+cora hook list
+
+# Reinstall hook
+cora hook uninstall && cora hook install
+```
+
+### Skip Hook Temporarily
+
+```bash
+# Skip for one commit
+git commit --no-verify -m "message"
+
+# Or use environment variable
+CORA_SKIP=1 git commit -m "message"
+```
+
+## Requirements
+
+- **Node.js 20+** (if installing via npm/bun)
+- **OR** standalone binary (no dependencies)
+- A Codecora account (sign up at https://codecora.dev)
+- An OpenAI-compatible API key configured in your workspace
+
+## License
+
+MIT © [CORA](https://codecora.dev)
+
+## Support
+
+- [Documentation](https://codecora.dev/docs/cli)
+- [GitHub Issues](https://github.com/ajianaz/cora/issues)
+- [GitHub Discussions](https://github.com/ajianaz/cora/discussions)

package/bin/cora.js

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+/**
+ * CORA CLI Entry Point
+ *
+ * Main entry point for the cora command-line tool.
+ */
+
+import { Command } from 'commander';
+import { login, logout, status, config as authConfig } from '../dist/commands/auth.js';
+import { review, autoReview } from '../dist/commands/review.js';
+import { installHook, uninstallHook, listHooks, enable, disable } from '../dist/commands/hook.js';
+import { VERSION } from '../dist/version.js';
+
+const program = new Command();
+
+program
+  .name('cora')
+  .description('CORA - AI-powered code review for git commits')
+  .version(VERSION);
+
+// Auth commands
+const authCmd = program
+  .command('auth')
+  .description('Authentication commands');
+
+authCmd
+  .command('login')
+  .description('Login to CORA via GitHub OAuth')
+  .option('-s, --server <url>', 'Server URL')
+  .action(async (options) => {
+    try {
+      await login(options.server);
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : String(error));
+      process.exit(1);
+    }
+  });
+
+authCmd
+  .command('logout')
+  .description('Logout from CORA')
+  .action(async () => {
+    try {
+      await logout();
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : String(error));
+      process.exit(1);
+    }
+  });
+
+authCmd
+  .command('status')
+  .description('Show authentication status')
+  .action(async () => {
+    try {
+      await status();
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : String(error));
+      process.exit(1);
+    }
+  });
+
+authCmd
+  .command('config')
+  .description('View or set configuration')
+  .argument('[key]', 'Configuration key')
+  .argument('[value]', 'Configuration value')
+  .action(async (key, value) => {
+    try {
+      await authConfig(key, value);
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : String(error));
+      process.exit(1);
+    }
+  });
+
+// Review command
+program
+  .command('review')
+  .description('Review code changes')
+  .option('-w, --workspace <id>', 'Workspace ID')
+  .option('-r, --repository <name>', 'Repository name (owner/repo)')
+  .option('-b, --branch <name>', 'Branch name')
+  .option('-s, --staged', 'Review staged changes (default: true)')
+  .option('-u, --unstaged', 'Review unstaged changes')
+  .option('-f, --files <files...>', 'Review specific files')
+  .option('-m, --max-tokens <number>', 'Maximum tokens to use', parseInt)
+  .option('-i, --include-walkthrough', 'Include full walkthrough')
+  .option('--mock', 'Mock mode for testing')
+  .option('--format <format>', 'Output format (pretty, json, compact)', 'pretty')
+  .action(async (options) => {
+    try {
+      const exitCode = await review({
+        workspace: options.workspace,
+        repository: options.repository,
+        branch: options.branch,
+        staged: options.unstaged ? false : options.staged !== false,
+        files: options.files,
+        maxTokens: options.maxTokens,
+        includeWalkthrough: options.includeWalkthrough,
+        mock: options.mock,
+        format: options.format,
+      });
+      process.exit(exitCode);
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : String(error));
+      process.exit(1);
+    }
+  });
+
+// Hook commands
+const hookCmd = program
+  .command('hook')
+  .description('Git hook management');
+
+hookCmd
+  .command('install')
+  .description('Install git hook for automatic review')
+  .option('-t, --type <type>', 'Hook type (pre-commit, pre-push)', 'pre-commit')
+  .action(async (options) => {
+    try {
+      await installHook(options.type);
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : String(error));
+      process.exit(1);
+    }
+  });
+
+hookCmd
+  .command('uninstall')
+  .description('Uninstall git hook')
+  .option('-t, --type <type>', 'Hook type (pre-commit, pre-push)', 'pre-commit')
+  .action(async (options) => {
+    try {
+      await uninstallHook(options.type);
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : String(error));
+      process.exit(1);
+    }
+  });
+
+hookCmd
+  .command('list')
+  .description('List installed hooks')
+  .action(async () => {
+    try {
+      await listHooks();
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : String(error));
+      process.exit(1);
+    }
+  });
+
+// Enable/disable aliases
+program
+  .command('enable')
+  .description('Enable automatic code review (install pre-commit hook)')
+  .action(async () => {
+    try {
+      await enable();
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : String(error));
+      process.exit(1);
+    }
+  });
+
+program
+  .command('disable')
+  .description('Disable automatic code review (uninstall pre-commit hook)')
+  .action(async () => {
+    try {
+      await disable();
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : String(error));
+      process.exit(1);
+    }
+  });
+
+// Parse arguments
+program.parseAsync(process.argv).catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/dist/api/client.js

@@ -0,0 +1,221 @@
+/**
+ * HTTP Client for CLI → Server communication
+ *
+ * Handles all API calls from CLI to CORA server.
+ * Uses ORPC fetch transport for type-safe API calls.
+ */
+/**
+ * Custom error for API failures
+ */
+export class CLIApiError extends Error {
+    statusCode;
+    responseBody;
+    constructor(message, statusCode, responseBody) {
+        super(message);
+        this.statusCode = statusCode;
+        this.responseBody = responseBody;
+        this.name = 'CLIApiError';
+    }
+}
+/**
+ * API Client for CLI
+ *
+ * Provides type-safe methods to call CORA server endpoints.
+ */
+export class CLIApiClient {
+    config;
+    constructor(config) {
+        this.config = {
+            timeout: 30000, // 30 seconds default
+            ...config,
+        };
+    }
+    /**
+     * Get base URL for API calls
+     */
+    getBaseUrl() {
+        const { serverUrl } = this.config;
+        // Remove trailing slash
+        return serverUrl.replace(/\/$/, '');
+    }
+    /**
+     * Get authorization headers
+     *
+     * Uses X-API-Key header for API key authentication (CI/CD)
+     * Uses Authorization: Bearer header for session token authentication (local CLI)
+     */
+    getAuthHeaders() {
+        const headers = {
+            'Content-Type': 'application/json',
+        };
+        // API Key authentication (CI/CD)
+        if (this.config.apiKey) {
+            headers['X-API-Key'] = this.config.apiKey;
+        }
+        // Session token authentication (local CLI)
+        else if (this.config.sessionToken) {
+            headers['Authorization'] = `Bearer ${this.config.sessionToken}`;
+        }
+        return headers;
+    }
+    /**
+     * Make HTTP request with timeout
+     */
+    async fetch(endpoint, options = {}) {
+        const url = `${this.getBaseUrl()}${endpoint}`;
+        const controller = new AbortController();
+        // Set timeout
+        const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+        try {
+            const response = await fetch(url, {
+                ...options,
+                headers: {
+                    ...this.getAuthHeaders(),
+                    ...options.headers,
+                },
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            // Parse response
+            const contentType = response.headers.get('content-type');
+            let data;
+            if (contentType?.includes('application/json')) {
+                const raw = await response.json();
+                // ORPC wraps response in {"json": {...}}
+                data = raw.json !== undefined ? raw.json : raw;
+            }
+            else {
+                data = await response.text();
+            }
+            // Handle errors
+            if (!response.ok) {
+                throw new CLIApiError(`API request failed: ${response.status} ${response.statusText}`, response.status, data);
+            }
+            return data;
+        }
+        catch (error) {
+            clearTimeout(timeoutId);
+            if (error instanceof CLIApiError) {
+                throw error;
+            }
+            if (error instanceof Error && error.name === 'AbortError') {
+                throw new CLIApiError(`Request timeout after ${this.config.timeout}ms`);
+            }
+            throw new CLIApiError(`Network error: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * POST request helper
+     */
+    post(endpoint, data) {
+        return this.fetch(endpoint, {
+            method: 'POST',
+            body: JSON.stringify(data),
+        });
+    }
+    /**
+     * Authenticate via OAuth code exchange
+     *
+     * Called after user completes OAuth flow in browser.
+     */
+    async auth(request) {
+        return this.post('/rpc/cli/auth', request);
+    }
+    /**
+     * Review code diff
+     *
+     * Main endpoint for code review.
+     * Sends git diff and receives AI analysis results.
+     */
+    async reviewDiff(request) {
+        return this.post('/api/cli/review', request);
+    }
+    /**
+     * Check token quota
+     *
+     * Returns remaining quota for user/workspace.
+     */
+    async checkQuota(workspaceId) {
+        return this.post('/rpc/cli/checkQuota', { workspaceId });
+    }
+    /**
+     * Get CLI configuration
+     *
+     * Returns server capabilities and configuration.
+     */
+    async getConfig() {
+        return this.fetch('/rpc/cli/getConfig', {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+        });
+    }
+    /**
+     * Verify session token
+     *
+     * Checks if current session token is still valid.
+     */
+    async verifySession() {
+        return this.fetch('/rpc/cli/verifySession', {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+        });
+    }
+    /**
+     * Update session token
+     *
+     * Updates the client's session token (for refresh).
+     */
+    setSessionToken(token) {
+        this.config.sessionToken = token;
+    }
+    /**
+     * Get current session token
+     */
+    getSessionToken() {
+        return this.config.sessionToken;
+    }
+    /**
+     * Update server URL
+     */
+    setServerUrl(url) {
+        this.config.serverUrl = url;
+    }
+    /**
+     * Get server URL
+     */
+    getServerUrl() {
+        return this.config.serverUrl;
+    }
+}
+/**
+ * Create API client from local config
+ *
+ * Factory function to create API client with proper authentication.
+ *
+ * Priority:
+ * 1. CORA_API_KEY env var (CI/CD)
+ * 2. Stored session token (local CLI usage)
+ */
+export async function createApiClient() {
+    // 1. Check for API Key (CI/CD)
+    const apiKey = process.env.CORA_API_KEY;
+    if (apiKey) {
+        return new CLIApiClient({
+            serverUrl: process.env.CORA_SERVER_URL || 'https://codecora.dev',
+            apiKey,
+            timeout: 420000, // 7 minutes for review requests
+        });
+    }
+    // 2. Fall back to session token (local CLI usage)
+    const { getLocalConfig } = await import('../config/storage.js');
+    const config = await getLocalConfig();
+    return new CLIApiClient({
+        serverUrl: config.auth?.serverUrl || 'https://codecora.dev',
+        sessionToken: config.auth?.sessionToken,
+        timeout: 420000, // 7 minutes for review requests
+    });
+}

package/dist/api/types.js

@@ -0,0 +1,33 @@
+/**
+ * Shared types between CLI and Server
+ *
+ * This file defines the contract between CLI client and server API.
+ * Both CLI and server must agree on these types for compatibility.
+ */
+/**
+ * Severity levels for code issues
+ */
+export const SEVERITY_LEVELS = ['critical', 'major', 'minor', 'info'];
+/**
+ * Issue type categories
+ */
+export const ISSUE_TYPES = [
+    'potential_issue',
+    'security',
+    'performance',
+    'code_smell',
+    'best_practice',
+    'documentation',
+];
+/**
+ * CLI exit codes
+ */
+export var CLIExitCode;
+(function (CLIExitCode) {
+    CLIExitCode[CLIExitCode["Success"] = 0] = "Success";
+    CLIExitCode[CLIExitCode["GeneralError"] = 1] = "GeneralError";
+    CLIExitCode[CLIExitCode["AuthError"] = 2] = "AuthError";
+    CLIExitCode[CLIExitCode["QuotaExceeded"] = 3] = "QuotaExceeded";
+    CLIExitCode[CLIExitCode["BlockedByIssues"] = 4] = "BlockedByIssues";
+    CLIExitCode[CLIExitCode["NetworkError"] = 5] = "NetworkError";
+})(CLIExitCode || (CLIExitCode = {}));