claudia-docs-cli/HANDOFF.md

# 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! 🚀**