outiline-mcp/openspec/changes/split-main-into-files/design.md

Design: split-main-into-files

Context

El proyecto outline-mcp vive íntegramente en main.go (425 líneas, paquete main), según la decisión D2 del change create-outline-mcp-server, que explícitamente anticipaba la extracción a múltiples archivos como refactor futuro. El archivo mezcla tres dominios independientes (cliente HTTP de Outline, handlers de tools MCP, auto-update vía Gitea). No hay tests aún; la verificación actual es go build, golangci-lint run y prueba manual por stdio.

Goals / Non-Goals

Goals:

• Repartir main.go en archivos por responsabilidad dentro del mismo paquete main, sin ningún cambio de comportamiento.
• Dejar el código preparado para añadir tests y nuevas tools sin fricción.
• Cumplir la promesa de D2: extracción sin impacto en specs de comportamiento ni en el pipeline de release.

Non-Goals:

• Introducir paquetes internal/ (descartado: no hay necesidad de ocultar API entre dominios con el alcance actual).
• Añadir tests (cambio posterior; solo se deja el terreno listo).
• Renombrar o refactorizar funciones, tipos o lógica.
• Modificar go.mod, dependencias, pipeline de release o contrato de nombres de assets.

Decisions

D1: Múltiples archivos en paquete main (opción B) frente a internal/ (opción C)

• Elección: dividir en archivos del mismo paquete main. Estructura resultante:
  • main.go — función main(), variables de build (Version, GiteaURL, RepoOwner, RepoName) y registro de tools.
  • client.go — tipo OutlineClient, newOutlineClient, método post.
  • tools.go — los cuatro handlers de tools MCP.
  • updater.go — giteaRelease, parseVersion, versionNewer, doUpdate.
• Alternativa (internal/outline, internal/tools, internal/selfupdate): descartada porque obliga a decidir superficie exportada acoplando los handlers al SDK (mcp.CallToolResult en firmas) y no aporta ocultación real con el alcance actual. Queda como refactor futuro si el número de tools crece de forma significativa.
• Alternativa (mantener un solo archivo): descartada; el argumento de bootstrap de D2 ya se cumplió y la mezcla de dominios penaliza la legibilidad y los futuros diffs.

D2 (revisión): se actualiza la decisión del change create-outline-mcp-server

La D2 original ("todo el código en main.go") queda sustituida por esta organización multi-archivo en paquete único. El carácter de monolito deliberado (un único binario, un único paquete) se mantiene; lo que cambia es la distribución física en archivos.

D3: Movimiento mecánico de código, sin reescritura

Las funciones y tipos se trasladan íntegras (mismos nombres, firmas, comentarios y directivas //nolint). Solo se ajustan los bloques import de cada archivo nuevo. Esto minimiza el riesgo del refactor y hace el diff auditable como puro movimiento.

D4: Las variables de build permanecen en main.go

Version, GiteaURL, RepoOwner y RepoName se inyectan con -ldflags -X main.Version=... y el paquete sigue siendo main, por lo que no hay razón para moverlas. Permanecen junto al entrypoint, que es su punto natural de referencia.

Risks / Trade-offs

• [División incorrecta de imports causa fallo de compilación] → Verificación inmediata con go build ./... en el contenedor tras cada movimiento; es un error de compilación, no un error silencioso.
• [golangci-lint señala imports sin usar o duplicados] → Ejecutar golangci-lint run en el contenedor como parte de la verificación.
• [Confusión temporal por familiaridad con el archivo único] → El diff es puro movimiento de código; los nombres de archivo (client.go, tools.go, updater.go) se corresponden directamente con los dominios.
• [Regresión funcional no detectada por compilación] → Prueba manual por stdio del servidor MCP (handshake + tools/list) tras el refactor, igual que en el change original.

Migration Plan

1. Crear los tres archivos nuevos moviendo bloques completos desde main.go.
2. Reducir main.go a entrypoint + variables de build + registro de tools.
3. Compilar, lintear y probar por stdio en el contenedor DevPod.
4. Rollback trivial: git revert del commit único del refactor.

Open Questions

(ninguna)