groundwork-method 0.0.1 → 0.11.0

package/src/generators/go-microservice/files/internal/postgres/postgres_test.go.template

@@ -0,0 +1,156 @@
+package postgres
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+	"github.com/testcontainers/testcontainers-go"
+	tcpostgres "github.com/testcontainers/testcontainers-go/modules/postgres"
+	"github.com/testcontainers/testcontainers-go/wait"
+
+	"<%= name %>/internal/core/domain"
+
+	_ "github.com/lib/pq"
+)
+
+// setupTestDB starts a Postgres container, applies db/schema.sql, and returns a live DB.
+// Each test gets its own isolated container.
+func setupTestDB(t *testing.T) (*DB, context.Context) {
+	t.Helper()
+	if testing.Short() {
+		t.Skip("skipping data-layer integration test in -short mode")
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
+	t.Cleanup(cancel)
+
+	pgContainer, err := tcpostgres.RunContainer(ctx,
+		testcontainers.WithImage("postgres:16-alpine"),
+		tcpostgres.WithDatabase("<%= name %>_test"),
+		tcpostgres.WithUsername("testuser"),
+		tcpostgres.WithPassword("testpass"),
+		testcontainers.WithWaitStrategy(
+			wait.ForLog("database system is ready to accept connections").
+				WithOccurrence(2).WithStartupTimeout(30*time.Second)),
+	)
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = pgContainer.Terminate(context.Background()) })
+
+	connStr, err := pgContainer.ConnectionString(ctx, "sslmode=disable")
+	require.NoError(t, err)
+
+	db, err := NewDB(connStr)
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = db.Close() })
+
+	// internal/postgres -> ../../db/schema.sql (same depth as cmd/api).
+	schemaPath := filepath.Join("..", "..", "db", "schema.sql")
+	schemaBytes, err := os.ReadFile(schemaPath)
+	require.NoError(t, err, "failed to read schema.sql from %s", schemaPath)
+	_, err = db.DB.ExecContext(ctx, string(schemaBytes))
+	require.NoError(t, err, "failed to apply schema")
+
+	return db, ctx
+}
+
+func TestRepository_CRUDRoundTrip(t *testing.T) {
+	db, ctx := setupTestDB(t)
+	repo := NewRepository(db)
+
+	ent := &domain.Entity{Name: "first"}
+	require.NoError(t, repo.Create(ctx, ent))
+	require.NotEmpty(t, ent.ID, "Create must populate the generated ID")
+
+	got, err := repo.GetByID(ctx, ent.ID)
+	require.NoError(t, err)
+	require.Equal(t, "first", got.Name)
+
+	got.Name = "renamed"
+	require.NoError(t, repo.Update(ctx, got))
+	reloaded, err := repo.GetByID(ctx, ent.ID)
+	require.NoError(t, err)
+	require.Equal(t, "renamed", reloaded.Name)
+
+	require.NoError(t, repo.Delete(ctx, ent.ID))
+	_, err = repo.GetByID(ctx, ent.ID)
+	require.Error(t, err, "GetByID after Delete must return an error (not found)")
+}
+
+// NOTE on transactional writes: service.Transaction exposes only Commit/Rollback,
+// not Exec — you cannot write *through* the wrapper tx from a test. So we verify
+// real transactional semantics directly on the raw *sql.Tx (db.DB.BeginTx), AND
+// verify the manager's Begin->Commit/Rollback lifecycle works. Do NOT route writes
+// through db.DB.ExecContext and then call tx.Commit/Rollback: a pool Exec
+// autocommits on a *different* connection, so the manager tx would be a no-op.
+
+func TestTransaction_RawRollbackDiscards(t *testing.T) {
+	db, ctx := setupTestDB(t)
+
+	tx, err := db.DB.BeginTx(ctx, nil)
+	require.NoError(t, err)
+	_, err = tx.ExecContext(ctx, "INSERT INTO entities (name) VALUES ('rolled-back')")
+	require.NoError(t, err)
+	require.NoError(t, tx.Rollback())
+
+	var count int
+	err = db.DB.QueryRowContext(ctx, "SELECT count(*) FROM entities WHERE name = 'rolled-back'").Scan(&count)
+	require.NoError(t, err)
+	require.Equal(t, 0, count, "rolled-back insert must not persist")
+}
+
+func TestTransaction_RawCommitPersists(t *testing.T) {
+	db, ctx := setupTestDB(t)
+
+	tx, err := db.DB.BeginTx(ctx, nil)
+	require.NoError(t, err)
+	_, err = tx.ExecContext(ctx, "INSERT INTO entities (name) VALUES ('committed')")
+	require.NoError(t, err)
+	require.NoError(t, tx.Commit())
+
+	var count int
+	err = db.DB.QueryRowContext(ctx, "SELECT count(*) FROM entities WHERE name = 'committed'").Scan(&count)
+	require.NoError(t, err)
+	require.Equal(t, 1, count, "committed insert must persist")
+}
+
+func TestTransactionManager_BeginCommitRollbackLifecycle(t *testing.T) {
+	db, ctx := setupTestDB(t)
+	tm := NewTransactionManager(db)
+
+	// Begin -> Commit must succeed.
+	txA, err := tm.Begin(ctx)
+	require.NoError(t, err)
+	require.NoError(t, txA.Commit(ctx))
+
+	// Begin -> Rollback must succeed.
+	txB, err := tm.Begin(ctx)
+	require.NoError(t, err)
+	require.NoError(t, txB.Rollback(ctx))
+}
+
+<% if (messaging !== 'none') { %>
+func TestOutboxRepository_InsertPollMark(t *testing.T) {
+	db, ctx := setupTestDB(t)
+	repo := NewOutboxRepository(db)
+	tm := NewTransactionManager(db)
+
+	tx, err := tm.Begin(ctx)
+	require.NoError(t, err)
+	require.NoError(t, repo.InsertEvent(ctx, tx, "entity.created", []byte(`{"id":"e1"}`)))
+	require.NoError(t, tx.Commit(ctx))
+
+	events, err := repo.PollUnpublished(ctx, 10)
+	require.NoError(t, err)
+	require.Len(t, events, 1, "the inserted event must be pollable as unpublished")
+	require.Equal(t, "entity.created", events[0].EventType)
+
+	require.NoError(t, repo.MarkPublished(ctx, events[0].ID))
+
+	after, err := repo.PollUnpublished(ctx, 10)
+	require.NoError(t, err)
+	require.Empty(t, after, "a published event must no longer appear as unpublished")
+}
+<% } %>

