48 lines
2.3 KiB
Markdown
48 lines
2.3 KiB
Markdown
# AGENTS.md
|
|
|
|
## Ejecución de comandos Go — OBLIGATORIO vía Docker
|
|
|
|
**No hay Go ni agentes instalados en el host (macOS).** Todos los comandos Go/lint/build se ejecutan dentro del contenedor DevPod:
|
|
|
|
```bash
|
|
# Resolver el nombre del contenedor (es auto-generado, puede cambiar):
|
|
docker ps --filter ancestor=mcr.microsoft.com/devcontainers/go --format '{{.Names}}'
|
|
|
|
# Ejecutar comandos dentro (workspace montado en /workspaces/outline-mcp):
|
|
docker exec <container> sh -c "cd /workspaces/outline-mcp && go build ./..."
|
|
```
|
|
|
|
- El nombre actual es `great_jang`, pero NO asumirlo: resolverlo con `docker ps` cada sesión.
|
|
- Las ediciones de archivos se hacen en el host (ruta normal del repo); solo la ejecución va por `docker exec`.
|
|
- `openspec` CLI se ejecuta en el **host** (no está en el contenedor).
|
|
|
|
## Toolchain
|
|
|
|
- Go 1.26 (imagen `mcr.microsoft.com/devcontainers/go:1-trixie`). NO bajar a 1.22: `mcp-go` v1.0.0 requiere Go ≥ 1.25.5.
|
|
- `golangci-lint` v2 solo dentro del contenedor.
|
|
- Módulo: `outline-mcp`. Todo el código en `main.go` (decisión de diseño D2: monolito deliberado).
|
|
|
|
## Build y verificación
|
|
|
|
```bash
|
|
# Dentro del contenedor:
|
|
go build -o outline-mcp .
|
|
go build -ldflags "-X main.Version=v0.0.1-dev -X main.GiteaURL=https://gitea.example.com -X main.RepoOwner=owner -X main.RepoName=outline-mcp" -o outline-mcp .
|
|
golangci-lint run
|
|
# Ver tools/list del servidor MCP (handshake + listing por stdio):
|
|
printf '{"jsonrpc":"2.0","id":1,"method":"initialize",...}' | ./outline-mcp
|
|
```
|
|
|
|
Sin tests aún; verificación = `go build` + `golangci-lint run` + prueba manual por stdio.
|
|
|
|
## Contrato crítico: nombres de assets
|
|
|
|
El pipeline de release (`.gitea/workflows/release.yml`) y el auto-update (`doUpdate` en main.go) comparten un contrato implícito: los assets DEBEN llamarse `outline-mcp_{GOOS}_{GOARCH}` (con `.exe` para windows). Cambiar una parte rompe la otra.
|
|
|
|
## Convenciones del repo
|
|
|
|
- Artefactos OpenSpec (`openspec/changes/*/`) en **español**, tono formal; tasks con formato Given/When/Than (regla de `openspec/config.yaml`).
|
|
- Flujo: `openspec new change` → proposal → specs → design → tasks → implementar marcando checkboxes en `tasks.md`.
|
|
- Errores de configuración (`OUTLINE_URL`, `OUTLINE_API_KEY`) se devuelven como resultado MCP de error, nunca panic.
|
|
- La API key de Outline nunca se loguea.
|