@corbat-tech/coco 1.2.3 โ†’ 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,150 +1,181 @@
1
- <p align="center">
2
- <img src="https://img.shields.io/badge/v1.2.3-stable-blueviolet?style=for-the-badge" alt="Version">
3
- <img src="https://img.shields.io/badge/TypeScript-5.7-3178c6?style=for-the-badge&logo=typescript&logoColor=white" alt="TypeScript">
4
- <img src="https://img.shields.io/badge/Node.js-22+-339933?style=for-the-badge&logo=nodedotjs&logoColor=white" alt="Node.js">
5
- <img src="https://img.shields.io/badge/License-MIT-f5c542?style=for-the-badge" alt="MIT License">
6
- <img src="https://img.shields.io/badge/Tests-4350%2B_passing-22c55e?style=for-the-badge" alt="Tests">
7
- </p>
1
+ <div align="center">
8
2
 
9
- <h1 align="center">๐Ÿฅฅ Corbat-Coco</h1>
3
+ # ๐Ÿฅฅ Coco
10
4
 
11
- <p align="center">
12
- <strong>The open-source coding agent that iterates on your code until it's actually production-ready.</strong>
13
- </p>
5
+ **The AI coding agent that actually delivers production-ready code**
14
6
 
15
- <p align="center">
16
- <em>Generate โ†’ Test โ†’ Measure โ†’ Fix โ†’ Repeat โ€” autonomously.</em>
17
- </p>
7
+ [Features](#-features) โ€ข
8
+ [Quick Start](#-quick-start) โ€ข
9
+ [How It Works](#-how-it-works) โ€ข
10
+ [Commands](#-commands) โ€ข
11
+ [Documentation](#-documentation)
12
+
13
+ [![NPM Version](https://img.shields.io/npm/v/@corbat-tech/coco?style=flat-square&color=blueviolet)](https://www.npmjs.com/package/@corbat-tech/coco)
14
+ [![License](https://img.shields.io/badge/license-MIT-f5c542?style=flat-square)](LICENSE)
15
+ [![TypeScript](https://img.shields.io/badge/TypeScript-5.7-3178c6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
16
+ [![Node](https://img.shields.io/badge/Node.js-22+-339933?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
17
+ [![Tests](https://img.shields.io/badge/tests-4350%2B-22c55e?style=flat-square)](https://github.com/corbat/corbat-coco/actions)
18
+
19
+ </div>
18
20
 
19
21
  ---
20
22
 
21
- ## Why Coco?
23
+ ## The Problem
24
+
25
+ Most AI coding tools generate code and walk away. If tests fail, types don't match, or security issues creep in โ€” **that's on you**.
22
26
 
23
- Most AI coding tools generate code and hand it to you. If something breaks โ€” tests fail, types don't match, a security issue slips in โ€” that's your problem.
27
+ ## The Solution
24
28
 
25
- Coco takes a different approach. After generating code, it **runs your tests, measures quality across 12 dimensions, diagnoses what's wrong, and fixes it** โ€” in a loop, autonomously โ€” until the code actually meets a quality bar you define.
29
+ **Coco doesn't just generate code. It iterates until it's right.**
30
+
31
+ After writing code, Coco automatically:
32
+ - โœ… Runs your tests
33
+ - ๐Ÿ“Š Measures quality across 12 dimensions
34
+ - ๐Ÿ” Diagnoses what's wrong
35
+ - ๐Ÿ”ง Fixes issues and repeats
36
+
37
+ **Until your code hits production-quality standards you define.**
26
38
 
27
39
  ```
28
- โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
29
- โ”‚ Generate โ”‚ โ”€โ”€โ–บ โ”‚ Test โ”‚ โ”€โ”€โ–บ โ”‚ Measure โ”‚ โ”€โ”€โ–บ โ”‚ Fix โ”‚
30
- โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
31
- โ”‚
32
- Score < 85? โ”‚ โ”€โ”€โ–บ Loop back
33
- Score โ‰ฅ 85? โ”‚ โ”€โ”€โ–บ Done โœ…
40
+ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
41
+ โ”‚ Generate โ”‚ โ”€โ”€โ–บ โ”‚ Test โ”‚ โ”€โ”€โ–บ โ”‚ Measure โ”‚ โ”€โ”€โ–บ โ”‚ Fix โ”‚
42
+ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
43
+ โ”‚
44
+ Score < 85? โ”‚ โ”€โ”€โ–บ Loop
45
+ Score โ‰ฅ 85? โ”‚ โ”€โ”€โ–บ Done โœ…
34
46
  ```
35
47
 
36
- This is the **Quality Convergence Loop** โ€” Coco's core differentiator.
37
-
38
48
  ---
39
49
 
40
- ## Quick Start
50
+ ## โœจ Features
41
51
 
42
- ```bash
43
- npm install -g @corbat-tech/coco
44
- coco # Opens interactive REPL โ€” guided setup on first run
45
- ```
52
+ ### ๐Ÿ”„ **Quality Convergence Loop** (COCO Mode)
46
53
 
47
- That's it. Coco walks you through provider configuration on first launch.
54
+ Not just code generation โ€” **iterative quality improvement**:
48
55
 
49
- ```bash
50
- # Or use it directly:
51
- coco "Add a REST API endpoint for user authentication with tests"
52
- ```
56
+ | Iteration | Score | Status |
57
+ |:---------:|:-----:|--------|
58
+ | **1** | 52 | Code generated โ€” 3 tests failing, no error handling |
59
+ | **2** | 71 | Tests fixed, security vulnerability found |
60
+ | **3** | 84 | Security patched, coverage 82% |
61
+ | **4** | **91** | โœ… **All green โ€” quality converged** |
53
62
 
54
- ---
63
+ > Enable with `/coco` โ€” now **on by default** for better results
55
64
 
56
- ## What Coco Does Well
65
+ ### ๐Ÿ“Š **12-Dimension Quality Scoring**
57
66
 
58
- ### Quality Convergence Loop
67
+ Real metrics, not guesses:
59
68
 
60
- Coco doesn't just generate code โ€” it iterates until quality converges:
69
+ | Dimension | How It's Measured |
70
+ |-----------|-------------------|
71
+ | Test Coverage | c8/v8 instrumentation |
72
+ | Security | Pattern matching + optional Snyk |
73
+ | Complexity | Cyclomatic complexity (AST) |
74
+ | Duplication | Line-based similarity |
75
+ | Correctness | Test pass rate + build verification |
76
+ | Style | oxlint / eslint / biome |
77
+ | Documentation | JSDoc coverage |
78
+ | + 5 more | Readability, Maintainability, Test Quality, Completeness, Robustness |
61
79
 
62
- | Iteration | Score | What happened |
63
- |:---------:|:-----:|---------------|
64
- | 1 | 52 | Code generated โ€” 3 tests failing, no error handling |
65
- | 2 | 71 | Tests fixed, security vulnerability found |
66
- | 3 | 84 | Security patched, coverage improved to 82% |
67
- | 4 | 91 | All green โ€” quality converged โœ… |
80
+ ### ๐Ÿš€ **Full Release Pipeline**
68
81
 
69
- The quality bar is yours to set:
82
+ Ship with confidence using `/ship`:
70
83
 
71
84
  ```bash
72
- coco build --min-quality 90 # Per-run override
73
- coco config set quality.minScore 90 # Persist in project config
85
+ /ship # Complete 10-step pipeline
74
86
  ```
75
87
 
76
- Default is **85** (senior-level). You can also configure max iterations, convergence threshold, coverage targets, and security requirements โ€” see `coco config init`.
88
+ **Pipeline:** Preflight โ†’ Review โ†’ Tests โ†’ Lint โ†’ Branch โ†’ Version โ†’ Commit โ†’ PR โ†’ CI โ†’ Merge
77
89
 
78
- ### 12-Dimension Quality Scoring
90
+ Each step is interactive โ€” press `Ctrl+C` anytime to safely cancel.
79
91
 
80
- Every iteration measures your code across 12 dimensions using real static analysis:
92
+ ### ๐Ÿค– **Multi-Agent Architecture**
81
93
 
82
- | Dimension | How it's measured |
83
- |-----------|-------------------|
84
- | Test Coverage | c8/v8 instrumentation |
85
- | Security | Pattern matching + optional Snyk |
86
- | Complexity | Cyclomatic complexity via AST parsing |
87
- | Duplication | Line-based similarity detection |
88
- | Correctness | Test pass rate + build verification |
89
- | Style | oxlint / eslint / biome integration |
90
- | Documentation | JSDoc coverage analysis |
91
- | Readability | AST: naming quality, function length, nesting |
92
- | Maintainability | AST: file size, coupling, function count |
93
- | Test Quality | Assertion density, edge case coverage |
94
- | Completeness | Export density + test file coverage |
95
- | Robustness | Error handling pattern detection |
94
+ Six specialized agents with automatic routing:
96
95
 
97
- > **Transparency note**: 7 dimensions use instrumented measurements. 5 use heuristic-based static analysis. We label which is which โ€” no black boxes.
96
+ - **Researcher** โ€” Codebase exploration and analysis
97
+ - **Coder** โ€” Code implementation (default)
98
+ - **Tester** โ€” Test generation and coverage
99
+ - **Reviewer** โ€” Quality auditing and code review
100
+ - **Optimizer** โ€” Refactoring and performance
101
+ - **Planner** โ€” Architecture and task decomposition
98
102
 
99
- ### Multi-Provider Support
103
+ ### ๐ŸŒ **Multi-Provider Support**
100
104
 
101
- Bring your own API keys. Coco works with:
105
+ Bring your own API key:
102
106
 
103
107
  | Provider | Auth | Models |
104
108
  |----------|------|--------|
105
- | **Anthropic** | API key / OAuth PKCE | Claude Opus, Sonnet, Haiku |
106
- | **OpenAI** | API key | GPT-4o, o1, o3 |
107
- | **Google** | API key / gcloud ADC | Gemini Pro, Flash |
109
+ | **Anthropic** | API key / OAuth | Claude Opus, Sonnet, Haiku |
110
+ | **OpenAI** | API key | GPT-5.3 Codex, GPT-4.1, o4-mini |
111
+ | **Google** | API key / gcloud | Gemini 3, 2.5 Pro/Flash |
108
112
  | **Ollama** | Local | Any local model |
109
113
  | **LM Studio** | Local | Any GGUF model |
110
114
  | **Moonshot** | API key | Kimi models |
111
115
 
112
- ### Multi-Agent Architecture
116
+ ### โšก **Modern Terminal UX**
113
117
 
114
- Six specialized agents with weighted-scoring routing:
118
+ - **Ghost-text completion** โ€” Tab to accept suggestions
119
+ - **Image paste** โ€” `Ctrl+V` to paste screenshots
120
+ - **Intent recognition** โ€” Natural language โ†’ commands
121
+ - **Full-access mode** โ€” `/full-access` for auto-approvals (with safety guards)
122
+ - **Self-update** โ€” Type "update coco" anytime
115
123
 
116
- - **Researcher** โ€” Explores, analyzes, maps the codebase
117
- - **Coder** โ€” Writes and edits code (default route)
118
- - **Tester** โ€” Generates tests, improves coverage
119
- - **Reviewer** โ€” Code review, quality auditing
120
- - **Optimizer** โ€” Refactoring and performance
121
- - **Planner** โ€” Architecture design, task decomposition
124
+ ---
125
+
126
+ ## ๐Ÿš€ Quick Start
127
+
128
+ ```bash
129
+ # Install globally
130
+ npm install -g @corbat-tech/coco
131
+
132
+ # Start interactive mode
133
+ coco
134
+
135
+ # Or use directly
136
+ coco "Add user authentication with tests"
137
+ ```
138
+
139
+ That's it. Coco walks you through provider setup on first launch.
140
+
141
+ ---
122
142
 
123
- Coco picks the right agent for each task automatically. When confidence is low, it defaults to the coder โ€” no guessing games.
143
+ ## ๐Ÿ’ฌ Commands
124
144
 
125
- ### Interactive REPL
145
+ ### Slash Commands
126
146
 
127
- A terminal-first experience with:
147
+ | Command | What it does |
148
+ |---------|-------------|
149
+ | `/help` | Show available commands |
150
+ | `/status` | Project status, git info, session stats |
151
+ | `/review` | Code review with severity-rated findings |
152
+ | `/diff` | Visual diff with syntax highlighting |
153
+ | `/ship` | Full release pipeline (review โ†’ test โ†’ PR โ†’ merge) |
154
+ | `/coco [on\|off]` | Toggle quality mode (default: ON) |
155
+ | `/full-access [on\|off]` | Auto-approve safe commands |
156
+ | `/compact` | Reduce context when conversation grows |
157
+ | `/clear` | Clear conversation history |
128
158
 
129
- - **Ghost-text completion** โ€” Tab to accept inline suggestions
130
- - **Slash commands** โ€” `/coco`, `/plan`, `/build`, `/diff`, `/commit`, `/help`
131
- - **Image paste** โ€” `Ctrl+V` to paste screenshots for visual context
132
- - **Intent recognition** โ€” Natural language mapped to commands
133
- - **Context management** โ€” Automatic compaction when context grows large
159
+ ### Natural Language
134
160
 
135
- ### Production Hardening
161
+ You don't need slash commands. Just talk:
136
162
 
137
- - **Error recovery** with typed error strategies and exponential backoff
138
- - **Checkpoint/Resume** โ€” `Ctrl+C` saves state, `coco resume` picks up where you left off
139
- - **AST validation** โ€” Syntax-checks generated code before saving
140
- - **Convergence analysis** โ€” Detects oscillation, diminishing returns, and stuck patterns
141
- - **Path sandboxing** โ€” Tools can only access files within the project
163
+ | You say | Coco does |
164
+ |---------|-----------|
165
+ | "review the code" | Runs `/review` |
166
+ | "let's ship it" | Runs `/ship` |
167
+ | "show me the changes" | Runs `/diff` |
168
+ | **"update coco"** | **Runs `/update-coco`** |
169
+
170
+ Bilingual support (English/Spanish).
142
171
 
143
172
  ---
144
173
 
145
- ## COCO Methodology
174
+ ## ๐ŸŽฏ How It Works
175
+
176
+ ### COCO Methodology
146
177
 
147
- Four phases, each with a dedicated executor:
178
+ Four phases for production-ready output:
148
179
 
149
180
  ```
150
181
  CONVERGE ORCHESTRATE COMPLETE OUTPUT
@@ -160,101 +191,95 @@ Four phases, each with a dedicated executor:
160
191
  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
161
192
  ```
162
193
 
163
- 1. **Converge** โ€” Understand what needs to be built. Gather requirements, produce a spec.
164
- 2. **Orchestrate** โ€” Design the architecture, decompose into a task backlog.
165
- 3. **Complete** โ€” Execute each task with the quality convergence loop.
166
- 4. **Output** โ€” Generate CI/CD pipelines, documentation, and deployment config.
194
+ 1. **Converge** โ€” Understand requirements
195
+ 2. **Orchestrate** โ€” Design architecture
196
+ 3. **Complete** โ€” Build with quality iteration
197
+ 4. **Output** โ€” Generate deployment config
167
198
 
168
199
  ---
169
200
 
170
- ## Use Cases
171
-
172
- Coco is designed for developers who want AI assistance with **accountability**:
201
+ ## ๐Ÿ“– Documentation
173
202
 
174
- - **Feature development** โ€” Describe what you want, get tested and reviewed code
175
- - **Vibe coding** โ€” Explore ideas interactively; Coco handles the quality checks
176
- - **Refactoring** โ€” Point at code and say "make this better" โ€” Coco iterates until metrics improve
177
- - **Test generation** โ€” Improve coverage with meaningful tests, not boilerplate
178
- - **Code review** โ€” Get multi-dimensional quality feedback on existing code
179
- - **Learning** โ€” See how code quality improves across iterations
203
+ - [Configuration Guide](docs/guides/CONFIGURATION.md)
204
+ - [Quick Start Tutorial](docs/guides/QUICK_START.md)
205
+ - [Troubleshooting](docs/guides/TROUBLESHOOTING.md)
206
+ - [API Reference](docs/API.md)
207
+ - [MCP Integration](docs/MCP.md)
180
208
 
181
209
  ---
182
210
 
183
- ## Development
211
+ ## ๐Ÿง‘โ€๐Ÿ’ป Development
184
212
 
185
213
  ```bash
186
214
  git clone https://github.com/corbat/corbat-coco
187
215
  cd corbat-coco
188
216
  pnpm install
189
- pnpm dev # Run in dev mode (tsx)
190
- pnpm test # 4,350+ tests via Vitest
191
- pnpm check # typecheck + lint + test
192
- pnpm build # Production build (tsup)
217
+ pnpm dev # Run in dev mode
218
+ pnpm test # 4,350+ tests
219
+ pnpm check # Typecheck + lint + test
193
220
  ```
194
221
 
195
222
  ### Project Structure
196
223
 
197
224
  ```
198
225
  src/
199
- โ”œโ”€โ”€ agents/ # Multi-agent coordination + weighted routing
200
- โ”œโ”€โ”€ cli/ # REPL, commands, input handling, output rendering
201
- โ”œโ”€โ”€ orchestrator/ # Phase coordinator + state recovery
202
- โ”œโ”€โ”€ phases/ # COCO phases (converge/orchestrate/complete/output)
203
- โ”œโ”€โ”€ quality/ # 12 quality analyzers + convergence engine
204
- โ”œโ”€โ”€ providers/ # 6 LLM providers + OAuth flows
205
- โ”œโ”€โ”€ tools/ # 20+ tool implementations
206
- โ”œโ”€โ”€ hooks/ # Lifecycle hooks (safety, lint, format, audit)
207
- โ”œโ”€โ”€ mcp/ # MCP server for external integration
208
- โ””โ”€โ”€ config/ # Zod-validated configuration system
226
+ โ”œโ”€โ”€ agents/ # Multi-agent coordination
227
+ โ”œโ”€โ”€ cli/ # REPL + commands
228
+ โ”œโ”€โ”€ phases/ # COCO phases
229
+ โ”œโ”€โ”€ quality/ # 12-dimension scoring
230
+ โ”œโ”€โ”€ providers/ # LLM provider integrations
231
+ โ””โ”€โ”€ tools/ # File ops, git, tests, etc.
209
232
  ```
210
233
 
211
- ### Technology Stack
234
+ **Stack:** TypeScript + Node.js 22 + Vitest + oxlint/oxfmt + Zod
235
+
236
+ ---
237
+
238
+ ## ๐ŸŽ“ Use Cases
212
239
 
213
- | Component | Technology |
214
- |-----------|-----------|
215
- | Language | TypeScript (ESM, strict mode) |
216
- | Runtime | Node.js 22+ |
217
- | Testing | Vitest (4,350+ tests) |
218
- | Linting | oxlint |
219
- | Formatting | oxfmt |
220
- | Build | tsup |
221
- | Schema validation | Zod |
240
+ - **Feature development** โ€” Get tested, reviewed code
241
+ - **Refactoring** โ€” Improve quality with measurable progress
242
+ - **Test generation** โ€” Meaningful tests, not boilerplate
243
+ - **Code review** โ€” 12-dimensional quality feedback
244
+ - **Learning** โ€” See how quality improves across iterations
222
245
 
223
246
  ---
224
247
 
225
- ## Known Limitations
248
+ ## โš ๏ธ Known Limitations
226
249
 
227
250
  We'd rather you know upfront:
228
251
 
229
- - **TypeScript/JavaScript first** โ€” Other languages have basic support but fewer analyzers
230
- - **CLI-only** โ€” No IDE extension yet (VS Code integration is planned)
231
- - **Iteration takes time** โ€” The convergence loop adds 2-5 minutes per task. For quick one-line fixes, a simpler tool may be faster
232
- - **Heuristic analyzers** โ€” 5 of 12 quality dimensions use pattern-based heuristics, not deep semantic analysis
233
- - **LLM-dependent** โ€” Output quality depends on the model you connect. Larger models produce better results
234
- - **Early stage** โ€” Actively developed. Not yet battle-tested at large enterprise scale
252
+ - **TypeScript/JavaScript first** โ€” Other languages have basic support
253
+ - **CLI-only** โ€” No IDE extension yet (VS Code planned)
254
+ - **Iteration takes time** โ€” Convergence adds 2-5 min per task
255
+ - **LLM-dependent** โ€” Quality depends on your model choice
256
+ - **Early stage** โ€” Not yet battle-tested at enterprise scale
235
257
 
236
258
  ---
237
259
 
238
- ## Contributing
260
+ ## ๐Ÿค Contributing
261
+
262
+ Contributions welcome:
263
+
264
+ - ๐Ÿ› Bug reports and feature requests
265
+ - ๐Ÿ”ฌ New quality analyzers
266
+ - ๐Ÿ”Œ Additional LLM providers
267
+ - ๐Ÿ“š Documentation and examples
239
268
 
240
- We welcome contributions of all kinds:
269
+ See [CONTRIBUTING.md](./CONTRIBUTING.md).
270
+
271
+ ---
241
272
 
242
- - Bug reports and feature requests
243
- - New quality analyzers
244
- - Additional LLM provider integrations
245
- - Documentation and examples
246
- - Real-world usage feedback
273
+ ## ๐Ÿ“„ License
247
274
 
248
- See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
275
+ MIT ยฉ [Corbat](https://corbat.tech)
249
276
 
250
277
  ---
251
278
 
252
- ## About
279
+ <div align="center">
253
280
 
254
- Corbat-Coco is built by [Corbat](https://corbat.tech), a technology consultancy that believes AI coding tools should be transparent, measurable, and open source.
281
+ **Built by developers who measure before they ship** ๐Ÿฅฅ
255
282
 
256
- <p align="center">
257
- <a href="https://github.com/corbat/corbat-coco">GitHub</a> ยท <a href="https://corbat.tech">corbat.tech</a>
258
- </p>
283
+ [GitHub](https://github.com/corbat/corbat-coco) ยท [corbat.tech](https://corbat.tech) ยท [npm](https://www.npmjs.com/package/@corbat-tech/coco)
259
284
 
260
- <p align="center"><strong>MIT License</strong> ยท Made by developers who measure before they ship. ๐Ÿฅฅ</p>
285
+ </div>