package/src/generators/go-microservice/files/internal/postgres/user_repository.go.template

@@ -0,0 +1,56 @@
+package postgres
+
+import (
+	"context"
+	"errors"
+
+	"<%= name %>/internal/core/domain"
+)
+
+type UserRepository struct {
+	db *DB
+}
+
+func NewUserRepository(db *DB) *UserRepository {
+	return &UserRepository{db: db}
+}
+
+func (r *UserRepository) GetByClerkID(ctx context.Context, clerkID string) (*domain.User, error) {
+	// STUB: Replace with actual query
+	// row := r.db.QueryRowContext(ctx, "SELECT id, clerk_id, email, username, created_at, updated_at FROM users WHERE clerk_id = $1", clerkID)
+	// var user domain.User
+	// err := row.Scan(&user.ID, &user.ClerkID, &user.Email, &user.Username, &user.CreatedAt, &user.UpdatedAt)
+	// if err != nil {
+	//     if errors.Is(err, sql.ErrNoRows) {
+	//         return nil, errors.New("user not found")
+	//     }
+	//     return nil, err
+	// }
+	// return &user, nil
+	return nil, errors.New("GetByClerkID not implemented")
+}
+
+func (r *UserRepository) Save(ctx context.Context, user *domain.User) error {
+	// STUB: Replace with actual query
+	// _, err := r.db.ExecContext(ctx,
+	//     "INSERT INTO users (clerk_id, email, username, created_at, updated_at) VALUES ($1, $2, $3, $4, $5) ON CONFLICT (clerk_id) DO UPDATE SET email = $2, username = $3, updated_at = $5",
+	//     user.ClerkID, user.Email, user.Username, user.CreatedAt, user.UpdatedAt)
+	// return err
+	return nil
+}
+
+func (r *UserRepository) Update(ctx context.Context, user *domain.User) error {
+	// STUB: Replace with actual query
+	// _, err := r.db.ExecContext(ctx,
+	//     "UPDATE users SET email = $1, username = $2, updated_at = $3 WHERE clerk_id = $4",
+	//     user.Email, user.Username, user.UpdatedAt, user.ClerkID)
+	// return err
+	return nil
+}
+
+func (r *UserRepository) DeleteByClerkID(ctx context.Context, clerkID string) error {
+	// STUB: Replace with actual query
+	// _, err := r.db.ExecContext(ctx, "DELETE FROM users WHERE clerk_id = $1", clerkID)
+	// return err
+	return nil
+}

