# Claudia Docs CLI — Handoff para Coder ## Overview Este documento es la guía de inicio para implementar **Claudia Docs CLI**, una herramienta de línea de comandos en Go que permite a Claudia (y otros agentes) interactuar con Claudia Docs. **Tiempo estimado de implementación:** 2-3 días (MVP completo) --- ## 1. Contexto del Proyecto ### Qué es - CLI written en **Go** con framework **Cobra** - Se comunica con la API REST de Claudia Docs (`/api/v1`) - Autenticación via JWT - Output por defecto en JSON, parseable por agentes ### Para qué sirve - Claudia guarda documentos y reasoning via CLI - Agentes pueden integrar el CLI en sus scripts/prompts - No requiere navegador ni UI web ### Repositorio ``` /projects/claudia-docs-cli/ ├── SPEC.md # Especificación completa (LEER PRIMERO) ├── HANDOFF.md # Este documento ├── cmd/ # Entry point ├── internal/ # Lógica de negocio └── pkg/types/ # Tipos compartidos ``` --- ## 2. Documentación Obligatoria **LEER ANTES DE CODear:** 1. **`SPEC.md`** — Especificación completa del CLI - Command structure - Flags y argumentos - Output format - Configuración - Estructura del proyecto 2. **`../claudia-docs/SPEC.md`** — Spec del backend - API endpoints (sección 5) - Data model (sección 4) - Auth flow - Para probar la API mientras sviluppo --- ## 3. Tech Stack | Componente | Tecnología | |------------|------------| | Language | Go 1.21+ | | CLI Framework | `github.com/spf13/cobra` | | Config | `github.com/spf13/viper` | | JWT | `github.com/golang-jwt/jwt/v5` | | HTTP | `net/http` (stdlib) | | JSON | `encoding/json` (stdlib) | **No agregar otras dependencias sin consultar.** --- ## 4. Configuración del Entorno ### Backend local (para testing) ```bash # En /projects/claudia-docs/ docker-compose up -d # API disponible en http://localhost:8000 # Swagger: http://localhost:8000/docs ``` ### Credenciales de test ```bash INITIAL_ADMIN_USERNAME=admin INITIAL_ADMIN_PASSWORD=admin123 ``` ### Variables de entorno para testing ```bash export CLAUDIA_SERVER=http://localhost:8000 export CLAUDIA_TOKEN="" ``` --- ## 5. Implementación Paso a Paso ### Paso 1: Setup del proyecto ```bash cd /projects/claudia-docs-cli # Inicializar go module go mod init github.com/claudia/docs-cli # Agregar dependencias go get github.com/spf13/cobra@v1.8.0 go get github.com/spf13/viper@v1.18.2 go get github.com/golang-jwt/jwt/v5@v5.2.0 ``` ### Paso 2: Estructura de carpetas ``` cmd/claudia-docs/main.go # Entry point internal/ api/client.go # HTTP client base api/documents.go # Document endpoints auth/auth.go # Login, JWT handling config/config.go # Viper config output/output.go # JSON/Text formatting pkg/types/types.go # Tipos compartidos cobra/commands.go # Definitions de comandos ``` ### Paso 3: Implementar en orden 1. **`pkg/types/types.go`** — Tipos básicos (Request/Response) 2. **`internal/config/config.go`** — Carga de config desde yaml/env 3. **`internal/output/output.go`** — Formatter JSON/Text 4. **`internal/api/client.go`** — HTTP client con auth 5. **`internal/auth/auth.go`** — Login, logout, JWT 6. **`cobra/commands.go`** — Estructura de comandos 7. **`cmd/claudia-docs/main.go`** — Entry point + root command 8. **`internal/api/*.go`** — Cada recurso (documents, projects, folders, tags, search, reasoning) ### Paso 4: Testing manual ```bash # Build go build -o claudia-docs ./cmd/claudia-docs # Login ./claudia-docs auth login -u admin -p admin123 # Probar commands ./claudia-docs auth status ./claudia-docs project list ./claudia-docs doc create -t "Test" -c "# Hello" -p ./claudia-docs doc list --project-id ``` --- ## 6. API Endpoints a Consumir Base URL: `${CLAUDIA_SERVER}/api/v1` ### Auth ``` POST /auth/register POST /auth/login → { access_token } GET /auth/me ``` ### Projects ``` GET /projects POST /projects GET /projects/:id PUT /projects/:id DELETE /projects/:id ``` ### Documents ``` GET /projects/:projectId/documents POST /projects/:projectId/documents GET /documents/:id PUT /documents/:id DELETE /documents/:id PUT /documents/:id/content ``` ### Folders ``` GET /projects/:projectId/folders POST /projects/:projectId/folders GET /folders/:id PUT /folders/:id DELETE /folders/:id ``` ### Tags ``` GET /tags POST /tags POST /documents/:id/tags DELETE /documents/:id/tags/:tagId ``` ### Search ``` GET /search?q=...&project_id=...&tags=... ``` ### Reasoning ``` PUT /documents/:id/reasoning GET /documents/:id/reasoning ``` **Ver spec del backend para Request/Response bodies exactos.** --- ## 7. Formato de Output ### JSON Response Structure ```go type Response struct { Success bool `json:"success"` Data interface{} `json:"data,omitempty"` Error *ErrorInfo `json:"error,omitempty"` Meta MetaInfo `json:"meta"` } type ErrorInfo struct { Code string `json:"code"` Message string `json:"message"` } type MetaInfo struct { Command string `json:"command"` DurationMs int64 `json:"duration_ms"` Server string `json:"server,omitempty"` } ``` ### Comportamiento - **Success:** `{"success": true, "data": {...}, "meta": {...}}` - **Error:** `{"success": false, "error": {"code": "...", "message": "..."}, "meta": {...}}` - **--quiet:** Solo JSON, sin prints a stdout - **--output text:** Print amigable para humanos --- ## 8. Config File Path: `~/.claudia-docs.yaml` ```yaml server: http://localhost:8000 token: "" timeout: 30s output: json agents: default: token: "" default_project: "" ``` **Viper maneja优先级:** 1. Flags (--server, --token) 2. Environment (CLAUDIA_SERVER, CLAUDIA_TOKEN) 3. Config file (~/.claudia-docs.yaml) 4. Defaults --- ## 9. Testing Checklist ### Auth - [ ] Login exitoso guarda token en config - [ ] Login con credenciales inválidas retorna error - [ ] Logout limpia token - [ ] Commands sin token retornan 401 ### Documents - [ ] Create documento retorna id - [ ] List retorna array de documentos - [ ] Get retorna documento con contenido - [ ] Update cambia título/contenido - [ ] Delete elimina documento ### Projects/Folders - [ ] CRUD completo funciona ### Search - [ ] Búsqueda retorna resultados - [ ] Filtros por proyecto/tag funcionan ### Output - [ ] JSON output es válido - [ ] --output text muestra formato legible - [ ] --quiet solo imprime JSON --- ## 10. Build & Release ### Build local ```bash # Linux GOOS=linux GOARCH=amd64 go build -o claudia-docs-linux-amd64 ./cmd/claudia-docs # macOS GOOS=darwin GOARCH=amd64 go build -o claudia-docs-darwin-amd64 ./cmd/claudia-docs # Windows GOOS=windows GOARCH=amd64 go build -o claudia-docs-windows-amd64.exe ./cmd/claudia-docs ``` ### Release script (para después) ```bash # Generar checksums sha256sum claudia-docs-* > checksums.txt # Tag y release en Git git tag v1.0.0 git push origin v1.0.0 ``` --- ## 11. Criterios de Aceptación ### Must Have (MVP) - [ ] `claudia-docs auth login` funciona y guarda token - [ ] `claudia-docs auth logout` limpia token - [ ] `claudia-docs auth status` muestra estado - [ ] `claudia-docs doc create` crea documento - [ ] `claudia-docs doc list` lista documentos - [ ] `claudia-docs doc get` obtiene documento - [ ] `claudia-docs doc update` actualiza documento - [ ] `claudia-docs doc delete` elimina documento - [ ] `claudia-docs project list` lista proyectos - [ ] Output JSON es parseable - [ ] Config file ~/.claudia-docs.yaml se crea - [ ] Flags --server y --token funcionan - [ ] Help con --help funciona ### Should Have (Phase 2) - [ ] Tags CRUD - [ ] Search - [ ] Reasoning save - [ ] --output text --- ## 12. Contacto para Dudas **Para preguntas sobre el diseño o specs:** - Crear issue en el proyecto - O preguntar directamente **Para preguntas sobre implementación:** - Si hay ambigüedad en el spec, preguntar antes de asumir --- ## 13. Enlaces - Spec CLI: `/projects/claudia-docs-cli/SPEC.md` - Spec Backend: `/projects/claudia-docs/SPEC.md` - Backend API Docs: `http://localhost:8000/docs` (si backend corriendo) --- **¡Happy coding! 🚀**