@korl3one/ccode 2.2.0 → 3.1.0

package/README.md

@@ -1,93 +1,89 @@
-```
-   ██████╗ ██████╗  ██████╗ ██████╗ ███████╗
-  ██╔════╝██╔════╝ ██╔═══██╗██╔══██╗██╔════╝
-  ██║     ██║      ██║   ██║██║  ██║█████╗
-  ██║     ██║      ██║   ██║██║  ██║██╔══╝
-  ╚██████╗╚██████╗ ╚██████╔╝██████╔╝███████╗
-   ╚═════╝ ╚═════╝  ╚═════╝ ╚═════╝ ╚══════╝
-```
+<div align="center">
 
-# CCODE
+<img src="assets/logo.png" alt="CCODE" width="600"/>
+
+<br/>
+<br/>
 
 **Persistent context CLI for AI-assisted development.**
 
 Stop re-explaining your project to AI every time the session resets.
 
+<br/>
+
 ```bash
 npm install -g @korl3one/ccode
-ccode init
 ```
 
-[![npm version](https://img.shields.io/npm/v/@korl3one/ccode)](https://www.npmjs.com/package/@korl3one/ccode)
-[![license](https://img.shields.io/npm/l/@korl3one/ccode)](LICENSE)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+<br/>
+
+[![npm version](https://img.shields.io/npm/v/@korl3one/ccode?color=00B4D8&style=for-the-badge)](https://www.npmjs.com/package/@korl3one/ccode)
+[![license](https://img.shields.io/npm/l/@korl3one/ccode?color=0077B6&style=for-the-badge)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-2DC653?style=for-the-badge)](https://nodejs.org)
+[![GitHub stars](https://img.shields.io/github/stars/iDevelop25/ccode?style=for-the-badge&color=FFB703)](https://github.com/iDevelop25/ccode)
+
+</div>
 
 ---
 
 ## The problem
 
-Every time you switch sessions, models, or tools when working with AI, you lose your project context. You end up re-explaining the architecture, previous decisions, and current state over and over again.
+Every time you switch sessions, models, or tools when working with AI, **you lose your project context**. You end up re-explaining the architecture, previous decisions, and current state over and over again.
 
-## The solution
-
-CCODE stores your project context **inside the repository**. One command generates professional documentation, architecture, rules, and a verifiable task checklist — all adapted to your project's actual complexity.
+And if you use multiple AI tools — Claude Code, Cursor, Gemini CLI, Copilot — you have to configure context files for each one manually.
 
-Any developer or AI can read `.ccode/` and understand the project instantly.
+## The solution
 
----
+CCODE generates and maintains your project context **inside the repository**. One command produces professional documentation, architecture, rules, and a verifiable task checklist — all adapted to your project's actual complexity.
 
-## Demo
+Then it **syncs that context to every major AI tool** automatically.
 
-```
-$ ccode init
+Any developer or AI can read your project and understand it instantly.
 
-   ██████╗ ██████╗  ██████╗ ██████╗ ███████╗
-  ██╔════╝██╔════╝ ██╔═══██╗██╔══██╗██╔════╝
-  ██║     ██║      ██║   ██║██║  ██║█████╗
-  ╚██████╗╚██████╗ ╚██████╔╝██████╔╝███████╗
-   ╚═════╝ ╚═════╝  ╚═════╝ ╚═════╝ ╚══════╝
+---
 
-  ●●●●  Paso 4/4
+## Universal Context Sync
 
-  ✓ Contexto generado exitosamente
+This is what makes CCODE different. One command generates context files for **every major AI tool**:
 
-  .ccode/
-  ├── project.md        Documentacion del proyecto
-  ├── architecture.md   Arquitectura del sistema
-  ├── rules.md          Estandares de desarrollo
-  ├── tasks.json        Checklist de tareas (8 tareas)
-  ├── context.json      Configuracion
-  ├── state.json        Estado del workflow
-  └── memory.md         Historial de decisiones
+```bash
+ccode sync
+```
 
-  CCODE sigue observando tu proyecto...
+```
+project/
+├── AGENTS.md                        ← Open Standard (60K+ repos)
+├── CLAUDE.md                        ← Claude Code
+├── GEMINI.md                        ← Gemini CLI
+├── .cursorrules                     ← Cursor
+├── .github/copilot-instructions.md  ← GitHub Copilot
+└── .ccode/context-export.md         ← Universal (copy/paste to any AI chat)
+```
 
-  ████████████░░░░░░░░  60%  (3/5)
-  > Tarea activa: TASK-002 — Crear formulario de login
+Each file is adapted to the tool's expected format. Your project context — architecture, rules, tasks, decisions — synced everywhere, from a single source of truth.
 
-  ? Que hacemos?
-    > Verificar progreso (se detectaron cambios)
-      Marcar tarea como completada
-      Iniciar siguiente tarea
-      Ver estado completo
-      Salir
-```
+No manual setup per tool. No copy-pasting between files. Context stays in sync automatically with `ccode init`, `ccode update`, and `ccode sync`.
 
 ---
 
 ## Why CCODE?
 
+<div align="center">
+
 | | CCODE | Manual prompts |
 |---|:---:|:---:|
 | Persistent project context | ✅ | ❌ |
+| Universal context sync (5+ AI tools) | ✅ | ❌ |
 | Architecture adapted to complexity | ✅ | ❌ |
 | AI-ready documentation | ✅ | ❌ |
 | Verifiable task checklist | ✅ | ❌ |
 | Auto-detect file changes | ✅ | ❌ |
 | AI-powered task verification | ✅ | ❌ |
-| Works with 6 AI providers | ✅ | ❌ |
+| Zero-config AI provider detection | ✅ | ❌ |
 | Context lives in the repo (Git) | ✅ | ❌ |
 
+</div>
+
 ---
 
 ## How it works
@@ -99,15 +95,21 @@ cd my-project
 ccode init
 ```
 
-A step-by-step wizard asks about your project and an AI generates the full context. CCODE adapts automatically:
+A step-by-step wizard asks about your project and an AI generates the full context. CCODE **adapts automatically**:
+
+| Project type | Context depth | Tasks |
+|---|---|---|
+| Simple (prototype, few features) | Lightweight docs | 3-5 |
+| Medium (standard app) | Moderate architecture | 5-8 |
+| Complex (multiple modules) | Detailed patterns + diagrams | 8-12 |
+
+A simple login doesn't need microservice diagrams. CCODE is smart about it.
 
-- **Simple project** (prototype, few features) → lightweight context, 3-5 tasks
-- **Medium project** (standard app) → moderate context, 5-8 tasks
-- **Complex project** (multiple modules, integrations) → detailed architecture, 8-12 tasks
+After generation, context is automatically synced to all AI tools.
 
 ### 2. Persistent session
 
-After init, CCODE stays active — watching your project in real time:
+After init, CCODE **stays active** — watching your project in real time:
 
 - Detects file changes automatically
 - Suggests verifying tasks when it sees progress
@@ -130,40 +132,50 @@ CCODE compares **acceptance criteria** against **actual project files**:
 ○ TASK-003: Implement JWT auth — PENDING
 ```
 
-### 4. Context export
+It doesn't guess — it verifies.
+
+### 4. Context sync
+
+```bash
+ccode sync
+```
+
+Regenerates context files for every AI tool. Run it after making significant changes, or let `ccode update` handle it when you re-analyze the project.
+
+### 5. Context export
 
 ```bash
 ccode export
 ```
 
-Generates a single `.md` file with your full project context — ready to paste into any AI chat (ChatGPT, Claude, Gemini, etc.) without connecting an API.
+Three options: sync to all tools, export a universal `.md` for copy/paste into any AI chat, or pick specific tools.
 
-### 5. Project health check
+### 6. Project health check
 
 ```bash
 ccode doctor
 ```
 
-```
-✓ Contexto generado
-✓ Proveedor de IA configurado
-⚠ 2 tareas sin completar
-⚠ architecture.md no refleja 3 archivos nuevos
-✓ Conexion con IA activa
-```
+Like a linter, but for your project context. Checks context files, AI connection, task status, export state, and tells you what needs attention.
 
 ---
 
 ## Supported AI Providers
 
+<div align="center">
+
 | Provider | Models | Note |
 |----------|--------|------|
-| **Claude** (Anthropic) | Sonnet 4, Haiku 3.5, Opus 4 | Recommended |
-| **OpenAI** (ChatGPT) | GPT-4o, GPT-4o mini, GPT-4.1, o3-mini | Most popular |
-| **Google Gemini** | 2.5 Flash, 2.5 Pro, 2.0 Flash | Free tier available |
-| **DeepSeek** | Chat, Reasoner | Budget-friendly |
-| **Groq** | Llama 3.3 70B, Llama 3.1 8B, Mixtral 8x7B | Ultra-fast, free tier |
-| **Ollama** | Any local model | Offline, no API key |
+| **Google Gemini** | 2.5 Flash, 2.5 Pro, 2.0 Flash | Free — just a Google account |
+| **Claude** (Anthropic) | Sonnet 4, Haiku 3.5, Opus 4 | Best quality |
+
+</div>
+
+CCODE auto-detects your provider:
+
+1. **Gemini CLI OAuth** — If you have `gemini` CLI installed and authenticated, it works instantly. Zero config.
+2. **Environment variables** — `GOOGLE_API_KEY` or `ANTHROPIC_API_KEY` detected automatically.
+3. **Manual setup** — Guided wizard with browser-based key generation as fallback.
 
 ---
 
@@ -171,29 +183,49 @@ ccode doctor
 
 | Command | What it does |
 |---------|-------------|
-| `ccode init` | Interactive wizard — generates full project context |
-| `ccode update` | Re-analyze project and refresh context |
-| `ccode export` | Export context as a single `.md` file for any AI |
-| `ccode explain` | Quick project summary for onboarding |
-| `ccode doctor` | Health check — what's good, what's missing |
-| `ccode connect` | Configure AI provider |
+| `ccode init` | Interactive wizard — generates full project context + syncs to all AI tools |
+| `ccode sync` | Sync context to all AI tools (AGENTS.md, CLAUDE.md, .cursorrules, ...) |
+| `ccode update` | Re-analyze project with AI and refresh context |
+| `ccode export` | Export context — all tools, universal .md, or pick specific |
+| `ccode verify` | AI-powered task verification against actual project files |
 | `ccode status` | Dashboard with progress bar and stats |
+| `ccode doctor` | Health check — context files, AI connection, exports, tasks |
+| `ccode connect` | Configure or reconfigure AI provider |
+| `ccode explain` | Quick project summary for onboarding |
+| `ccode plan` | Generate or regenerate task checklist |
+| `ccode next` | Show and start the next pending task |
+| `ccode complete` | Mark active task as completed |
 
 ---
 
 ## What gets generated
 
-Everything lives in `.ccode/` inside your repository:
+### Source of truth (`.ccode/`)
+
+```
+.ccode/
+├── project.md          Vision, objectives, scope
+├── architecture.md     System structure (adapted to complexity)
+├── rules.md            Development standards for your stack
+├── tasks.json          Task checklist with acceptance criteria
+├── state.json          Active task, workflow stage
+├── context.json        Project configuration
+├── memory.md           Decision history
+├── config.json         AI provider config
+└── context-export.md   Universal export
+```
+
+### Synced context files (project root)
+
+```
+AGENTS.md                        Open Standard
+CLAUDE.md                        Claude Code
+GEMINI.md                        Gemini CLI
+.cursorrules                     Cursor
+.github/copilot-instructions.md  GitHub Copilot
+```
 
-| File | Content |
-|------|---------|
-| `project.md` | Vision, objectives, scope |
-| `architecture.md` | System structure adapted to complexity |
-| `rules.md` | Development standards for your stack |
-| `tasks.json` | Task checklist with acceptance criteria |
-| `state.json` | Active task, workflow stage |
-| `memory.md` | Decision history |
-| `config.json` | AI provider config |
+All derived from `.ccode/`. One source, multiple outputs.
 
 ---
 
@@ -201,46 +233,54 @@ Everything lives in `.ccode/` inside your repository:
 
 ```
 src/
-  cli/          → Session, branding, file watcher
-  core/         → Context engine, tasks, prompt builder
-  ai/           → 6 provider adapters (Adapter pattern)
-  utils/        → File system abstraction
+├── cli/           Session, branding, file watcher
+├── core/          Context engine, tasks, prompt builder, exports
+├── ai/            Provider adapters (Adapter pattern)
+└── utils/         File system abstraction
 ```
 
-Key patterns: **Adapter** (AI providers), **Observer** (file watcher), **State Machine** (workflow), **Builder** (prompts).
+**Patterns:** Adapter (AI providers) · Observer (file watcher) · State Machine (workflow) · Builder (prompts)
 
 ---
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions and guidelines.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions.
 
-Adding a new AI provider? Just implement `IAIProvider`, add it to the manager switch, done.
+Adding a new AI provider? Implement `IAIProvider`, add it to the manager, done.
+
+Adding a new export format? Add a method to `ContextExporter`, register the format, done.
+
+Zero changes to the rest of the system in both cases.
 
 ---
 
 ## Learn more
 
-- [Learning guide](docs/learning/README.md) — 6 modules following QP2C methodology
-- [AGENTS.md](AGENTS.md) — Engineering roles
-- [SKILLS.md](SKILLS.md) — Technical competencies
-- [YouTube @CreativeCode25](https://www.youtube.com/@CreativeCode25) — Tutorials and walkthroughs
+| Resource | Link |
+|----------|------|
+| Engineering roles | [AGENTS.md](AGENTS.md) |
+| Technical competencies | [SKILLS.md](SKILLS.md) |
+| YouTube | [@CreativeCode25](https://www.youtube.com/@CreativeCode25) |
 
 ---
 
-## Support the project
+<div align="center">
+
+### If CCODE helps you, consider giving it a star
 
-If CCODE helps you, consider giving it a **star on GitHub** ⭐
 It helps the project grow and reach more developers.
 
-[![GitHub stars](https://img.shields.io/github/stars/iDevelop25/ccode?style=social)](https://github.com/iDevelop25/ccode)
+<br/>
 
----
+[![Star on GitHub](https://img.shields.io/github/stars/iDevelop25/ccode?style=for-the-badge&color=FFB703&label=Star%20on%20GitHub)](https://github.com/iDevelop25/ccode)
 
-## License
+<br/>
 
-ISC
+**[npm](https://www.npmjs.com/package/@korl3one/ccode)** · **[GitHub](https://github.com/iDevelop25/ccode)** · **[YouTube](https://www.youtube.com/@CreativeCode25)**
 
----
+<br/>
 
 *CCODE doesn't tell you how to code — it tells you what to build and makes sure you don't lose track.*
+
+</div>

package/dist/ai/claude.d.ts

@@ -3,7 +3,8 @@ import { IAIProvider, IAIConfig } from './provider.js';
  * Adaptador para Claude (Anthropic).
  */
 export declare class ClaudeAdapter implements IAIProvider {
-    private config;
+    private apiKey;
+    private model;
     constructor(config: IAIConfig);
     getName(): string;
     generate(prompt: string): Promise<string>;

package/dist/ai/claude.js

@@ -3,32 +3,35 @@ import axios from 'axios';
  * Adaptador para Claude (Anthropic).
  */
 export class ClaudeAdapter {
-    config;
+    apiKey;
+    model;
     constructor(config) {
-        this.config = {
-            apiKey: config.apiKey || '',
-            model: config.model || 'claude-sonnet-4-20250514',
-            baseUrl: config.baseUrl || 'https://api.anthropic.com/v1/messages',
-        };
+        this.apiKey = config.apiKey || '';
+        this.model = config.model || 'claude-sonnet-4-20250514';
     }
     getName() {
-        return `Claude (${this.config.model})`;
+        return `Claude (${this.model})`;
     }
     async generate(prompt) {
-        if (!this.config.apiKey) {
+        if (!this.apiKey) {
             throw new Error('API Key de Anthropic no configurada.');
         }
-        const response = await axios.post(this.config.baseUrl, {
-            model: this.config.model,
+        const response = await axios.post('https://api.anthropic.com/v1/messages', {
+            model: this.model,
             max_tokens: 8096,
             messages: [{ role: 'user', content: prompt }],
         }, {
             headers: {
-                'x-api-key': this.config.apiKey,
+                'x-api-key': this.apiKey,
                 'anthropic-version': '2023-06-01',
                 'content-type': 'application/json',
             },
+            timeout: 120000,
         });
-        return response.data.content[0].text;
+        const text = response.data?.content?.[0]?.text;
+        if (!text) {
+            throw new Error('Claude respondio pero sin contenido. Intenta de nuevo.');
+        }
+        return text;
     }
 }

package/dist/ai/gemini.d.ts

@@ -1,10 +1,22 @@
 import { IAIProvider, IAIConfig } from './provider.js';
 /**
  * Adaptador para Google Gemini.
+ * Soporta API Key y OAuth token (de Gemini CLI).
  */
 export declare class GeminiAdapter implements IAIProvider {
-    private config;
+    private apiKey;
+    private oauthToken;
+    private model;
     constructor(config: IAIConfig);
     getName(): string;
+    /**
+     * Try to read OAuth token from Gemini CLI installation.
+     */
+    static readOAuthToken(): string | null;
+    /**
+     * Check if Gemini CLI is installed and authenticated.
+     */
+    static isAvailable(): boolean;
+    setOAuthToken(token: string): void;
     generate(prompt: string): Promise<string>;
 }

package/dist/ai/gemini.js

@@ -1,31 +1,78 @@
 import axios from 'axios';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
 /**
  * Adaptador para Google Gemini.
+ * Soporta API Key y OAuth token (de Gemini CLI).
  */
 export class GeminiAdapter {
-    config;
+    apiKey;
+    oauthToken;
+    model;
     constructor(config) {
-        this.config = {
-            apiKey: config.apiKey || '',
-            model: config.model || 'gemini-2.5-flash',
-            baseUrl: config.baseUrl || 'https://generativelanguage.googleapis.com/v1beta/models',
-        };
+        this.apiKey = config.apiKey || '';
+        this.oauthToken = '';
+        this.model = config.model || 'gemini-2.5-flash';
     }
     getName() {
-        return `Gemini (${this.config.model})`;
+        return `Gemini (${this.model})`;
+    }
+    /**
+     * Try to read OAuth token from Gemini CLI installation.
+     */
+    static readOAuthToken() {
+        try {
+            const credsPath = path.join(os.homedir(), '.gemini', 'oauth_creds.json');
+            if (!fs.existsSync(credsPath))
+                return null;
+            const creds = JSON.parse(fs.readFileSync(credsPath, 'utf-8'));
+            if (creds.access_token && typeof creds.access_token === 'string') {
+                return creds.access_token;
+            }
+        }
+        catch {
+            // ignore
+        }
+        return null;
+    }
+    /**
+     * Check if Gemini CLI is installed and authenticated.
+     */
+    static isAvailable() {
+        return GeminiAdapter.readOAuthToken() !== null;
+    }
+    setOAuthToken(token) {
+        this.oauthToken = token;
     }
     async generate(prompt) {
-        if (!this.config.apiKey) {
-            throw new Error('API Key de Google AI no configurada.');
+        const baseUrl = `https://generativelanguage.googleapis.com/v1beta/models/${this.model}:generateContent`;
+        let url;
+        let headers;
+        if (this.oauthToken) {
+            // Use OAuth token from Gemini CLI
+            url = baseUrl;
+            headers = {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${this.oauthToken}`,
+            };
+        }
+        else if (this.apiKey) {
+            // Use API key
+            url = `${baseUrl}?key=${this.apiKey}`;
+            headers = { 'Content-Type': 'application/json' };
+        }
+        else {
+            throw new Error('No hay credenciales de Gemini configuradas.');
         }
-        const url = `${this.config.baseUrl}/${this.config.model}:generateContent?key=${this.config.apiKey}`;
         const response = await axios.post(url, {
             contents: [{ parts: [{ text: prompt }] }],
             generationConfig: { maxOutputTokens: 8096 },
-        }, {
-            headers: { 'Content-Type': 'application/json' },
-            timeout: 120000,
-        });
-        return response.data.candidates[0].content.parts[0].text;
+        }, { headers, timeout: 120000 });
+        const text = response.data?.candidates?.[0]?.content?.parts?.[0]?.text;
+        if (!text) {
+            throw new Error('Gemini respondio pero sin contenido. Intenta de nuevo.');
+        }
+        return text;
     }
 }

package/dist/ai/manager.d.ts

@@ -1,18 +1,37 @@
 import { IAIProvider } from './provider.js';
-export type ProviderName = 'claude' | 'openai' | 'gemini' | 'deepseek' | 'groq' | 'ollama';
+export type ProviderName = 'claude' | 'gemini';
 export interface ICCODEConfig {
     provider: ProviderName;
     apiKey?: string;
     model?: string;
-    baseUrl?: string;
+    authType?: 'api-key' | 'oauth';
 }
-/**
- * Gestiona la configuración y conexión con proveedores de IA.
- */
+export declare const PROVIDER_INFO: Record<ProviderName, {
+    name: string;
+    keyUrl: string;
+    envVars: string[];
+    models: Array<{
+        name: string;
+        value: string;
+    }>;
+}>;
 export declare class AIManager {
     private static readonly CONFIG_FILE;
     static loadConfig(): Promise<ICCODEConfig | null>;
     static saveConfig(config: ICCODEConfig): Promise<void>;
     static getProvider(config: ICCODEConfig): IAIProvider;
-    static testConnection(config: ICCODEConfig): Promise<boolean>;
+    static testConnection(config: ICCODEConfig): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    /**
+     * Auto-detect the best available provider.
+     * Priority: 1) Gemini CLI OAuth, 2) env vars, 3) null
+     */
+    static autoDetect(): {
+        provider: ProviderName;
+        authType: 'oauth' | 'api-key';
+        apiKey?: string;
+        source: string;
+    } | null;
 }