package/src/generators/go-microservice/files/internal/pubsub/gcp_pubsub.go.template

@@ -0,0 +1,35 @@
+<% if (messaging === 'gcp-pubsub') { %>package pubsub
+
+import (
+	"context"
+	"fmt"
+
+	gcppubsub "cloud.google.com/go/pubsub"
+	"github.com/rs/zerolog/log"
+
+	"<%= name %>/internal/core/service"
+)
+
+// Ensure Publisher implements service.MessageQueue
+var _ service.MessageQueue = (*Publisher)(nil)
+
+type Publisher struct {
+	client *gcppubsub.Client
+}
+
+func NewPublisher(projectID string) (*Publisher, error) {
+	ctx := context.Background()
+	client, err := gcppubsub.NewClient(ctx, projectID)
+	if err != nil {
+		return nil, fmt.Errorf("create pubsub client: %w", err)
+	}
+
+	log.Info().Msg("GCP Pub/Sub publisher initialized")
+	return &Publisher{client: client}, nil
+}
+
+func (p *Publisher) Publish(ctx context.Context, topic string, key, data []byte) error {
+	// Publish logic
+	return nil
+}
+<% } %>

package/src/generators/go-microservice/files/internal/websocket/client.go.template

@@ -0,0 +1,151 @@
+package websocket
+
+import (
+	"context"
+	"encoding/json"
+	"log/slog"
+	"sync"
+	"time"
+
+	"github.com/gorilla/websocket"
+)
+
+const (
+	writeWait      = 10 * time.Second
+	pongWait       = 60 * time.Second
+	pingPeriod     = (pongWait * 9) / 10
+	maxMessageSize = 512 * 1024 // 512 KB
+	sendBufferSize = 256
+)
+
+// inboundCloudEvent represents a CloudEvents-wrapped JSON command from the client.
+type inboundCloudEvent struct {
+	Type string          `json:"type"`
+	Data json.RawMessage `json:"data"`
+}
+
+// Client represents a single WebSocket connection for a specific user.
+type Client struct {
+	ctx        context.Context
+	hub        *Hub
+	conn       *websocket.Conn
+	userID     string
+	sessionID  string
+	send       chan []byte
+	closeOnce  sync.Once
+}
+
+func (c *Client) UserID() string {
+	return c.userID
+}
+
+func (c *Client) SessionID() string {
+	return c.sessionID
+}
+
+func (c *Client) closeSend() {
+	c.closeOnce.Do(func() {
+		close(c.send)
+	})
+}
+
+func NewClient(ctx context.Context, hub *Hub, conn *websocket.Conn, userID string, sessionID string) *Client {
+	return &Client{
+		ctx:       ctx,
+		hub:       hub,
+		conn:      conn,
+		userID:    userID,
+		sessionID: sessionID,
+		send:      make(chan []byte, sendBufferSize),
+	}
+}
+
+func (c *Client) ReadPump() {
+	defer func() {
+		c.hub.Unregister(c)
+		c.conn.Close()
+	}()
+
+	c.conn.SetReadLimit(maxMessageSize)
+	if err := c.conn.SetReadDeadline(time.Now().Add(pongWait)); err != nil {
+		slog.ErrorContext(c.ctx, "failed to set read deadline", slog.String("error", err.Error()))
+		return
+	}
+	c.conn.SetPongHandler(func(string) error {
+		return c.conn.SetReadDeadline(time.Now().Add(pongWait))
+	})
+
+	for {
+		messageType, message, err := c.conn.ReadMessage()
+		if err != nil {
+			if websocket.IsUnexpectedCloseError(err, websocket.CloseGoingAway, websocket.CloseNormalClosure) {
+				slog.WarnContext(c.ctx, "WebSocket unexpected close", slog.String("user_id", c.userID), slog.String("error", err.Error()))
+			}
+			return
+		}
+
+		if messageType == websocket.TextMessage {
+			c.handleTextMessage(message)
+		}
+	}
+}
+
+func (c *Client) handleTextMessage(message []byte) {
+	var envelope inboundCloudEvent
+	if err := json.Unmarshal(message, &envelope); err != nil {
+		slog.WarnContext(c.ctx, "invalid JSON command", slog.String("user_id", c.userID), slog.String("error", err.Error()))
+		return
+	}
+
+	// STUB: Handle specific incoming command types here.
+	switch envelope.Type {
+	case "com.<%= name %>.example.command.v1":
+		slog.InfoContext(c.ctx, "received example command")
+	default:
+		slog.DebugContext(c.ctx, "unknown CloudEvents command type, ignoring",
+			slog.String("type", envelope.Type),
+			slog.String("user_id", c.userID))
+	}
+}
+
+func (c *Client) WritePump() {
+	ticker := time.NewTicker(pingPeriod)
+	defer func() {
+		ticker.Stop()
+		c.conn.Close()
+	}()
+
+	for {
+		select {
+		case message, ok := <-c.send:
+			if err := c.conn.SetWriteDeadline(time.Now().Add(writeWait)); err != nil {
+				return
+			}
+			if !ok {
+				if err := c.conn.WriteMessage(websocket.CloseMessage, websocket.FormatCloseMessage(websocket.CloseGoingAway, "Server shutting down")); err != nil {
+					slog.WarnContext(c.ctx, "failed to write close message", slog.String("error", err.Error()))
+				}
+				return
+			}
+
+			if err := c.conn.WriteMessage(websocket.TextMessage, message); err != nil {
+				return
+			}
+
+			n := len(c.send)
+			for i := 0; i < n; i++ {
+				if err := c.conn.WriteMessage(websocket.TextMessage, <-c.send); err != nil {
+					return
+				}
+			}
+
+		case <-ticker.C:
+			if err := c.conn.SetWriteDeadline(time.Now().Add(writeWait)); err != nil {
+				return
+			}
+			if err := c.conn.WriteMessage(websocket.PingMessage, nil); err != nil {
+				return
+			}
+		}
+	}
+}

