cto-ai-cli 1.3.0 → 3.0.0

package/DOCS.md

@@ -0,0 +1,351 @@
+# CTO — Full Documentation
+
+> Complete reference for CLI, MCP server, API server, programmatic API, GitHub Action, and configuration.
+
+## Table of Contents
+
+- [CLI Commands](#cli-commands)
+- [MCP Server](#mcp-server)
+- [API Server](#api-server)
+- [Programmatic API](#programmatic-api)
+- [GitHub Action](#github-action)
+- [Configuration](#configuration)
+- [Architecture](#architecture)
+
+---
+
+## CLI Commands
+
+### `cto2 init [path]`
+
+Initialize CTO for a project. Creates `.cto/config.yml` and `.cto/policy.yml`.
+
+```bash
+cto2 init                  # current directory
+cto2 init ./my-project     # specific directory
+```
+
+### `cto2 analyze [path]`
+
+Analyze project structure, dependencies, and risk profile.
+
+```bash
+cto2 analyze               # full analysis
+cto2 analyze --risk-only   # show only risk distribution
+cto2 analyze --graph       # show dependency graph (hubs, clusters, orphans)
+```
+
+### `cto2 interact <task>`
+
+Build optimized AI context for a specific task.
+
+```bash
+cto2 interact "refactor the auth middleware"
+cto2 interact "fix the login bug" --explain       # show selection decisions
+cto2 interact "review this PR" --pr               # PR mode (diff vs main)
+cto2 interact "review this PR" --pr develop       # PR mode (diff vs develop)
+cto2 interact "add tests" --output file           # save to .cto/prompt-{id}.md
+cto2 interact "add tests" --output clipboard      # copy to clipboard
+cto2 interact "add tests" --json                  # JSON output
+```
+
+### `cto2 snapshot`
+
+Reproducible context snapshots.
+
+```bash
+cto2 snapshot create baseline    # save current state
+cto2 snapshot verify baseline    # check for drift
+cto2 snapshot compare a b        # diff two snapshots
+cto2 snapshot list               # list all snapshots
+```
+
+### `cto2 audit`
+
+Tamper-evident audit trail.
+
+```bash
+cto2 audit list     # show audit entries
+cto2 audit verify   # verify integrity
+cto2 audit purge    # remove old entries
+```
+
+### `cto2 policy`
+
+Context selection policies.
+
+```bash
+cto2 policy show
+cto2 policy add no-tests exclude-always --pattern "**/*.test.*" --reason "Skip tests"
+cto2 policy remove no-tests
+cto2 policy toggle no-tests
+cto2 policy validate
+cto2 policy init
+```
+
+---
+
+## MCP Server
+
+CTO exposes 19 tools via the Model Context Protocol.
+
+### Setup
+
+**Windsurf** (`~/.codeium/windsurf/mcp_config.json`):
+```json
+{
+  "mcpServers": {
+    "cto": { "command": "cto2-mcp" }
+  }
+}
+```
+
+**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "cto": {
+      "command": "node",
+      "args": ["/path/to/cto-ai-cli/dist/mcp/v2.js"]
+    }
+  }
+}
+```
+
+### Tools
+
+| Tool | Category | Description |
+|------|----------|-------------|
+| `cto_analyze` | Engine | Full project analysis |
+| `cto_risk_profile` | Engine | Risk factors per file |
+| `cto_select_context` | Engine | Deterministic context selection |
+| `cto_pr_context` | Engine | PR-focused context from git diff |
+| `cto_score` | Engine | Context Score (0-100) |
+| `cto_benchmark` | Engine | CTO vs naive vs random |
+| `cto_quality_benchmark` | Engine | Relevance, completeness, noise metrics |
+| `cto_plan_interaction` | Interact | Full pipeline: analyze → select → prompt → cost |
+| `cto_get_prompt` | Interact | Rendered prompt ready to use |
+| `cto_estimate_cost` | Interact | Cost estimation for a model |
+| `cto_init` | Govern | Initialize .cto/ directory |
+| `cto_scan_secrets` | Govern | Scan for hardcoded secrets |
+| `cto_validate_policy` | Govern | Validate against policy rules |
+| `cto_snapshot_create` | Govern | Create reproducible snapshot |
+| `cto_snapshot_verify` | Govern | Verify snapshot (detect drift) |
+| `cto_snapshot_compare` | Govern | Compare two snapshots |
+| `cto_audit_query` | Govern | Query audit trail |
+| `cto_cache_stats` | Infra | Cache statistics |
+| `cto_watch_status` | Infra | Active file watchers |
+
+### Resources
+
+- `cto://analysis/{projectPath}` — Full analysis as JSON
+
+### Prompts
+
+- `plan-task` — Plan an optimized AI interaction
+- `review-context` — Review what context would be selected
+
+---
+
+## API Server
+
+Start a REST API server for integration with any tool or language.
+
+```bash
+cto2-api                                    # start on port 3141
+PORT=8080 cto2-api                          # custom port
+CTO_API_KEY=your-secret cto2-api            # with auth
+CTO_API_KEY=your-secret RATE_LIMIT=30 cto2-api  # with rate limiting
+```
+
+### Endpoints
+
+| Method | Path | Body | Description |
+|--------|------|------|-------------|
+| `POST` | `/v1/analyze` | `{ "path": "..." }` | Full project analysis |
+| `POST` | `/v1/select` | `{ "path": "...", "task": "...", "budget": 50000 }` | Context selection |
+| `POST` | `/v1/score` | `{ "path": "..." }` | Context Score |
+| `POST` | `/v1/benchmark` | `{ "path": "...", "task": "..." }` | Benchmark comparison |
+| `POST` | `/v1/quality` | `{ "path": "...", "task": "..." }` | Quality benchmark |
+| `POST` | `/v1/pr-context` | `{ "path": "...", "task": "...", "base": "main" }` | PR context |
+| `POST` | `/v1/interact` | `{ "path": "...", "task": "...", "budget": 50000 }` | Full pipeline |
+| `GET` | `/v1/health` | — | Health check |
+| `GET` | `/v1/openapi` | — | OpenAPI 3.1 spec |
+
+### Example
+
+```bash
+# Score a project
+curl -X POST http://localhost:3141/v1/score \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer your-secret' \
+  -d '{"path": "/path/to/project"}'
+
+# Select context for a task
+curl -X POST http://localhost:3141/v1/select \
+  -H 'Content-Type: application/json' \
+  -d '{"path": "/path/to/project", "task": "refactor auth", "budget": 50000}'
+```
+
+### Authentication
+
+Set `CTO_API_KEY` environment variable. All requests must include `Authorization: Bearer <key>`.
+
+If `CTO_API_KEY` is not set, the server runs without auth (development mode).
+
+### Rate Limiting
+
+Default: 60 requests per minute per IP. Configurable via `RATE_LIMIT` env var.
+
+---
+
+## Programmatic API
+
+```typescript
+import { analyzeProject, getCachedAnalysis } from 'cto-ai-cli/engine';
+import { planInteraction } from 'cto-ai-cli/interact';
+import { validateSelection, DEFAULT_POLICY } from 'cto-ai-cli/govern';
+
+// Analyze (cached — instant on repeat calls)
+const analysis = await getCachedAnalysis('/path/to/project');
+
+// Plan an interaction
+const plan = await planInteraction({
+  task: 'refactor the auth middleware',
+  analysis,
+  budget: 50_000,
+});
+
+console.log(plan.context.files);       // Selected files with prune levels
+console.log(plan.model);               // Recommended model + alternatives
+console.log(plan.cost.savings);        // Token & dollar savings
+console.log(plan.prompt.rendered);     // Ready-to-use prompt
+
+// Context Score
+import { computeContextScore } from 'cto-ai-cli/engine';
+const score = await computeContextScore(analysis);
+console.log(score.overall, score.grade); // 87, "A-"
+
+// Benchmark
+import { runBenchmark } from 'cto-ai-cli/engine';
+const benchmark = await runBenchmark(analysis);
+console.log(benchmark.ctoAdvantage);
+
+// Validate against policies
+const validation = validateSelection(plan.context, DEFAULT_POLICY, analysis.files);
+console.log(validation.passed);
+```
+
+---
+
+## GitHub Action
+
+Post Context Score on every PR.
+
+```yaml
+# .github/workflows/cto-score.yml
+name: CTO Context Score
+on: [pull_request]
+
+jobs:
+  score:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - uses: cto-ai/cto-ai-cli@main
+        with:
+          comment-on-pr: 'true'
+          fail-below: '40'
+```
+
+### Inputs
+
+| Input | Default | Description |
+|-------|---------|-------------|
+| `path` | `.` | Project path |
+| `budget` | `50000` | Token budget |
+| `task` | `general code review` | Representative task |
+| `comment-on-pr` | `true` | Post PR comment |
+| `fail-below` | `0` | Fail if score below threshold |
+
+### Outputs
+
+| Output | Description |
+|--------|-------------|
+| `score` | Context Score (0-100) |
+| `grade` | Grade (A+ to F) |
+| `saved-percent` | Token savings % |
+| `monthly-savings` | USD saved per month |
+| `json` | Full results as JSON |
+
+---
+
+## Configuration
+
+CTO uses `.cto/config.yml` in your project root.
+
+```yaml
+version: "2.0"
+tokenMethod: tiktoken    # tiktoken (accurate) | chars4 (fast)
+defaultBudget: 50000     # default token budget
+
+ignoreDirs:
+  - node_modules
+  - .git
+  - dist
+  - build
+  - coverage
+
+extensions:
+  - ts
+  - tsx
+  - js
+  - jsx
+  - py
+  - go
+  - rs
+  - java
+```
+
+---
+
+## Architecture
+
+```
+src/
+├── engine/              # Context Intelligence Engine
+│   ├── analyzer.ts          # Project analysis pipeline
+│   ├── graph.ts             # Dependency graph
+│   ├── risk.ts              # Risk scoring
+│   ├── selector.ts          # Deterministic context selection
+│   ├── score.ts             # Context Score (0-100)
+│   ├── benchmark.ts         # Strategy comparison
+│   ├── compile-proof.ts     # Real tsc compilation test
+│   ├── 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
+├── interact/            # Interaction Optimization
+│   ├── orchestrator.ts      # Full pipeline
+│   ├── router.ts            # Model routing
+│   ├── prompt.ts            # Prompt builder
+│   └── estimator.ts         # Cost estimation
+├── govern/              # Governance & Audit
+│   ├── audit.ts             # Audit trail
+│   ├── secrets.ts           # Secret detection
+│   ├── policy.ts            # Policy engine
+│   ├── snapshot.ts          # Snapshots
+│   └── integrity.ts         # SHA-256 verification
+├── cli/
+│   ├── score.ts             # npx cto-score entry point
+│   └── v2/index.ts          # Full CLI
+├── mcp/v2.ts            # MCP server (19 tools)
+├── api/
+│   ├── server.ts            # REST API server
+│   └── dashboard.ts         # HTML dashboard generator
+└── action/index.ts      # GitHub Action
+```