cto-ai-cli 1.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CTO Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,326 @@
+# 🔧 CTO — Claude Token Optimizer
+
+> Optimize your token usage with Claude Code without modifying your projects.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.4-blue.svg)](https://www.typescriptlang.org)
+
+CTO analyzes your codebase, classifies files into **hot/warm/cold tiers** based on recency and dependency structure, and generates optimized `CLAUDE.md` and `.claudeignore` files — so Claude Code reads only what matters. Includes an **MCP Server** for native Claude Code integration and **enterprise-grade security** with secret detection, audit logging, and data integrity verification.
+
+## ✨ Features
+
+- **🔍 Token Analysis** — Scan your project and estimate token usage per file (chars/4 or tiktoken)
+- **📊 File Tiering** — Classify files as 🔥 hot / 🌡️ warm / ❄️ cold based on recency + AST analysis
+- **🧠 AST Analysis** — Dependency graph, hub file detection, cyclomatic complexity via ts-morph
+- **🎯 Smart Model Routing** — Suggests Opus/Sonnet/Haiku based on file complexity
+- **📝 CLAUDE.md Generation** — Auto-generate context files optimized for Claude Code
+- **🚫 .claudeignore Generation** — Keep cold files out of Claude's context
+- **👁️ Watch Mode** — Auto-recalculate tiers and regenerate artifacts when files change
+- **📝 Session Tracking** — Track Claude Code sessions, log file reads, detect waste patterns
+- **📊 Dashboard** — Terminal dashboard with metrics, savings ratio, and suggestions
+- **📈 Reports** — Weekly reports, project comparison, CSV/JSON export
+- **🔌 MCP Server** — Native Claude Code integration via Model Context Protocol
+- **📋 Prompt Templates** — Pre-built prompts optimized by task type (debug, review, refactor, test)
+- **🔐 Secret Detection** — Scans for API keys, tokens, passwords, connection strings before generating artifacts
+- **📝 Audit Logging** — Immutable, integrity-verified audit trail of every CTO action
+- **🛡️ Data Integrity** — SHA-256 verification of artifacts, backups, and sessions
+- **🪧 CI/CD Validation** — `cto validate` for automated security checks in pipelines
+- **✂️ Smart Context Pruning** — Signatures-only for warm files, skeleton for cold — 60-80% token savings
+- **🔀 Git-Aware Tiering** — Uses `git diff`/blame for precise tier classification, auto-promotes changed files
+- **💰 Cost Estimation** — Real dollar savings per session, weekly/monthly/yearly projections
+- **🎯 Token Budget Optimizer** — Knapsack algorithm selects optimal files within a token budget
+- **🤖 Multi-AI Generator** — Generate context for Claude, Cursor, Copilot, and Gemini
+- **🔀 PR Context** — Focused context for code reviews with dependency-aware file selection
+- **💡 Explain** — Transparent tier reasoning showing all factors per file
+- **🎯 Prompt Engineering** — Enhanced prompts with role priming, chain-of-thought, constraints, and anti-hallucination
+- **🧠 Smart Model Routing** — Auto-select Haiku/Sonnet/Opus based on task complexity
+- **📜 Specification-Driven Development** — Extract specs, generate contract documents, validate implementations
+- **📁 Project-Local Config** — `cto init --local` creates `.cto/` in project root, shareable via git
+- **🔄 Reversible** — Every apply creates a backup; revert anytime
+- **📦 Autocontained** — All CTO data in `~/.config/cto/` or `.cto/` in project root
+- **⚙️ Configurable** — YAML config with global, per-project, and local overrides
+
+## 📦 Installation
+
+```bash
+# From source
+git clone <repo-url>
+cd cto
+npm install
+npm run build
+npm link
+
+# Coming soon: npm i -g @cto/cli
+```
+
+## 🚀 Quick Start
+
+```bash
+# 1. Initialize CTO (interactive wizard)
+cto init
+
+# 2. Analyze your project
+cto analyze /path/to/project
+
+# 3. View file tiers
+cto tiers /path/to/project
+
+# 4. Generate optimized artifacts
+cto generate /path/to/project
+
+# 5. Preview what would change
+cto diff claude-md /path/to/project
+
+# 6. Apply to your project (with confirmation)
+cto apply claude-md /path/to/project
+```
+
+## 📖 Commands
+
+| Command | Description |
+|---------|-------------|
+| `cto init` | Interactive setup wizard |
+| `cto analyze [path]` | Analyze token usage (read-only) |
+| `cto tiers [path]` | Show hot/warm/cold file tiers |
+| `cto generate [path]` | Generate CLAUDE.md & .claudeignore |
+| `cto show <artifact>` | Preview a generated artifact |
+| `cto diff <artifact>` | Show what would change before applying |
+| `cto apply <artifact>` | Apply artifact to project (with backup) |
+| `cto revert [artifact]` | Undo last apply using backup |
+| `cto clean [path]` | Remove all CTO data for a project |
+| `cto prompts [path]` | Show/generate optimized prompt templates |
+| `cto config [path]` | Show current configuration |
+| `cto deps [path]` | Show dependency graph, hub files & complexity |
+| `cto watch [path]` | Watch for changes, auto-recalculate tiers |
+| `cto session start\|end\|current\|list\|log` | Track Claude Code sessions |
+| `cto dashboard [path]` | Terminal dashboard with metrics |
+| `cto report weekly\|project\|export` | Usage reports and data export |
+| `cto doctor [path]` | Health check & security audit |
+| `cto audit log\|verify\|purge` | View and manage audit trail |
+| `cto validate [path]` | CI/CD validation & secret scan |
+| `cto prune preview\|file` | Smart context pruning preview |
+| `cto costs estimate\|history\|pricing` | Token cost estimation & savings |
+| `cto context budget\|pr` | Budget optimizer & PR-focused context |
+| `cto multi-gen generate\|list` | Generate for Claude/Cursor/Copilot/Gemini |
+| `cto explain <file>` | Explain why a file is in a specific tier |
+| `cto route recommend\|tasks` | Smart model routing per task type |
+| `cto multi-gen generate --enhanced` | Prompt-engineered context generation |
+| `cto sdd extract\|spec\|validate` | Specification-Driven Development |
+| `cto init --local` | Create .cto/ in project root (team-shareable) |
+
+**Artifact types:** `claude-md`, `claudeignore`, `all`
+
+## ⚙️ Configuration
+
+CTO uses YAML config files:
+
+- **Global:** `~/.config/cto/config.yaml`
+- **Per-project:** `~/.config/cto/projects/<hash>/config.yaml`
+
+```yaml
+version: "1.3.0"
+model: sonnet              # sonnet | opus | haiku
+tokenEstimation: tiktoken  # tiktoken (accurate) | chars4 (fast)
+
+tiering:
+  hotDays: 3           # Files modified within N days = hot
+  warmDays: 14         # Files modified within N days = warm
+  hotTokenLimit: 50000
+  warmTokenLimit: 200000
+
+ignoreDirs:
+  - node_modules
+  - .git
+  - dist
+  - build
+
+extensions:
+  code:
+    - ts
+    - tsx
+    - js
+    - py
+  config:
+    - json
+    - yaml
+  docs:
+    - md
+```
+
+## 📊 How Tiering Works
+
+| Tier | Criteria | Action |
+|------|----------|--------|
+| 🔥 **Hot** | Modified within 3 days | Read first, always include |
+| 🌡️ **Warm** | Modified within 14 days | Read if needed |
+| ❄️ **Cold** | Not modified in 14+ days | Skip unless explicitly needed |
+
+CTO supports two token estimation methods:
+- **`chars4`** — Fast estimate at ~4 characters per token (default)
+- **`tiktoken`** — Accurate estimation using Claude's real tokenizer
+
+### AST-Enhanced Tiering (v0.5.1+)
+
+Beyond recency, CTO uses AST analysis to boost tier priority:
+- **Hub files** (imported by 3+ files) get promoted one tier (cold→warm, warm→hot)
+- **High-complexity files** (cyclomatic complexity >30) get promoted from warm→hot
+- **Model suggestions**: Opus for complex files, Sonnet for moderate, Haiku for simple
+
+The tier thresholds are fully configurable.
+
+## 🏗️ Architecture
+
+```
+~/.config/cto/
+├── config.yaml                # Global config
+├── audit/                     # Immutable audit logs
+│   └── audit_YYYYMMDD.json   # Daily audit entries (0600 perms)
+└── projects/
+    └── <project-hash>/
+        ├── config.yaml        # Project-specific overrides
+        ├── analysis.json      # Last analysis results
+        ├── integrity.json     # SHA-256 integrity manifest (0600)
+        ├── artifacts/
+        │   ├── CLAUDE.md      # Generated CLAUDE.md (sanitized)
+        │   └── .claudeignore  # Generated .claudeignore
+        ├── backups/
+        │   ├── manifest.json  # Backup tracking
+        │   └── <backup-files> # Original files before apply
+        └── sessions/
+            ├── current.json   # Active session
+            └── session_*.json # Archived sessions
+```
+
+## 🔐 Security
+
+CTO is built with enterprise security requirements in mind.
+
+### Secret Detection
+
+Before generating CLAUDE.md, CTO scans for and redacts:
+- **API keys** — OpenAI, Anthropic, generic API keys
+- **Cloud credentials** — AWS access keys, secret keys
+- **Private keys** — RSA, EC, DSA, OpenSSH
+- **Passwords** — Hardcoded passwords, database passwords
+- **Tokens** — GitHub, GitLab, npm, OAuth, bearer tokens
+- **Connection strings** — PostgreSQL, MongoDB, MySQL, Redis, AMQP
+- **Custom patterns** — Define your own regex patterns in config
+
+### Audit Logging
+
+Every CTO action is logged to an immutable audit trail:
+- Each entry includes: timestamp, user, action, project, and details
+- Entries are **integrity-protected** with SHA-256 hashes
+- Tampering is detected with `cto audit verify`
+- Auto-purge after configurable retention period (default: 90 days)
+
+### Data Integrity
+
+- **SHA-256 hashes** for all artifacts, backups, and sessions
+- `cto validate` verifies integrity on demand (CI/CD ready)
+- Exits with code 1 on failure — use `--strict` to fail on warnings
+
+### Secure File Permissions
+
+- All CTO data files: `0600` (owner read/write only)
+- All CTO directories: `0700` (owner access only)
+- `cto doctor --fix` enforces permissions automatically
+
+### CI/CD Integration
+
+```bash
+# Add to your CI pipeline
+cto validate /path/to/project --strict --json
+
+# Fails on: leaked secrets, corrupted data, stale artifacts
+```
+
+## 🔒 Principles
+
+| Principle | Guarantee |
+|-----------|-----------|
+| 🔒 **Transparent** | Zero files created inside your project unless you explicitly `apply` |
+| 📖 **Read-only by default** | Analysis never modifies anything |
+| 🔄 **Reversible** | Every `apply` creates a backup, every change can be reverted |
+| 📦 **Autocontained** | `~/.config/cto/` is the only location CTO writes to |
+| 🚫 **No secrets leak** | All generated artifacts are sanitized for secrets |
+| 📝 **Auditable** | Every action is logged with tamper-proof integrity hashes |
+| ⚡ **Minimal deps** | No databases, no Docker, no external services |
+| 🎯 **Quality first** | Optimizing tokens ≠ losing context |
+
+## 🧪 Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+
+# Watch mode
+npm run test:watch
+
+# Type check
+npm run typecheck
+```
+
+## 🔌 MCP Server
+
+CTO includes a Model Context Protocol server for native Claude Code integration.
+
+### Setup
+
+Add to your Claude Code MCP config (`~/.claude.json` or project `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "cto": {
+      "command": "cto-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+### Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `cto_analyze_project` | Analyze project token usage and tier breakdown |
+| `cto_get_hot_files` | Get hot-tier files (read these first) |
+| `cto_should_read_file` | Check if a file is hot/warm/cold with recommendation |
+| `cto_get_context` | Get the optimized CLAUDE.md context |
+| `cto_session_log` | Start/end sessions and log file reads |
+| `cto_get_prompt` | Get an optimized prompt template |
+| `cto_dashboard` | Get dashboard metrics (sessions, tokens, savings) |
+
+### MCP Resources
+
+- `cto://context/{projectPath}` — Project context as markdown
+
+### MCP Prompts
+
+- `optimize-task` — Optimized prompt for a task with minimal token usage
+- `review-code` — Optimized prompt for code review
+
+## 🗺️ Roadmap
+
+- [x] **v0.5.0** — TypeScript CLI with full analysis, tiering, generation, apply/revert
+- [x] **v0.5.1** — AST-based analysis (ts-morph), tiktoken integration, dependency graph
+- [x] **v0.5.2** — Watch mode with chokidar, auto-regeneration, tier change notifications
+- [x] **v0.7.x** — Session tracking, terminal dashboard, weekly reports, metrics export
+- [x] **v0.9.x** — MCP Server with 7 tools, resources, and prompt templates
+- [x] **v1.0.0** — Enterprise security: secret detection, audit logging, integrity verification, CI/CD validation
+- [x] **v1.1.0** — Smart context pruning, git-aware tiering, cost estimation in real dollars
+- [x] **v1.2.0** — Token budget optimizer, multi-AI generator, PR context, explain command
+- [x] **v1.3.0** — Smart model routing, prompt engineering, SDD, project-local config
+- [ ] **v1.x+** — Plugin system, GitHub Action, VS Code extension
+
+## 📄 License
+
+[MIT](LICENSE)

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }