Initial MVP implementation of Claudia Docs CLI
- Auth commands: login, logout, status - Document commands: create, list, get, update, delete - Project commands: list, get - Folder commands: list, create - Tag commands: list, create, add - Search command - Reasoning save command - JSON output format with --output text option - Viper-based configuration management - Cobra CLI framework
This commit is contained in:
Claudia CLI Bot
371
HANDOFF.md
Normal file
371
HANDOFF.md
Normal file
@@ -0,0 +1,371 @@
|
||||
# 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 <project-id>
|
||||
./claudia-docs doc list --project-id <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! 🚀**
|
||||
Reference in New Issue
Block a user