@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 +179 -154
- package/README.old.md +310 -0
- package/dist/cli/index.js +3157 -1989
- package/dist/cli/index.js.map +1 -1
- package/dist/index.d.ts +12 -1
- package/dist/index.js +430 -49
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,150 +1,181 @@
|
|
|
1
|
-
<
|
|
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
|
-
|
|
3
|
+
# ๐ฅฅ Coco
|
|
10
4
|
|
|
11
|
-
|
|
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
|
-
|
|
16
|
-
|
|
17
|
-
|
|
7
|
+
[Features](#-features) โข
|
|
8
|
+
[Quick Start](#-quick-start) โข
|
|
9
|
+
[How It Works](#-how-it-works) โข
|
|
10
|
+
[Commands](#-commands) โข
|
|
11
|
+
[Documentation](#-documentation)
|
|
12
|
+
|
|
13
|
+
[](https://www.npmjs.com/package/@corbat-tech/coco)
|
|
14
|
+
[](LICENSE)
|
|
15
|
+
[](https://www.typescriptlang.org/)
|
|
16
|
+
[](https://nodejs.org/)
|
|
17
|
+
[](https://github.com/corbat/corbat-coco/actions)
|
|
18
|
+
|
|
19
|
+
</div>
|
|
18
20
|
|
|
19
21
|
---
|
|
20
22
|
|
|
21
|
-
##
|
|
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
|
-
|
|
27
|
+
## The Solution
|
|
24
28
|
|
|
25
|
-
Coco
|
|
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
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
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
|
-
##
|
|
50
|
+
## โจ Features
|
|
41
51
|
|
|
42
|
-
|
|
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
|
-
|
|
54
|
+
Not just code generation โ **iterative quality improvement**:
|
|
48
55
|
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
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
|
-
|
|
65
|
+
### ๐ **12-Dimension Quality Scoring**
|
|
57
66
|
|
|
58
|
-
|
|
67
|
+
Real metrics, not guesses:
|
|
59
68
|
|
|
60
|
-
|
|
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
|
-
|
|
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
|
-
|
|
82
|
+
Ship with confidence using `/ship`:
|
|
70
83
|
|
|
71
84
|
```bash
|
|
72
|
-
|
|
73
|
-
coco config set quality.minScore 90 # Persist in project config
|
|
85
|
+
/ship # Complete 10-step pipeline
|
|
74
86
|
```
|
|
75
87
|
|
|
76
|
-
|
|
88
|
+
**Pipeline:** Preflight โ Review โ Tests โ Lint โ Branch โ Version โ Commit โ PR โ CI โ Merge
|
|
77
89
|
|
|
78
|
-
|
|
90
|
+
Each step is interactive โ press `Ctrl+C` anytime to safely cancel.
|
|
79
91
|
|
|
80
|
-
|
|
92
|
+
### ๐ค **Multi-Agent Architecture**
|
|
81
93
|
|
|
82
|
-
|
|
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
|
-
|
|
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
|
|
105
|
+
Bring your own API key:
|
|
102
106
|
|
|
103
107
|
| Provider | Auth | Models |
|
|
104
108
|
|----------|------|--------|
|
|
105
|
-
| **Anthropic** | API key / OAuth
|
|
106
|
-
| **OpenAI** | API key | GPT-
|
|
107
|
-
| **Google** | API key / gcloud
|
|
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
|
-
###
|
|
116
|
+
### โก **Modern Terminal UX**
|
|
113
117
|
|
|
114
|
-
|
|
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
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
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
|
-
|
|
143
|
+
## ๐ฌ Commands
|
|
124
144
|
|
|
125
|
-
###
|
|
145
|
+
### Slash Commands
|
|
126
146
|
|
|
127
|
-
|
|
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
|
-
|
|
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
|
-
|
|
161
|
+
You don't need slash commands. Just talk:
|
|
136
162
|
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
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
|
-
##
|
|
174
|
+
## ๐ฏ How It Works
|
|
175
|
+
|
|
176
|
+
### COCO Methodology
|
|
146
177
|
|
|
147
|
-
Four phases
|
|
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
|
|
164
|
-
2. **Orchestrate** โ Design
|
|
165
|
-
3. **Complete** โ
|
|
166
|
-
4. **Output** โ Generate
|
|
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
|
-
##
|
|
171
|
-
|
|
172
|
-
Coco is designed for developers who want AI assistance with **accountability**:
|
|
201
|
+
## ๐ Documentation
|
|
173
202
|
|
|
174
|
-
-
|
|
175
|
-
-
|
|
176
|
-
-
|
|
177
|
-
-
|
|
178
|
-
-
|
|
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
|
|
190
|
-
pnpm test # 4,350+ tests
|
|
191
|
-
pnpm check #
|
|
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
|
|
200
|
-
โโโ cli/ # REPL
|
|
201
|
-
โโโ
|
|
202
|
-
โโโ
|
|
203
|
-
โโโ
|
|
204
|
-
|
|
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
|
-
|
|
234
|
+
**Stack:** TypeScript + Node.js 22 + Vitest + oxlint/oxfmt + Zod
|
|
235
|
+
|
|
236
|
+
---
|
|
237
|
+
|
|
238
|
+
## ๐ Use Cases
|
|
212
239
|
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
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
|
|
230
|
-
- **CLI-only** โ No IDE extension yet (VS Code
|
|
231
|
-
- **Iteration takes time** โ
|
|
232
|
-
- **
|
|
233
|
-
- **
|
|
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
|
-
|
|
269
|
+
See [CONTRIBUTING.md](./CONTRIBUTING.md).
|
|
270
|
+
|
|
271
|
+
---
|
|
241
272
|
|
|
242
|
-
|
|
243
|
-
- New quality analyzers
|
|
244
|
-
- Additional LLM provider integrations
|
|
245
|
-
- Documentation and examples
|
|
246
|
-
- Real-world usage feedback
|
|
273
|
+
## ๐ License
|
|
247
274
|
|
|
248
|
-
|
|
275
|
+
MIT ยฉ [Corbat](https://corbat.tech)
|
|
249
276
|
|
|
250
277
|
---
|
|
251
278
|
|
|
252
|
-
|
|
279
|
+
<div align="center">
|
|
253
280
|
|
|
254
|
-
|
|
281
|
+
**Built by developers who measure before they ship** ๐ฅฅ
|
|
255
282
|
|
|
256
|
-
|
|
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
|
-
|
|
285
|
+
</div>
|