cto-ai-cli 3.2.0 → 5.0.0

package/DOCS.md

@@ -6,6 +6,9 @@
 
 - [CLI Commands](#cli-commands)
 - [Security Audit](#security-audit---audit)
+- [Context Gateway](#context-gateway)
+- [Learning Mode](#learning-mode)
+- [Code Review](#code-review)
 - [MCP Server](#mcp-server)
 - [API Server](#api-server)
 - [Programmatic API](#programmatic-api)
@@ -99,6 +102,21 @@ npx cto-ai-cli --compare                 # Compare your score vs popular open so
 npx cto-ai-cli --benchmark              # CTO vs naive vs random comparison
 npx cto-ai-cli --json                    # Machine-readable JSON output
 npx cto-ai-cli --help                    # Show all options
+
+# Phase 5 — CI/CD Quality Gate
+npx cto-ai-cli --ci                      # Run quality gate (exits 1 on failure)
+npx cto-ai-cli --ci --threshold 80       # Set minimum score (default: 70)
+npx cto-ai-cli --ci --json               # JSON output for CI pipelines
+
+# Phase 7 — Learning Mode
+npx cto-ai-cli --learn                   # Show feedback model & cross-repo intelligence
+npx cto-ai-cli --feedback                # Alias for --learn
+npx cto-ai-cli --predict                 # Predict relevant files for a task
+npx cto-ai-cli --learn --json            # Export learning data as JSON
+
+# Phase 8 — Code Review
+npx cto-ai-cli --review                  # Smart PR review analysis
+npx cto-ai-cli --review --json           # JSON output for CI
 ```
 
 Flags can be combined: `npx cto-ai-cli --fix --audit --report --compare`
@@ -236,6 +254,385 @@ Based on findings, CTO generates actionable recommendations:
 
 ---
 
+## Context Gateway
+
+A transparent HTTP proxy that sits between your application and any LLM provider. It intercepts every request, scans for secrets, optimizes context, tracks costs, and enforces budgets — all with zero external dependencies.
+
+### Quick start
+
+```bash
+npx cto-gateway                    # Start on port 8787
+npx cto-gateway --port 9000        # Custom port
+npx cto-gateway --block-secrets    # Hard block on critical secrets
+npx cto-gateway --budget-daily 10  # $10/day limit
+```
+
+Then point your app:
+```bash
+export OPENAI_BASE_URL=http://localhost:8787
+```
+
+Every request must include the target provider URL as a header:
+```
+x-cto-target: https://api.openai.com/v1/chat/completions
+```
+
+### Architecture
+
+```
+Your App → Gateway (localhost:8787) → Provider (api.openai.com)
+                │
+                ├── Secret Scanner  → redacts/blocks secrets in messages
+                ├── Context Optimizer → injects CTO-selected context
+                ├── Cost Tracker → logs per-request cost to JSONL
+                ├── Budget Guard → rejects requests over limit (429)
+                └── Dashboard → live web UI at /__cto
+```
+
+### CLI flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--port <n>` | `8787` | Port to listen on |
+| `--host <addr>` | `127.0.0.1` | Host to bind to |
+| `--project <path>` | `.` | Project to analyze for context optimization |
+| `--block-secrets` | off | Hard block requests with critical secrets (403) |
+| `--budget-daily <$>` | unlimited | Max cost per day — returns 429 when exceeded |
+| `--budget-monthly <$>` | unlimited | Max cost per month |
+| `--no-optimize` | on | Disable CTO context injection |
+| `--no-redact` | on | Disable secret redaction |
+| `--no-dashboard` | on | Disable web dashboard |
+
+### Provider detection
+
+The Gateway auto-detects providers from the `x-cto-target` URL and request headers:
+
+| Provider | Detection | Auth header |
+|----------|-----------|-------------|
+| OpenAI | `api.openai.com` or `/v1/chat/completions` | `Authorization: Bearer sk-...` |
+| Anthropic | `api.anthropic.com` or `anthropic-version` header | `x-api-key` |
+| Google AI | `generativelanguage.googleapis.com` | `x-goog-api-key` |
+| Azure OpenAI | `*.openai.azure.com` or `api-key` header | `api-key` |
+| Custom | Fallback — assumes OpenAI-compatible | `Authorization` |
+
+### Model pricing
+
+Built-in pricing for accurate cost tracking:
+
+| Model | Input ($/M tokens) | Output ($/M tokens) | Context window |
+|-------|--------------------|--------------------|----------------|
+| gpt-4o | $2.50 | $10.00 | 128K |
+| gpt-4o-mini | $0.15 | $0.60 | 128K |
+| o1 | $15.00 | $60.00 | 200K |
+| o3-mini | $1.10 | $4.40 | 200K |
+| claude-sonnet-4 | $3.00 | $15.00 | 200K |
+| claude-3.5-haiku | $0.80 | $4.00 | 200K |
+| gemini-2.5-pro | $1.25 | $10.00 | 1M |
+| gemini-2.0-flash | $0.10 | $0.40 | 1M |
+
+### Request lifecycle
+
+1. **Receive** — Client sends POST request to Gateway
+2. **Budget check** — If daily/monthly budget exceeded → 429
+3. **Parse** — Detect provider, extract messages from provider-specific format
+4. **Scan secrets** — Run 30+ patterns against all message content
+5. **Redact or block** — Replace secrets with `***REDACTED***` or return 403
+6. **Optimize context** — If analysis ready, inject CTO-selected files into system prompt
+7. **Forward** — Proxy to provider (streaming SSE or buffered)
+8. **Track** — Log cost, tokens, savings, latency to JSONL
+9. **Respond** — Forward provider response to client (zero-copy for streams)
+
+### Streaming support
+
+The Gateway fully supports Server-Sent Events (SSE) streaming:
+
+- Detects streaming from `Content-Type: text/event-stream`
+- Zero-copy passthrough: chunks are forwarded to client as they arrive
+- Async token tracking: parses SSE events in background without blocking the stream
+- Usage data extracted from final SSE chunk (when provider includes it)
+
+### Dashboard
+
+Available at `http://localhost:8787/__cto` (configurable via `--dashboardPath`).
+
+Shows:
+- **Today**: requests, cost, tokens saved, secrets redacted
+- **This month**: totals + budget progress
+- **Feature status**: optimization, redaction, tracking, audit log
+- **By model**: breakdown of requests, tokens, and cost per model
+- **By provider**: requests and cost per provider
+- Auto-refreshes every 30 seconds
+
+### Usage storage
+
+| File | Format | Description |
+|------|--------|-------------|
+| `.cto/gateway/usage/YYYY-MM.jsonl` | JSON Lines | One line per request. Monthly files. |
+
+Each line:
+```json
+{
+  "id": "a1b2c3d4",
+  "timestamp": "2026-02-24T23:52:00.000Z",
+  "provider": "openai",
+  "model": "gpt-4o",
+  "inputTokens": 1200,
+  "outputTokens": 350,
+  "costUSD": 0.0065,
+  "originalTokens": 6200,
+  "optimizedTokens": 1200,
+  "savedTokens": 5000,
+  "savedUSD": 0.0130,
+  "secretsRedacted": 2,
+  "secretsBlocked": false,
+  "latencyMs": 152,
+  "stream": true
+}
+```
+
+### Budget enforcement
+
+When a budget is set, the Gateway checks cost totals before every request:
+
+| Condition | HTTP response |
+|-----------|---------------|
+| Daily budget exceeded | `429 Too Many Requests` + `{ "error": "Daily budget exceeded", "budget": 10, "current": 10.42 }` |
+| Monthly budget exceeded | `429 Too Many Requests` + `{ "error": "Monthly budget exceeded" }` |
+| Critical secrets + `--block-secrets` | `403 Forbidden` + `{ "error": "Request blocked: secrets detected" }` |
+
+Budget alerts are emitted at 80% of limit (configurable via `alertThreshold`).
+
+### Programmatic API
+
+```typescript
+import { ContextGateway, UsageTracker } from 'cto-ai-cli/gateway';
+
+const gateway = new ContextGateway({
+  port: 8787,
+  projectPath: '/path/to/project',
+  redactSecrets: true,
+  blockOnSecrets: false,
+  budgetDaily: 20,
+  budgetMonthly: 500,
+});
+
+// Listen to events
+gateway.onEvent((event) => {
+  if (event.type === 'request') console.log(`${event.record.model}: $${event.record.costUSD}`);
+  if (event.type === 'budget-alert') console.log(`Budget warning: ${event.period}`);
+});
+
+await gateway.start();
+
+// Get usage summary
+const tracker = gateway.getTracker();
+const summary = tracker.getSummary('month');
+console.log(`This month: ${summary.totalRequests} requests, $${summary.totalCostUSD}`);
+
+// Provider detection (standalone)
+import { detectProvider, estimateCost } from 'cto-ai-cli/gateway';
+
+const provider = detectProvider('https://api.openai.com/v1/chat/completions', {});
+const cost = estimateCost(provider, 'gpt-4o', 5000, 1000);
+```
+
+### Interceptor (standalone)
+
+```typescript
+import { interceptRequest } from 'cto-ai-cli/gateway';
+import type { Message, GatewayConfig } from 'cto-ai-cli/gateway';
+
+const messages: Message[] = [
+  { role: 'user', content: 'Deploy with key sk-live_abc123...' },
+];
+
+const result = await interceptRequest(messages, config, analysis);
+// result.secretsRedacted → 1
+// result.messages[0].content → 'Deploy with key sk-l**********23...'
+// result.decisions → ['Redacted 1 secret(s) in user message: api-key']
+```
+
+---
+
+## Learning Mode
+
+CTO learns from your usage patterns to improve context selection over time. Three engines work together:
+
+### Feedback Engine (`--learn` / `--feedback`)
+
+Tracks which context selections lead to accepted AI output.
+
+```bash
+npx cto-ai-cli --learn                   # Full learning dashboard
+npx cto-ai-cli --learn --json            # Export for team sharing
+```
+
+**v2.0 Features:**
+
+| Feature | Description |
+|---------|-------------|
+| **EWMA Temporal Decay** | Recent feedback weighs more (α=0.15). Old patterns fade naturally. |
+| **Bayesian Confidence (Wilson Score)** | Avoids over-trusting sparse data. 1/1 ≠ 100% confidence. |
+| **Session Tracking** | Groups related feedback for per-session analysis. |
+| **A/B Strategy Comparison** | Compare different context strategies with statistical rigor. |
+| **Team Export/Import** | Share learned models across teams with weighted merge (local 70%, team 30%). |
+
+### Predictor Engine (`--predict`)
+
+Predicts which files are relevant for a task based on historical patterns.
+
+```bash
+npx cto-ai-cli --predict --context "fix auth bug"   # Predict files for a task
+npx cto-ai-cli --predict --json                      # JSON predictions
+```
+
+The predictor uses:
+- **Task type frequency** — which files were selected for similar task types (3× weight)
+- **Keyword frequency** — which files correlate with task keywords (2× weight)
+- **General selection frequency** — files selected in >30% of all observations
+- **Co-selection patterns** — files that tend to be selected together
+
+### Cross-Repo Intelligence
+
+Learns patterns across repositories. Stored in `~/.cto/global-intelligence.json`.
+
+- **Project fingerprinting** — stack, size class, structure pattern
+- **Archetype matching** — "TypeScript medium-size projects with tests"
+- **Universal patterns** — patterns that work across >50% of project types
+
+### Programmatic API
+
+```typescript
+import {
+  recordFeedback,
+  loadFeedbackModel,
+  getFeedbackBoosts,
+  exportFeedbackForTeam,
+  importTeamFeedback,
+  wilsonLowerBound,
+  renderFeedbackReport,
+  renderCrossRepoReport,
+} from 'cto-ai-cli/engine';
+import {
+  recordSelection,
+  predictRelevantFiles,
+  getPredictorBoosts,
+  loadModel,
+  getModelStats,
+} from 'cto-ai-cli/engine';
+import {
+  recordCrossRepoSelection,
+  predictFromCrossRepo,
+  loadGlobalModel,
+  getCrossRepoStats,
+  computeFingerprint,
+} from 'cto-ai-cli/engine';
+
+// Record feedback
+const model = await recordFeedback('/path/to/project', {
+  task: 'fix auth bug',
+  contextHash: 'abc123',
+  filesIncluded: ['src/auth.ts', 'src/types.ts'],
+  tokensUsed: 5000,
+  budget: 50000,
+  outcome: { accepted: true, compilable: true, timeToAcceptMs: 3000 },
+  sessionId: 'sess-1',       // optional: group feedback
+  strategy: 'experimental',  // optional: A/B testing
+});
+
+// Get boosts for context selection
+const boosts = await getFeedbackBoosts('/path/to/project', 'fix auth');
+// Map<string, number> — file path → boost value
+
+// Wilson score for statistical confidence
+const confidence = wilsonLowerBound(8, 10); // 8 successes out of 10
+// ~0.49 — 95% confident the true rate is ≥49%
+
+// Team sharing
+const exported = await exportFeedbackForTeam('/path/to/project', 'my-project');
+const merged = await importTeamFeedback('/other/project', exported);
+
+// Predict relevant files
+const predictions = await predictRelevantFiles('/path', 'fix auth', analysis);
+// { filePath, predictedScore, reasons }[]
+```
+
+### Storage
+
+| File | Scope | Description |
+|------|-------|-------------|
+| `.cto/feedback.json` | Per-project | Raw feedback entries (last 1000) |
+| `.cto/feedback-model.json` | Per-project | Rebuilt model with EWMA, Bayesian, sessions |
+| `.cto/predictor.json` | Per-project | ML predictor model |
+| `~/.cto/global-intelligence.json` | Cross-repo | Global archetype and pattern data |
+
+---
+
+## Code Review
+
+Context-aware PR review intelligence. Analyzes git diffs, detects breaking changes, finds missing files, and generates AI-ready review prompts.
+
+### Usage
+
+```bash
+npx cto-ai-cli --review                  # Full review analysis
+npx cto-ai-cli --review --json           # JSON output for CI
+```
+
+Generates:
+- **Terminal dashboard** — review quality score, breaking changes, missing files, impact radius
+- **`.cto/review-prompt.md`** — AI-ready review prompt with full file contents
+
+### Features
+
+| Feature | Description |
+|---------|-------------|
+| **Diff Parsing** | Parses git diffs into structured DiffHunk[] with additions/deletions |
+| **Breaking Change Detection** | Removed exports, type changes, function signature changes, deleted files with dependents |
+| **Missing File Detection** | Sibling type files, test files, importers of changed exports, barrel index files |
+| **Impact Radius** | BFS on dependency graph: direct dependents, transitive (2-hop), affected tests |
+| **Review Quality Score** | 5-factor weighted score: PR size (25%), focus (20%), breaking changes (25%), completeness (15%), blast radius (15%) |
+| **Review Prompt Generation** | Context-rich prompt with breaking changes, missing files, and file contents for top-risk files |
+
+### Review Quality Score
+
+| Grade | Score | Meaning |
+|-------|-------|---------|
+| A+/A/A- | 85-100 | Small, focused PR with no breaking changes |
+| B+/B/B- | 70-84 | Manageable PR, some issues to review |
+| C+/C/C- | 55-69 | Large or unfocused PR, needs careful review |
+| D+/D/D- | 40-54 | Risky PR with breaking changes or missing files |
+| F | <40 | Very large, unfocused, or highly risky PR |
+
+### Breaking Change Severity
+
+| Severity | Trigger |
+|----------|--------|
+| **Critical** | Deleted file with dependents, removed export with >3 dependents |
+| **High** | Removed export, interface property removed, function signature changed |
+| **Medium** | Export changed with no direct dependents |
+
+### Programmatic API
+
+```typescript
+import { analyzeForReview, renderReviewSummary } from 'cto-ai-cli/engine';
+import type { ReviewResult, ReviewOptions } from 'cto-ai-cli/engine';
+
+const result: ReviewResult = await analyzeForReview(analysis, {
+  baseBranch: 'main',        // default: 'main'
+  depth: 2,                  // dependency expansion depth
+  maxPromptFiles: 20,        // max files in review prompt
+});
+
+console.log(result.breakingChanges);    // BreakingChange[]
+console.log(result.missingFiles);       // MissingFile[]
+console.log(result.impactRadius);       // { directlyAffected, transitivelyAffected, riskScore }
+console.log(result.reviewQuality);      // { score, grade, factors }
+console.log(result.reviewPrompt);       // Full AI-ready review prompt
+```
+
+---
+
 ## MCP Server
 
 CTO exposes 19 tools via the Model Context Protocol.
@@ -478,8 +875,11 @@ src/
 │   ├── multi-model.ts       # Per-model optimization
 │   ├── predictor.ts         # ML-based prediction (learns from usage)
 │   ├── semantic.ts          # Semantic domain analysis
-│   ├── feedback.ts          # Output feedback loop
-│   └── cross-repo.ts        # Cross-repo intelligence
+│   ├── feedback.ts          # Output feedback loop (v2: EWMA, Bayesian, A/B, team)
+│   ├── cross-repo.ts        # Cross-repo intelligence
+│   ├── code-review.ts       # Context-aware PR review engine
+│   ├── monorepo.ts          # Monorepo intelligence
+│   └── quality-gate.ts      # CI/CD quality gate
 ├── interact/            # Interaction Optimization
 │   ├── orchestrator.ts      # Full pipeline
 │   ├── router.ts            # Model routing