Merge pull request #624 from pitabwire/openapi-static

feat(openapi): compile-time specs and scaffolding tools

Author: pitabwire

.github/workflows/gemini-pr-review.yml

@@ -154,6 +154,7 @@ jobs:
       - name: 'Run Gemini PR Review'
         uses: 'google-github-actions/run-gemini-cli@v0'
         id: 'gemini_pr_review'
+        continue-on-error: true
         env:
           GITHUB_TOKEN: '${{ steps.generate_token.outputs.token || secrets.GITHUB_TOKEN }}'
           PR_NUMBER: '${{ steps.get_pr.outputs.pr_number || steps.get_pr_comment.outputs.pr_number }}'

.github/workflows/golangci-lint.yml

@@ -15,11 +15,13 @@ jobs:
       - uses: actions/checkout@v6.0.2
       - name: golangci-lint
         uses: golangci/golangci-lint-action@v9
+        env:
+          GOLANGCI_LINT_CACHE: /tmp/golangci-lint
         with:
           # Optional: version of golangci-lint to use in form of v1.2 or v1.2.3 or `latest` to use the latest version
           version: latest
           args: --timeout=5m
-          skip-cache: false
+          skip-cache: true
 
           # Optional: working directory, useful for monorepos
           # working-directory: somedir
@@ -37,4 +39,4 @@ jobs:
           # skip-pkg-cache: true
 
           # Optional: if set to true then the action don't cache or restore ~/.cache/go-build.
-          # skip-build-cache: true
+          # skip-build-cache: true

blueprint/blueprint.go

@@ -0,0 +1,33 @@
+package blueprint
+
+type Blueprint struct {
+	Service string      `json:"service" yaml:"service"`
+	HTTP    []HTTPRoute `json:"http"    yaml:"http"`
+	Plugins []Plugin    `json:"plugins" yaml:"plugins"`
+	Queues  []Queue     `json:"queues"  yaml:"queues"`
+}
+
+type HTTPRoute struct {
+	Name     string `json:"name"     yaml:"name"`
+	Method   string `json:"method"   yaml:"method"`
+	Route    string `json:"route"    yaml:"route"`
+	Handler  string `json:"handler"  yaml:"handler"`
+	Override bool   `json:"override" yaml:"override"`
+	Remove   bool   `json:"remove"   yaml:"remove"`
+}
+
+type Plugin struct {
+	Name     string            `json:"name"     yaml:"name"`
+	Config   map[string]string `json:"config"   yaml:"config"`
+	Override bool              `json:"override" yaml:"override"`
+	Remove   bool              `json:"remove"   yaml:"remove"`
+}
+
+type Queue struct {
+	Name       string `json:"name"       yaml:"name"`
+	Publisher  string `json:"publisher"  yaml:"publisher"`
+	Subscriber string `json:"subscriber" yaml:"subscriber"`
+	Topic      string `json:"topic"      yaml:"topic"`
+	Override   bool   `json:"override"   yaml:"override"`
+	Remove     bool   `json:"remove"     yaml:"remove"`
+}

blueprint/merge.go

@@ -0,0 +1,111 @@
+package blueprint
+
+import "fmt"
+
+func Merge(base, overlay Blueprint) (Blueprint, error) {
+	out := base
+
+	if overlay.Service != "" {
+		if out.Service == "" {
+			out.Service = overlay.Service
+		} else if out.Service != overlay.Service {
+			return Blueprint{}, fmt.Errorf("service mismatch: base %q overlay %q", out.Service, overlay.Service)
+		}
+	}
+
+	out.HTTP = mergeHTTP(out.HTTP, overlay.HTTP)
+	out.Plugins = mergePlugins(out.Plugins, overlay.Plugins)
+	out.Queues = mergeQueues(out.Queues, overlay.Queues)
+
+	return out, nil
+}
+
+func mergeHTTP(base, overlay []HTTPRoute) []HTTPRoute {
+	return mergeList(
+		base,
+		overlay,
+		func(item HTTPRoute) string { return item.Name },
+		func(_ HTTPRoute, src HTTPRoute) HTTPRoute { return src },
+		func(item HTTPRoute) bool { return item.Override },
+		func(item HTTPRoute) bool { return item.Remove },
+	)
+}
+
+func mergePlugins(base, overlay []Plugin) []Plugin {
+	return mergeList(
+		base,
+		overlay,
+		func(item Plugin) string { return item.Name },
+		func(_ Plugin, src Plugin) Plugin { return src },
+		func(item Plugin) bool { return item.Override },
+		func(item Plugin) bool { return item.Remove },
+	)
+}
+
+func mergeQueues(base, overlay []Queue) []Queue {
+	return mergeList(
+		base,
+		overlay,
+		func(item Queue) string { return item.Name },
+		func(_ Queue, src Queue) Queue { return src },
+		func(item Queue) bool { return item.Override },
+		func(item Queue) bool { return item.Remove },
+	)
+}
+
+type keyFunc[T any] func(T) string
+type replaceFunc[T any] func(dst, src T) T
+
+type flagFunc[T any] func(T) bool
+
+func mergeList[T any](
+	base, overlay []T,
+	key keyFunc[T],
+	replace replaceFunc[T],
+	override flagFunc[T],
+	remove flagFunc[T],
+) []T {
+	index := make(map[string]int, len(base))
+	out := make([]T, 0, len(base)+len(overlay))
+	for i, item := range base {
+		k := key(item)
+		if k == "" {
+			continue
+		}
+		index[k] = len(out)
+		out = append(out, item)
+		_ = i
+	}
+
+	for _, item := range overlay {
+		k := key(item)
+		if k == "" {
+			continue
+		}
+		if remove(item) {
+			if idx, ok := index[k]; ok {
+				out[idx] = *new(T)
+				delete(index, k)
+			}
+			continue
+		}
+		if idx, ok := index[k]; ok {
+			if override(item) {
+				out[idx] = replace(out[idx], item)
+			}
+			continue
+		}
+		index[k] = len(out)
+		out = append(out, item)
+	}
+
+	// Compact removed items
+	clean := out[:0]
+	for _, item := range out {
+		if key(item) == "" {
+			continue
+		}
+		clean = append(clean, item)
+	}
+	return clean
+}

