ga-plugins-cli 0.1.0 → 0.1.1

package/plugins/go-standards/skills/project-layout.md

@@ -0,0 +1,313 @@
+# Project Layout Standard
+
+Canonical folder structure for every chi-based service in this migration.
+All 30 services MUST follow this layout without exception — consistency is
+what makes the consolidated codebase navigable.
+
+---
+
+## Canonical Tree
+
+```
+my-service/
+  cmd/
+    server/
+      main.go           # entrypoint only — wires deps, calls ListenAndServe
+  internal/
+    handler/            # HTTP handlers — thin, delegate immediately to usecase
+      user_handler.go
+      user_handler_test.go
+    usecase/            # business logic — the core of the service
+      user_usecase.go
+      user_usecase_test.go
+    repository/         # data-access implementations (DB, cache, external APIs)
+      user_repository.go
+      user_repository_test.go
+    domain/             # structs, interfaces, sentinel errors — zero external imports
+      user.go
+      errors.go
+  pkg/                  # importable by external packages (shared clients, helpers)
+  config/               # env loading, Config struct
+    config.go
+  go.mod
+  go.sum
+  Dockerfile
+  .env.example
+```
+
+---
+
+## Rule 1 — `cmd/server/main.go` wires dependencies only
+
+`main.go` is a composition root. It reads config, constructs every concrete
+type, wires them together, and starts the HTTP server. No business logic lives
+here.
+
+### DO
+
+```go
+// cmd/server/main.go
+package main
+
+import (
+    "context"
+    "log"
+    "net/http"
+    "os/signal"
+    "syscall"
+    "time"
+
+    "github.com/go-chi/chi/v5"
+    "github.com/go-chi/chi/v5/middleware"
+    "go.uber.org/zap"
+
+    "github.com/zokypesch/go-ga-lib/config"
+    "github.com/zokypesch/go-ga-lib/internal/handler"
+    "github.com/zokypesch/go-ga-lib/internal/repository"
+    "github.com/zokypesch/go-ga-lib/internal/usecase"
+)
+
+func main() {
+    cfg, err := config.Load()
+    if err != nil {
+        log.Fatalf("loading config: %v", err)
+    }
+
+    logger, err := zap.NewProduction()
+    if err != nil {
+        log.Fatalf("building logger: %v", err)
+    }
+    defer logger.Sync()
+
+    db, err := repository.OpenDB(cfg.DSN)
+    if err != nil {
+        log.Fatalf("opening db: %v", err)
+    }
+
+    userRepo := repository.NewUserRepository(db)
+    userUC   := usecase.NewUserUsecase(userRepo, logger)
+    userH    := handler.NewUserHandler(userUC, logger)
+
+    r := chi.NewRouter()
+    r.Use(middleware.RequestID)
+    r.Use(middleware.Logger)
+    r.Use(middleware.Recoverer)
+
+    r.Route("/api/v1", func(r chi.Router) {
+        r.Mount("/users", userH.Routes())
+    })
+
+    srv := &http.Server{Addr: ":" + cfg.Port, Handler: r}
+
+    ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
+    defer stop()
+
+    go func() {
+        if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
+            logger.Fatal("server error", zap.Error(err))
+        }
+    }()
+
+    <-ctx.Done()
+    shutCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+    defer cancel()
+    _ = srv.Shutdown(shutCtx)
+}
+```
+
+### DO NOT
+
+```go
+// cmd/server/main.go — WRONG: business logic leaking into main
+func main() {
+    // WRONG: querying the DB directly in main
+    rows, _ := db.Query("SELECT * FROM users WHERE active = true")
+    // WRONG: inline HTTP handler in main
+    http.HandleFunc("/users", func(w http.ResponseWriter, r *http.Request) {
+        // ... business logic here ...
+    })
+    http.ListenAndServe(":8080", nil)
+}
+```
+
+---
+
+## Rule 2 — `internal/` is private to this module
+
+Go enforces this at the compiler level: packages under `internal/` cannot be
+imported by any module outside the module root. Rely on this — never fight it.
+
+### DO
+
+```
+// Correct: a sibling service imports only pkg/, never internal/
+import "github.com/zokypesch/go-ga-lib/pkg/apierror"   // ok — pkg is public
+```
+
+### DO NOT
+
+```
+// WRONG: trying to import internal/ from another module
+import "github.com/zokypesch/go-ga-lib/internal/domain" // compile error
+```
+
+---
+
+## Rule 3 — `domain/` has zero external imports
+
+`domain/` defines the vocabulary of the service: structs, interfaces, and
+sentinel errors. It MUST import nothing outside the Go standard library. This
+makes the domain portable and prevents import cycles.
+
+### DO
+
+```go
+// internal/domain/user.go
+package domain
+
+import "time"  // stdlib only
+
+type User struct {
+    ID        string
+    Email     string
+    Name      string
+    CreatedAt time.Time
+}
+
+// UserRepository is the storage contract — implemented in repository/.
+type UserRepository interface {
+    FindByID(ctx context.Context, id string) (*User, error)
+    Create(ctx context.Context, u *User) error
+    Update(ctx context.Context, u *User) error
+    Delete(ctx context.Context, id string) error
+}
+
+// UserUsecase is the business contract — implemented in usecase/.
+type UserUsecase interface {
+    Get(ctx context.Context, id string) (*User, error)
+    Create(ctx context.Context, input CreateUserInput) (*User, error)
+}
+```
+
+```go
+// internal/domain/errors.go
+package domain
+
+import "errors"
+
+var (
+    ErrNotFound      = errors.New("not found")
+    ErrAlreadyExists = errors.New("already exists")
+    ErrInvalidInput  = errors.New("invalid input")
+    ErrUnauthorized  = errors.New("unauthorized")
+)
+```
+
+### DO NOT
+
+```go
+// internal/domain/user.go — WRONG: external import in domain
+package domain
+
+import (
+    "gorm.io/gorm"        // WRONG: ORM in domain
+    "github.com/google/uuid" // WRONG: external lib in domain
+)
+
+type User struct {
+    gorm.Model            // WRONG: ORM base struct in domain
+    ID    uuid.UUID
+}
+```
+
+---
+
+## Rule 4 — Handlers NEVER call repositories directly
+
+The dependency flow is strict and unidirectional:
+
+```
+handler  →  usecase  →  repository
+```
+
+Handlers know about usecases. Usecases know about repositories. Nothing flows
+backwards. Handlers NEVER import `repository/`.
+
+### DO
+
+```go
+// internal/handler/user_handler.go
+package handler
+
+import "github.com/zokypesch/go-ga-lib/internal/domain"
+
+type UserHandler struct {
+    uc     domain.UserUsecase  // depends on the interface, not the concrete type
+    logger *zap.Logger
+}
+
+func NewUserHandler(uc domain.UserUsecase, logger *zap.Logger) *UserHandler {
+    return &UserHandler{uc: uc, logger: logger}
+}
+
+func (h *UserHandler) Get(w http.ResponseWriter, r *http.Request) {
+    id := chi.URLParam(r, "id")
+    user, err := h.uc.Get(r.Context(), id)  // calls usecase, not repository
+    if err != nil {
+        respondError(w, err)
+        return
+    }
+    respondJSON(w, http.StatusOK, user)
+}
+```
+
+### DO NOT
+
+```go
+// internal/handler/user_handler.go — WRONG: handler calls repository
+package handler
+
+import "github.com/zokypesch/go-ga-lib/internal/repository" // WRONG
+
+type UserHandler struct {
+    repo *repository.UserRepository // WRONG: skip the usecase layer
+}
+
+func (h *UserHandler) Get(w http.ResponseWriter, r *http.Request) {
+    id := chi.URLParam(r, "id")
+    user, _ := h.repo.FindByID(r.Context(), id) // WRONG: bypasses business logic
+    json.NewEncoder(w).Encode(user)
+}
+```
+
+---
+
+## Dependency Direction Summary
+
+```
+cmd/server/main.go
+    └── internal/handler       (imports domain interfaces)
+         └── internal/usecase  (imports domain interfaces)
+              └── internal/repository (imports domain structs)
+                   └── internal/domain (imports stdlib only)
+```
+
+Breaking this chain in any direction is a FAIL in code review.
+
+---
+
+## File Naming Conventions
+
+| Concern | File name |
+|---------|-----------|
+| HTTP handlers for User | `internal/handler/user_handler.go` |
+| Usecase for User | `internal/usecase/user_usecase.go` |
+| Repository for User | `internal/repository/user_repository.go` |
+| Domain types for User | `internal/domain/user.go` |
+| Sentinel errors | `internal/domain/errors.go` |
+| Config struct | `config/config.go` |
+| Test for usecase | `internal/usecase/user_usecase_test.go` |
+
+One file per major type. Do not create `utils.go`, `helpers.go`, or
+`common.go` files — if code is shared, put it in a purpose-named file or
+in `pkg/`.