package/src/generators/go-microservice/files/internal/websocket/hub.go.template

@@ -0,0 +1,261 @@
+package websocket
+
+import (
+	"context"
+	"encoding/json"
+	"log/slog"
+	"sync"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/redis/go-redis/v9"
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/propagation"
+
+	"<%= name %>/internal/config"
+	"<%= name %>/internal/core/domain"
+)
+
+// cloudEvent is the CloudEvents v1.0 JSON envelope sent over WebSocket.
+type cloudEvent struct {
+	SpecVersion    string `json:"specversion"`
+	ID             string `json:"id"`
+	Type           string `json:"type"`
+	Source         string `json:"source"`
+	Time           string `json:"time"`
+	Traceparent    string `json:"traceparent,omitempty"`
+	Tracestate     string `json:"tracestate,omitempty"`
+	SourceClientID string `json:"sourceClientId,omitempty"`
+	Data           any    `json:"data"`
+}
+
+// mapCarrier adapts a map for OTel text-map propagation injection.
+type mapCarrier map[string]string
+
+func (c mapCarrier) Get(key string) string { return c[key] }
+func (c mapCarrier) Set(key, value string) { c[key] = value }
+func (c mapCarrier) Keys() []string {
+	keys := make([]string, 0, len(c))
+	for k := range c {
+		keys = append(keys, k)
+	}
+	return keys
+}
+
+// Hub maintains the set of active WebSocket clients and broadcasts events.
+type Hub struct {
+	clients map[string]map[*Client]struct{} // Map by UserID or other partition key
+	mu      sync.RWMutex
+
+	registerCh   chan *Client
+	unregisterCh chan *Client
+	broadcastCh  chan domain.Event
+	stopCh       chan struct{}
+
+	redisClient  *redis.Client
+	redisPubSub  *redis.PubSub
+}
+
+func NewHub(cfg *config.Config) *Hub {
+	h := &Hub{
+		clients:      make(map[string]map[*Client]struct{}),
+		registerCh:   make(chan *Client, 64),
+		unregisterCh: make(chan *Client, 64),
+		broadcastCh:  make(chan domain.Event, 256),
+		stopCh:       make(chan struct{}),
+	}
+
+	if cfg.Redis.URI != "" {
+		opts, err := redis.ParseURL(cfg.Redis.URI)
+		if err == nil {
+			h.redisClient = redis.NewClient(opts)
+			h.redisPubSub = h.redisClient.Subscribe(context.Background(), "<%= name %>:ws:events")
+			slog.Info("WebSocket Hub connected to Redis Backplane")
+			go h.listenRedis()
+		} else {
+			slog.Warn("Failed to parse Redis URL for WebSocket Backplane", slog.String("error", err.Error()))
+		}
+	}
+
+	return h
+}
+
+func (h *Hub) Run() {
+	for {
+		select {
+		case client := <-h.registerCh:
+			h.addClient(client)
+		case client := <-h.unregisterCh:
+			h.removeClient(client)
+		case event := <-h.broadcastCh:
+			h.broadcastToUser(event)
+		case <-h.stopCh:
+			return
+		}
+	}
+}
+
+func (h *Hub) Stop() {
+	h.Reset()
+	close(h.stopCh)
+}
+
+func (h *Hub) Register(client *Client) {
+	h.registerCh <- client
+}
+
+func (h *Hub) Unregister(client *Client) {
+	h.unregisterCh <- client
+}
+
+// ConnectedUsers returns the total number of connected clients across all users.
+func (h *Hub) ConnectedUsers() int {
+	h.mu.RLock()
+	defer h.mu.RUnlock()
+	count := 0
+	for _, userClients := range h.clients {
+		count += len(userClients)
+	}
+	return count
+}
+
+// Broadcast queues a domain event for delivery.
+func (h *Hub) Broadcast(event domain.Event) {
+	select {
+	case h.broadcastCh <- event:
+	default:
+		slog.Warn("broadcast channel full, dropping event")
+	}
+}
+
+func (h *Hub) addClient(client *Client) {
+	h.mu.Lock()
+	defer h.mu.Unlock()
+	userID := client.UserID()
+	userClients, ok := h.clients[userID]
+	if !ok {
+		userClients = make(map[*Client]struct{})
+		h.clients[userID] = userClients
+	}
+	userClients[client] = struct{}{}
+	slog.Info("WebSocket client registered", slog.String("user_id", userID))
+}
+
+func (h *Hub) removeClient(client *Client) {
+	h.mu.Lock()
+	defer h.mu.Unlock()
+	userID := client.UserID()
+	userClients, ok := h.clients[userID]
+	if !ok {
+		return
+	}
+	if _, exists := userClients[client]; exists {
+		delete(userClients, client)
+		client.closeSend()
+	}
+	if len(userClients) == 0 {
+		delete(h.clients, userID)
+	}
+	slog.Info("WebSocket client unregistered", slog.String("user_id", userID))
+}
+
+func (h *Hub) broadcastToUser(event domain.Event) {
+	h.mu.RLock()
+	// Using a generic partition key from the event if applicable.
+	// STUB: Update partition key based on your domain.Event definition.
+	partitionKey := "all" 
+	
+	userClients, ok := h.clients[partitionKey]
+	if !ok || len(userClients) == 0 {
+		h.mu.RUnlock()
+		return
+	}
+
+	targets := make([]*Client, 0, len(userClients))
+	for client := range userClients {
+		targets = append(targets, client)
+	}
+	h.mu.RUnlock()
+
+	ctx := context.Background()
+
+	carrier := make(mapCarrier)
+	otel.GetTextMapPropagator().Inject(ctx, propagation.MapCarrier(carrier))
+
+	envelope := cloudEvent{
+		SpecVersion: "1.0",
+		ID:          uuid.New().String(),
+		Type:        "event", // STUB: string(event.Type)
+		Source:      "<%= name %>/ws",
+		Time:        time.Now().UTC().Format(time.RFC3339),
+		Traceparent: carrier["traceparent"],
+		Tracestate:  carrier["tracestate"],
+		Data:        event, // STUB: Extract relevant payload
+	}
+
+	data, err := json.Marshal(envelope)
+	if err != nil {
+		slog.ErrorContext(ctx, "failed to marshal CloudEvent", slog.String("error", err.Error()))
+		return
+	}
+
+	// Dynamic Backplane: If Redis is configured, publish to the backplane instead of just local clients
+	if h.redisClient != nil {
+		if err := h.redisClient.Publish(ctx, "<%= name %>:ws:events", data).Err(); err != nil {
+			slog.ErrorContext(ctx, "failed to publish event to Redis backplane", slog.String("error", err.Error()))
+		}
+		// In a real Redis setup, you'd rely entirely on the listenRedis goroutine to receive and broadcast it locally.
+		// For simplicity, we just broadcast locally here too, but you might want to skip local broadcast to avoid duplicates.
+	}
+
+	var evicted []*Client
+	for _, client := range targets {
+		select {
+		case client.send <- data:
+		default:
+			evicted = append(evicted, client)
+		}
+	}
+
+	for _, client := range evicted {
+		h.removeClient(client)
+	}
+}
+
+func (h *Hub) listenRedis() {
+	if h.redisPubSub == nil {
+		return
+	}
+	ch := h.redisPubSub.Channel()
+	for msg := range ch {
+		// Parse the envelope to find the partition key
+		var envelope cloudEvent
+		if err := json.Unmarshal([]byte(msg.Payload), &envelope); err != nil {
+			slog.Error("failed to unmarshal Redis backplane event", slog.String("error", err.Error()))
+			continue
+		}
+		
+		// For now, we broadcast to all. In production, extract user ID from the event and route specifically
+		h.mu.RLock()
+		for _, userClients := range h.clients {
+			for client := range userClients {
+				select {
+				case client.send <- []byte(msg.Payload):
+				default:
+				}
+			}
+		}
+		h.mu.RUnlock()
+	}
+}
+
+func (h *Hub) Reset() {
+	h.mu.Lock()
+	for _, userClients := range h.clients {
+		for client := range userClients {
+			client.closeSend()
+		}
+	}
+	h.clients = make(map[string]map[*Client]struct{})
+	h.mu.Unlock()
+}

package/src/generators/go-microservice/files/scripts/apply-schema.sh.template

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+set -e
+
+# Loads environment variables if .env exists
+if [ -f .env ]; then
+    export $(cat .env | xargs)
+fi
+
+# Ensure database URL is available
+DB_URL=${DATABASE_URL:-"postgres://postgres:postgres@localhost:5432/<%= name %>?sslmode=disable"}
+
+echo "Applying declarative schema to database..."
+
+# Uses Stripe's pg-schema-diff to declaratively migrate the database 
+# to match the state defined in db/schema.sql
+go run github.com/stripe/pg-schema-diff/cmd/pg-schema-diff apply \
+    --from-dsn "$DB_URL" \
+    --to-dir ./db \
+    --skip-confirm-prompt
+
+echo "Schema applied successfully!"

package/src/generators/go-microservice/files/tools/tools.go.template

@@ -0,0 +1,10 @@
+//go:build tools
+
+// Package tools pins tool dependencies so go mod tidy retains them.
+// These packages are referenced via go run in shell scripts; the build
+// tag prevents them from being compiled into the main binary.
+package tools
+
+import (
+	_ "github.com/stripe/pg-schema-diff/cmd/pg-schema-diff"
+)