From 12ff432d6b2db203f30b84d7351ca3027f98481d Mon Sep 17 00:00:00 2001 From: Snider Date: Sun, 22 Feb 2026 23:45:56 +0000 Subject: [PATCH] docs: archive completed plans with summaries Move completed plan documents to docs/plans/completed/ with concise completion summaries alongside the originals. Archived: MCP integration, Go API design/plan, CLI meta-package design. Co-Authored-By: Claude Opus 4.6 --- .../2026-02-05-mcp-integration-original.md} | 0 .../2026-02-20-go-api-design-original.md} | 0 .../2026-02-20-go-api-plan-original.md} | 0 ...02-21-cli-meta-package-design-original.md} | 0 docs/plans/completed/cli-meta-package.md | 30 ++++++++++ docs/plans/completed/go-api.md | 57 +++++++++++++++++++ docs/plans/completed/mcp-integration.md | 37 ++++++++++++ 7 files changed, 124 insertions(+) rename docs/plans/{2026-02-05-mcp-integration.md => completed/2026-02-05-mcp-integration-original.md} (100%) rename docs/plans/{2026-02-20-go-api-design.md => completed/2026-02-20-go-api-design-original.md} (100%) rename docs/plans/{2026-02-20-go-api-plan.md => completed/2026-02-20-go-api-plan-original.md} (100%) rename docs/plans/{2026-02-21-cli-meta-package-design.md => completed/2026-02-21-cli-meta-package-design-original.md} (100%) create mode 100644 docs/plans/completed/cli-meta-package.md create mode 100644 docs/plans/completed/go-api.md create mode 100644 docs/plans/completed/mcp-integration.md diff --git a/docs/plans/2026-02-05-mcp-integration.md b/docs/plans/completed/2026-02-05-mcp-integration-original.md similarity index 100% rename from docs/plans/2026-02-05-mcp-integration.md rename to docs/plans/completed/2026-02-05-mcp-integration-original.md diff --git a/docs/plans/2026-02-20-go-api-design.md b/docs/plans/completed/2026-02-20-go-api-design-original.md similarity index 100% rename from docs/plans/2026-02-20-go-api-design.md rename to docs/plans/completed/2026-02-20-go-api-design-original.md diff --git a/docs/plans/2026-02-20-go-api-plan.md b/docs/plans/completed/2026-02-20-go-api-plan-original.md similarity index 100% rename from docs/plans/2026-02-20-go-api-plan.md rename to docs/plans/completed/2026-02-20-go-api-plan-original.md diff --git a/docs/plans/2026-02-21-cli-meta-package-design.md b/docs/plans/completed/2026-02-21-cli-meta-package-design-original.md similarity index 100% rename from docs/plans/2026-02-21-cli-meta-package-design.md rename to docs/plans/completed/2026-02-21-cli-meta-package-design-original.md diff --git a/docs/plans/completed/cli-meta-package.md b/docs/plans/completed/cli-meta-package.md new file mode 100644 index 0000000..d88672b --- /dev/null +++ b/docs/plans/completed/cli-meta-package.md @@ -0,0 +1,30 @@ +# CLI Meta-Package Restructure — Completed + +**Completed:** 22 Feb 2026 + +## What Was Done + +`pkg/cli` was extracted from `core/go` into its own Go module at `forge.lthn.ai/core/cli`. This made the CLI SDK a first-class, independently versioned package rather than a subdirectory of the Go foundation repo. + +Following the extraction, an ecosystem-wide import path migration updated all consumers from the old path to the new one: + +- Old: `forge.lthn.ai/core/go/pkg/cli` +- New: `forge.lthn.ai/core/cli/pkg/cli` + +## Scope + +- **147+ files** updated across **10 repos** +- All repos build clean after migration + +## Repos Migrated + +`core/cli`, `core/go`, `go-devops`, `go-ai`, `go-agentic`, `go-crypt`, `go-rag`, `go-scm`, `go-api`, `go-update` + +## Key Outcomes + +- `forge.lthn.ai/core/cli/pkg/cli` is the single import for all CLI concerns across the ecosystem +- Domain repos are insulated from cobra, lipgloss, and bubbletea — only `pkg/cli` imports them +- Command registration uses the Core framework lifecycle via `cli.WithCommands()` — no `init()`, no global state +- `core/cli` is a thin assembly repo (~2K LOC) with 7 meta packages; all business logic lives in domain repos +- Variant binary pattern established: multiple `main.go` files can wire different `WithCommands` sets for targeted binaries (core-ci, core-mlx, core-ops, etc.) +- Command migration from the old `core/cli` monolith to domain repos was completed in full (13 command groups moved) diff --git a/docs/plans/completed/go-api.md b/docs/plans/completed/go-api.md new file mode 100644 index 0000000..86278a2 --- /dev/null +++ b/docs/plans/completed/go-api.md @@ -0,0 +1,57 @@ +# go-api — Completion Summary + +**Completed:** 21 February 2026 +**Module:** `forge.lthn.ai/core/go-api` +**Status:** Phases 1–3 complete, 176 tests passing + +## What Was Built + +### Phase 1 — Core Framework (20 Feb 2026) + +Gin-based HTTP engine with extensible middleware via `With*()` options. Key components: + +- `RouteGroup` / `StreamGroup` interfaces — subsystems register their own endpoints +- `Response[T]` envelope — `OK()`, `Fail()`, `Paginated()` generics +- `Engine` — `New()`, `Register()`, `Handler()`, `Serve()` with graceful shutdown +- Bearer auth, request ID, and CORS middleware +- WebSocket endpoint wrapping a `go-ws` Hub +- Swagger UI at `/swagger/` with runtime spec serving +- `/health` endpoint always available without auth +- First integration proof in `go-ml/api/` (3 endpoints, 12 tests) + +### Phase 2 — Gin Plugin Stack (20–21 Feb 2026) + +17 middleware plugins added across four waves, all as drop-in `With*()` options: + +| Wave | Plugins | +|------|---------| +| 1 — Gateway hardening | Authentik (OIDC + forward auth), secure headers, structured slog, timeouts, gzip, static files | +| 2 — Performance + auth | Brotli compression, in-memory response cache, server-side sessions, Casbin RBAC | +| 3 — Network + streaming | HTTP signature verification, SSE broker, reverse proxy detection, i18n locale, GraphQL | +| 4 — Observability | pprof, expvar, OpenTelemetry distributed tracing | + +### Phase 3 — OpenAPI + SDK Codegen (21 Feb 2026) + +Runtime spec generation (not swaggo annotations — incompatible with dynamic RouteGroups and `Response[T]` generics): + +- `DescribableGroup` interface — opt-in OpenAPI metadata for route groups +- `ToolBridge` — converts MCP tool descriptors into `POST /{tool_name}` REST endpoints +- `SpecBuilder` — assembles full OpenAPI 3.1 JSON from registered groups at runtime +- Spec export to JSON and YAML (`core api spec`) +- SDK codegen wrapper for openapi-generator-cli, 11 languages (`core api sdk --lang go`) +- `go-ai` `mcp/registry.go` — generic `addToolRecorded[In,Out]` captures types in closures +- `go-ai` `mcp/bridge.go` — `BridgeToAPI()` populates ToolBridge from MCP tool registry +- CLI commands: `core api spec`, `core api sdk` (in `core/cli` dev branch) + +## Key Outcomes + +- **176 tests** across go-api (143), go-ai bridge (10), and CLI commands (4), all passing +- Zero internal ecosystem dependencies — subsystems import go-api, not the reverse +- Authentik (OIDC) and bearer token auth coexist; Casbin adds RBAC on top +- Four-protocol access pattern established: REST, GraphQL, WebSocket, MCP — same handlers + +## Known Limitations + +- Subsystem MCP tools registered via `mcp.AddTool` directly are excluded from the REST bridge (only the 10 built-in tools appear). Fix: pass `*Service` to `RegisterTools` instead of `*mcp.Server`. +- `structSchema` reflection handles flat structs only; nested structs are not recursed. +- `core api spec` currently emits a spec with only `/health`; full MCP wiring into the CLI command is pending. diff --git a/docs/plans/completed/mcp-integration.md b/docs/plans/completed/mcp-integration.md new file mode 100644 index 0000000..7edf86e --- /dev/null +++ b/docs/plans/completed/mcp-integration.md @@ -0,0 +1,37 @@ +# MCP Integration — Completion Summary + +**Completed:** 2026-02-05 +**Plan:** `docs/plans/2026-02-05-mcp-integration.md` + +## What Was Built + +### RAG Tools (`pkg/mcp/tools_rag.go`) +Three MCP tools added to the existing `pkg/mcp` server: +- `rag_query` — semantic search against Qdrant vector DB +- `rag_ingest` — ingest a file or directory into a named collection +- `rag_collections` — list available Qdrant collections (with optional stats) + +### Metrics Tools (`pkg/mcp/tools_metrics.go`) +Two MCP tools for agent activity tracking: +- `metrics_record` — write a typed event (agent_id, repo, arbitrary data) to JSONL storage +- `metrics_query` — query events with aggregation by type, repo, and agent; supports human-friendly duration strings (7d, 24h) + +Also added `parseDuration()` helper for "Nd"/"Nh"/"Nm" duration strings. + +### `core mcp serve` Command (`internal/cmd/mcpcmd/cmd_mcp.go`) +New CLI sub-command registered via `cli.WithCommands()` (not `init()`). +- Runs `pkg/mcp` server over stdio by default +- TCP mode via `MCP_ADDR=:9000` environment variable +- `--workspace` flag to restrict file operations to a directory + +Registered in the full CLI variant. i18n strings added for all user-facing text. + +### Plugin Configuration +`.mcp.json` created for the `agentic-flows` Claude Code plugin, pointing to `core mcp serve`. Exposes all 15 tools to Claude Code agents via the `core-cli` MCP server name. + +## Key Outcomes + +- `core mcp serve` is the single entry point for all MCP tooling (file ops, RAG, metrics, language detection, process management, WebSocket, webview/CDP) +- MCP command moved to `go-ai/cmd/mcpcmd/` in final form; the plan's `internal/cmd/mcpcmd/` path reflects the pre-extraction location +- Registration pattern updated from `init()` + `RegisterCommands()` to `cli.WithCommands()` lifecycle hooks +- Services required at runtime: Qdrant (localhost:6333), Ollama with nomic-embed-text (localhost:11434)