package/plugins/go-standards/skills/testing.md

@@ -0,0 +1,366 @@
+# Testing Standard
+
+Tests are first-class citizens. Every usecase and repository must have unit
+tests. Handlers get integration tests. The default pattern is table-driven.
+
+---
+
+## Rule 1 — Table-Driven Tests as Default
+
+Table-driven tests make it easy to add cases without duplicating test
+scaffolding and produce clear failure messages via `t.Run`.
+
+```go
+// internal/usecase/user_usecase_test.go
+package usecase_test
+
+import (
+    "context"
+    "errors"
+    "testing"
+
+    "github.com/stretchr/testify/assert"
+    "github.com/stretchr/testify/require"
+    "go.uber.org/zap/zaptest"
+
+    "github.com/zokypesch/go-ga-lib/internal/domain"
+    "github.com/zokypesch/go-ga-lib/internal/usecase"
+)
+
+func TestUserUsecase_Create(t *testing.T) {
+    cases := []struct {
+        name    string
+        input   domain.CreateUserInput
+        repoErr error   // error the mock repo returns
+        want    *domain.User
+        wantErr error   // sentinel error the usecase should wrap
+    }{
+        {
+            name:  "valid input creates user",
+            input: domain.CreateUserInput{Email: "alice@example.com", Name: "Alice"},
+            want:  &domain.User{ID: "u1", Email: "alice@example.com", Name: "Alice"},
+        },
+        {
+            name:    "missing email returns invalid input",
+            input:   domain.CreateUserInput{Name: "Alice"},
+            wantErr: domain.ErrInvalidInput,
+        },
+        {
+            name:    "duplicate email returns already exists",
+            input:   domain.CreateUserInput{Email: "alice@example.com", Name: "Alice"},
+            repoErr: domain.ErrAlreadyExists,
+            wantErr: domain.ErrAlreadyExists,
+        },
+        {
+            name:    "repo error propagates",
+            input:   domain.CreateUserInput{Email: "bob@example.com", Name: "Bob"},
+            repoErr: errors.New("connection refused"),
+            wantErr: errors.New("connection refused"), // non-sentinel: check message
+        },
+    }
+
+    for _, tc := range cases {
+        t.Run(tc.name, func(t *testing.T) {
+            t.Parallel() // safe — each test case uses its own mock
+
+            repo := &mockUserRepository{createErr: tc.repoErr, createUser: tc.want}
+            logger := zaptest.NewLogger(t)
+            uc := usecase.NewUserUsecase(repo, logger)
+
+            got, err := uc.Create(context.Background(), tc.input)
+
+            if tc.wantErr != nil {
+                require.Error(t, err)
+                if errors.Is(tc.wantErr, domain.ErrInvalidInput) ||
+                    errors.Is(tc.wantErr, domain.ErrAlreadyExists) {
+                    assert.ErrorIs(t, err, tc.wantErr) // sentinel: use errors.Is
+                } else {
+                    assert.ErrorContains(t, err, tc.wantErr.Error()) // infra: check message
+                }
+                assert.Nil(t, got)
+                return
+            }
+
+            require.NoError(t, err)
+            assert.Equal(t, tc.want.Email, got.Email)
+            assert.Equal(t, tc.want.Name, got.Name)
+        })
+    }
+}
+```
+
+---
+
+## Rule 2 — File Naming
+
+| Scenario | Package declaration | File name |
+|----------|---------------------|-----------|
+| White-box (access unexported symbols) | `package usecase` | `user_usecase_test.go` |
+| Black-box (test exported API only) | `package usecase_test` | `user_usecase_test.go` |
+| Integration test | `package usecase_test` | `user_usecase_integration_test.go` |
+
+Prefer black-box tests (`_test` package suffix) — they test the public
+contract and catch accidental leaks of internal details.
+
+---
+
+## Rule 3 — Use testify/assert and testify/require
+
+- `require.*` — stops the test immediately on failure (use for preconditions)
+- `assert.*` — records failure but continues (use for post-conditions)
+
+```go
+import (
+    "github.com/stretchr/testify/assert"
+    "github.com/stretchr/testify/require"
+)
+
+// require for setup / preconditions
+user, err := uc.Create(ctx, input)
+require.NoError(t, err)          // stop if creation failed — rest of test is meaningless
+
+// assert for post-conditions — collect all failures
+assert.Equal(t, "alice@example.com", user.Email)
+assert.NotEmpty(t, user.ID)
+assert.False(t, user.CreatedAt.IsZero())
+```
+
+---
+
+## Rule 4 — Interfaces Enable Mocking
+
+All dependencies are injected as interfaces. Mocks are hand-written structs
+(or generated with `mockery`) that implement the interface.
+
+```go
+// internal/usecase/user_usecase_test.go — hand-written mock
+type mockUserRepository struct {
+    createUser *domain.User
+    createErr  error
+    findUser   *domain.User
+    findErr    error
+    calls      []string  // optional: record calls for assertion
+}
+
+func (m *mockUserRepository) Create(_ context.Context, u *domain.User) (*domain.User, error) {
+    m.calls = append(m.calls, "Create")
+    if m.createErr != nil {
+        return nil, m.createErr
+    }
+    if m.createUser != nil {
+        return m.createUser, nil
+    }
+    return u, nil
+}
+
+func (m *mockUserRepository) FindByID(_ context.Context, id string) (*domain.User, error) {
+    m.calls = append(m.calls, "FindByID")
+    return m.findUser, m.findErr
+}
+```
+
+For complex mocks, use `github.com/vektra/mockery` to generate:
+```bash
+go generate ./...
+// File: internal/domain/user.go
+//go:generate mockery --name=UserRepository --output=../mocks --outpkg=mocks
+```
+
+---
+
+## Rule 5 — Integration Tests with Build Tags
+
+Integration tests require real infrastructure (DB, cache, external APIs).
+Gate them behind a build tag so `go test ./...` only runs unit tests in CI
+by default.
+
+```go
+// internal/repository/user_repository_integration_test.go
+//go:build integration
+
+package repository_test
+
+import (
+    "context"
+    "database/sql"
+    "testing"
+
+    _ "github.com/lib/pq"
+    "github.com/stretchr/testify/assert"
+    "github.com/stretchr/testify/require"
+
+    "github.com/zokypesch/go-ga-lib/internal/domain"
+    "github.com/zokypesch/go-ga-lib/internal/repository"
+)
+
+func TestUserRepository_Create_Integration(t *testing.T) {
+    db, err := sql.Open("postgres", testDSN(t))
+    require.NoError(t, err)
+    t.Cleanup(func() { db.Close() })
+
+    repo := repository.NewUserRepository(db)
+
+    user, err := repo.Create(context.Background(), &domain.User{
+        Email: "integration@example.com",
+        Name:  "Integration User",
+    })
+    require.NoError(t, err)
+    assert.NotEmpty(t, user.ID)
+}
+
+// testDSN reads the test DB connection string from env or t.Skip if absent
+func testDSN(t *testing.T) string {
+    t.Helper()
+    dsn := os.Getenv("TEST_DB_DSN")
+    if dsn == "" {
+        t.Skip("TEST_DB_DSN not set — skipping integration test")
+    }
+    return dsn
+}
+```
+
+Run integration tests explicitly:
+```bash
+go test -tags=integration ./internal/repository/...
+```
+
+---
+
+## Rule 6 — No `time.Sleep` in Tests
+
+Sleep makes tests slow and flaky. Use channels, context timeouts, or
+testify's `Eventually` helper to wait for asynchronous conditions.
+
+### DO
+
+```go
+// Waiting for an async result with a channel
+func TestWorker_ProcessesMessage(t *testing.T) {
+    processed := make(chan string, 1)
+    worker := NewWorker(func(msg string) {
+        processed <- msg
+    })
+    worker.Start(context.Background())
+
+    worker.Send("hello")
+
+    select {
+    case msg := <-processed:
+        assert.Equal(t, "hello", msg)
+    case <-time.After(2 * time.Second):
+        t.Fatal("timed out waiting for message to be processed")
+    }
+}
+
+// Polling with testify Eventually for eventually-consistent state
+assert.Eventually(t,
+    func() bool { return cache.Has("key") },
+    2*time.Second,   // max wait
+    10*time.Millisecond, // poll interval
+    "cache never populated",
+)
+```
+
+### DO NOT
+
+```go
+worker.Start(context.Background())
+worker.Send("hello")
+time.Sleep(500 * time.Millisecond)  // WRONG: flaky, slow, arbitrary
+assert.True(t, worker.Processed("hello"))
+```
+
+---
+
+## Rule 7 — Handler Tests use `httptest`
+
+Test handlers with the standard `net/http/httptest` package. No need to
+start a real server.
+
+```go
+// internal/handler/user_handler_test.go
+package handler_test
+
+import (
+    "bytes"
+    "encoding/json"
+    "net/http"
+    "net/http/httptest"
+    "testing"
+
+    "github.com/stretchr/testify/assert"
+    "github.com/stretchr/testify/require"
+    "go.uber.org/zap/zaptest"
+
+    "github.com/zokypesch/go-ga-lib/internal/domain"
+    "github.com/zokypesch/go-ga-lib/internal/handler"
+)
+
+func TestUserHandler_Create(t *testing.T) {
+    cases := []struct {
+        name       string
+        body       any
+        ucErr      error
+        ucUser     *domain.User
+        wantStatus int
+        wantCode   string // error code in JSON response
+    }{
+        {
+            name:       "creates user — 201",
+            body:       map[string]string{"email": "a@b.com", "name": "A"},
+            ucUser:     &domain.User{ID: "u1", Email: "a@b.com"},
+            wantStatus: http.StatusCreated,
+        },
+        {
+            name:       "invalid input — 400",
+            body:       map[string]string{"name": "A"}, // missing email
+            ucErr:      domain.ErrInvalidInput,
+            wantStatus: http.StatusBadRequest,
+            wantCode:   "BAD_REQUEST",
+        },
+        {
+            name:       "duplicate — 409",
+            body:       map[string]string{"email": "a@b.com", "name": "A"},
+            ucErr:      domain.ErrAlreadyExists,
+            wantStatus: http.StatusConflict,
+            wantCode:   "CONFLICT",
+        },
+    }
+
+    for _, tc := range cases {
+        t.Run(tc.name, func(t *testing.T) {
+            bodyBytes, err := json.Marshal(tc.body)
+            require.NoError(t, err)
+
+            uc := &mockUserUsecase{createUser: tc.ucUser, createErr: tc.ucErr}
+            h := handler.NewUserHandler(uc, zaptest.NewLogger(t))
+
+            req := httptest.NewRequest(http.MethodPost, "/api/v1/users", bytes.NewReader(bodyBytes))
+            req.Header.Set("Content-Type", "application/json")
+            rr := httptest.NewRecorder()
+
+            h.Create(rr, req)
+
+            assert.Equal(t, tc.wantStatus, rr.Code)
+            if tc.wantCode != "" {
+                var resp map[string]string
+                require.NoError(t, json.NewDecoder(rr.Body).Decode(&resp))
+                assert.Equal(t, tc.wantCode, resp["code"])
+            }
+        })
+    }
+}
+```
+
+---
+
+## Test Coverage Targets
+
+| Layer | Minimum coverage |
+|-------|-----------------|
+| `domain/` | 100% (pure logic, no I/O) |
+| `usecase/` | 90% |
+| `handler/` | 80% |
+| `repository/` | covered by integration tests |
+
+Run with: `go test -cover ./...`

package/plugins/java2go-porter/.claude-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "java2go-porter",
+  "version": "0.1.0",
+  "description": "Java→Go translation accelerator (DRAFT only — requires human review + green tests). Runs analyzer→translator→test-pairer→reviewer pipeline.",
+  "commands": [
+    {
+      "name": "port-java-service",
+      "description": "Translate a Java/Spring Boot service to a Go draft using chi + go-ga-lib",
+      "path": "commands/port-java-service.md"
+    }
+  ],
+  "agents": [
+    { "name": "analyzer", "path": "agents/analyzer.md" },
+    { "name": "translator", "path": "agents/translator.md" },
+    { "name": "test-pairer", "path": "agents/test-pairer.md" },
+    { "name": "reviewer", "path": "agents/reviewer.md" }
+  ],
+  "skills": [
+    { "name": "idiom-mapping", "path": "skills/idiom-mapping.md" }
+  ]
+}