blueprint/merge_test.go

@@ -0,0 +1,89 @@
+package blueprint_test
+
+import (
+	"testing"
+
+	"github.com/pitabwire/frame/blueprint"
+)
+
+func TestMerge_Additive(t *testing.T) {
+	base := blueprint.Blueprint{
+		Service: "users",
+		HTTP: []blueprint.HTTPRoute{
+			{Name: "list", Method: "GET", Route: "/users", Handler: "List"},
+		},
+		Plugins: []blueprint.Plugin{{Name: "logging"}},
+	}
+	overlay := blueprint.Blueprint{
+		HTTP: []blueprint.HTTPRoute{
+			{Name: "create", Method: "POST", Route: "/users", Handler: "Create"},
+		},
+		Plugins: []blueprint.Plugin{{Name: "metrics"}},
+	}
+
+	out, err := blueprint.Merge(base, overlay)
+	if err != nil {
+		t.Fatalf("merge: %v", err)
+	}
+
+	if len(out.HTTP) != 2 {
+		t.Fatalf("expected 2 routes, got %d", len(out.HTTP))
+	}
+	if len(out.Plugins) != 2 {
+		t.Fatalf("expected 2 plugins, got %d", len(out.Plugins))
+	}
+}
+
+func TestMerge_Override(t *testing.T) {
+	base := blueprint.Blueprint{
+		HTTP: []blueprint.HTTPRoute{
+			{Name: "list", Method: "GET", Route: "/users", Handler: "List"},
+		},
+	}
+	overlay := blueprint.Blueprint{
+		HTTP: []blueprint.HTTPRoute{
+			{Name: "list", Method: "GET", Route: "/users", Handler: "ListV2", Override: true},
+		},
+	}
+
+	out, err := blueprint.Merge(base, overlay)
+	if err != nil {
+		t.Fatalf("merge: %v", err)
+	}
+
+	if out.HTTP[0].Handler != "ListV2" {
+		t.Fatalf("expected override to apply")
+	}
+}
+
+func TestMerge_Remove(t *testing.T) {
+	base := blueprint.Blueprint{
+		HTTP: []blueprint.HTTPRoute{
+			{Name: "list", Method: "GET", Route: "/users", Handler: "List"},
+		},
+	}
+	overlay := blueprint.Blueprint{
+		HTTP: []blueprint.HTTPRoute{
+			{Name: "list", Remove: true},
+		},
+	}
+
+	out, err := blueprint.Merge(base, overlay)
+	if err != nil {
+		t.Fatalf("merge: %v", err)
+	}
+
+	if len(out.HTTP) != 0 {
+		t.Fatalf("expected route removed, got %d", len(out.HTTP))
+	}
+}
+
+func TestMerge_ServiceMismatch(t *testing.T) {
+	base := blueprint.Blueprint{Service: "users"}
+	overlay := blueprint.Blueprint{Service: "billing"}
+
+	_, err := blueprint.Merge(base, overlay)
+	if err == nil {
+		t.Fatalf("expected mismatch error")
+	}
+}

docs/ai-assistants.md

@@ -24,19 +24,36 @@ This is the canonical pattern that matches Frame’s API.
 
 ```text
 /cmd/myservice/main.go
-/internal/handlers/...
-/internal/plugins/...
-/internal/clients/...
+/pkg/handlers/...
+/pkg/plugins/...
+/pkg/clients/...
+/pkg/openapi/...
 /configs/...
 ```
 
+For monorepos, prefer:
+
+```text
+/cmd
+  /monolith
+  /users
+  /billing
+/apps
+  /users
+  /billing
+/pkg
+  /plugins
+  /openapi
+```
+
 ## How to Ask AI for Frame Code
 
 Use these prompt patterns:
 
 - “Generate a new HTTP service using Frame, using the canonical `ctx, svc := frame.NewService(...)` bootstrap pattern.”
 - “Create a new Frame plugin as a `WithXxx` option that registers a queue subscriber.”
 - “Add a datastore setup using `WithDatastore` and a migration step.”
+- “Generate OpenAPI specs with `frame-openapi` and register `openapi.Option()`.”
 
 ## Frame Plugin Mental Model
 
@@ -46,3 +63,13 @@ A plugin is a `frame.Option` helper that configures a `Service` and registers st
 
 - Don’t assume `NewService` returns `*Service` directly; it returns `(context.Context, *Service)`.
 - Don’t assume `WithName` accepts a handler; use `WithHTTPHandler` separately.
+
+## Blueprint Extension Rules (AI-Safe)
+
+When working with Frame Blueprints, always **extend** by default:
+
+- Add new items without removing or replacing existing ones.
+- Use `override: true` to modify existing definitions.
+- Use `remove: true` to delete definitions.
+
+This preserves system stability while allowing incremental expansion.