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)

# En /projects/claudia-docs/
docker-compose up -d
# API disponible en http://localhost:8000
# Swagger: http://localhost:8000/docs

Credenciales de test

INITIAL_ADMIN_USERNAME=admin
INITIAL_ADMIN_PASSWORD=admin123

Variables de entorno para testing

export CLAUDIA_SERVER=http://localhost:8000
export CLAUDIA_TOKEN=""

---

5. Implementación Paso a Paso

Paso 1: Setup del proyecto

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

# 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

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

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

# 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)

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