From c3db1cd425ddf73b105fa41b6c6cdfd97e4c7c67 Mon Sep 17 00:00:00 2001 From: Snider Date: Sat, 14 Mar 2026 09:36:07 +0000 Subject: [PATCH] docs: add core/api polyglot merge design spec Merge core/go-api + core/php-api into core/api. Same pattern as core/mcp polyglot repo. Co-Authored-By: Virgil --- .../2026-03-14-api-polyglot-merge-design.md | 154 ++++++++++++++++++ 1 file changed, 154 insertions(+) create mode 100644 docs/superpowers/specs/2026-03-14-api-polyglot-merge-design.md diff --git a/docs/superpowers/specs/2026-03-14-api-polyglot-merge-design.md b/docs/superpowers/specs/2026-03-14-api-polyglot-merge-design.md new file mode 100644 index 0000000..d31a939 --- /dev/null +++ b/docs/superpowers/specs/2026-03-14-api-polyglot-merge-design.md @@ -0,0 +1,154 @@ +# core/api Polyglot Merge — Go + PHP API in One Repo + +**Date:** 2026-03-14 +**Status:** Approved +**Pattern:** Same as core/mcp merge (2026-03-09) + +## Problem + +The API layer is split across two repos: +- `core/go-api` — Gin REST framework, OpenAPI, ToolBridge, SDK codegen, WS/SSE +- `core/php-api` — Laravel REST module, rate limiting, webhooks, OAuth, API docs + +These serve the same purpose in their respective stacks. The provider framework +(previous spec) needs a single `core/api` that both Go and PHP packages register +into. Same problem core/mcp solved by merging. + +## Solution + +Merge both into `core/api` (`ssh://git@forge.lthn.ai:2223/core/api.git`), +following the exact pattern established by core/mcp. + +## Target Structure + +``` +core/api/ +├── go.mod # module forge.lthn.ai/core/api +├── composer.json # name: lthn/api +├── .gitattributes # export-ignore Go files for Composer +├── CLAUDE.md +├── pkg/ # Go packages +│ ├── api/ # Engine, RouteGroup, middleware (from go-api root) +│ ├── provider/ # Provider framework (new, from previous spec) +│ └── openapi/ # SpecBuilder, codegen (from go-api root) +├── cmd/ +│ └── core-api/ # Standalone binary (if needed) +├── src/ +│ └── php/ +│ └── src/ +│ ├── Api/ # Boot, Controllers, Middleware, etc. (from php-api/src/Api/) +│ ├── Front/Api/ # Frontend API routes (from php-api/src/Front/) +│ └── Website/Api/ # Website API routes (from php-api/src/Website/) +└── docs/ +``` + +## Go Module + +```go +module forge.lthn.ai/core/api +``` + +All current consumers importing `forge.lthn.ai/core/go-api` will need to update +to `forge.lthn.ai/core/api/pkg/api` (or `forge.lthn.ai/core/api` if we keep +packages at root level — see decision below). + +### Package Layout Decision + +**Option A**: Packages under `pkg/api/` — clean but changes all import paths. +**Option B**: Packages at root (like go-api currently) — no import path change +if module path stays `forge.lthn.ai/core/api`. + +**Recommendation: B** — keep Go files at repo root. The module path changes from +`forge.lthn.ai/core/go-api` to `forge.lthn.ai/core/api`. This is a one-line +change in each consumer's import. The PHP code lives under `src/php/` and +doesn't conflict. + +``` +core/api/ +├── api.go, group.go, openapi.go, ... # Go source at root (same as go-api today) +├── pkg/provider/ # New provider framework +├── cmd/core-api/ # Binary +├── src/php/ # PHP source +├── composer.json +├── go.mod +└── .gitattributes +``` + +## Composer Package + +```json +{ + "name": "lthn/api", + "autoload": { + "psr-4": { + "Core\\Api\\": "src/php/src/Api/", + "Core\\Website\\Api\\": "src/php/src/Website/Api/" + } + }, + "replace": { + "lthn/php-api": "self.version", + "core/php-api": "self.version" + } +} +``` + +Note: No `Core\Front\Api\` namespace — php-api has no `src/Front/` directory. +Add it later if a frontend API boot provider is needed. + +## .gitattributes + +Same pattern as core/mcp — exclude Go files from Composer installs: + +``` +*.go export-ignore +go.mod export-ignore +go.sum export-ignore +cmd/ export-ignore +pkg/ export-ignore +.core/ export-ignore +src/php/tests/ export-ignore +``` + +## Migration Steps + +1. **Clone core/api** (empty repo, just created) +2. **Copy Go code** from go-api → core/api root (all .go files, cmd/, docs/) +3. **Copy PHP code** from php-api/src/ → core/api/src/php/src/ +4. **Copy PHP config** — composer.json, phpunit.xml, tests +5. **Update go.mod** — change module path to `forge.lthn.ai/core/api` +6. **Create .gitattributes** — export-ignore Go files +7. **Create composer.json** — lthn/api with PSR-4 autoload +8. **Update consumers** — sed import paths in all repos that import go-api +9. **Add provider framework** — `pkg/provider/` from the previous spec +10. **Archive go-api and php-api** on forge (keep for backward compat period) + +## Consumer Updates + +Repos that import `forge.lthn.ai/core/go-api`: +- core/go-ai (ToolBridge, API routes) +- core/go-ml (API route group) +- core/mcp (bridge.go) +- core/agent (indirect, v0.0.3) +- core/ide (via provider framework) + +Each needs: `s/forge.lthn.ai\/core\/go-api/forge.lthn.ai\/core\/api/g` in +imports and go.mod. + +PHP consumers via Composer — update `lthn/php-api` → `lthn/api` in +composer.json. Namespace stays `Core\Api\` (unchanged). + +## Go Workspace + +Add `core/api` to `~/Code/go.work`, remove `core/go-api` entry. + +## Testing + +- `go test ./...` in core/api +- `composer test` in core/api (runs PHP tests via phpunit) +- Build verification across consumer repos after import path update + +## Not In Scope + +- Provider framework implementation (separate spec, separate plan) +- New API features — this is a structural merge only +- TypeScript API layer (future Phase 3)