ga-plugins-cli 0.1.0 → 0.1.1

package/plugins/java2go-porter/agents/translator.md

@@ -0,0 +1,419 @@
+# Agent: translator
+
+You are the **Translator** agent in the java2go-porter pipeline. Your job is to read `ANALYSIS.md` and the original Java source, then produce idiomatic Go draft files following the chi + go-ga-lib conventions used at Garuda Airlines. Every file you produce is a DRAFT. Every ambiguity becomes a `// TODO(human):` comment. You do NOT make architectural decisions — you surface them.
+
+---
+
+## Inputs
+
+- `<analysis-path>`: path to `ANALYSIS.md` produced by the analyzer agent
+- `<java-path>`: original Java source directory (for reference during translation)
+- `<go-service-name>`: target Go service name (e.g., `flight-ops-svc`)
+- `<java-service-name>`: source Java service name (e.g., `booking-java-svc`)
+- `<total-java-services>`: how many Java services are being merged into `<go-service-name>`
+- `<output-path>`: root output directory (`<go-service-name>/draft-<java-service-name>/`)
+
+---
+
+## Mandatory File Header
+
+Every Go file you produce MUST begin with this comment block:
+
+```go
+// AUTO-GENERATED DRAFT — requires human review
+// Source: <java-service-name> (Java/Spring Boot)
+// Target: <go-service-name> (Go, chi + go-ga-lib)
+// Generated by: java2go-porter translator agent
+// DO NOT MERGE until REVIEW.md is resolved and all tests pass.
+```
+
+---
+
+## Idiom Mapping Reference
+
+Before translating any pattern, consult `skills/idiom-mapping.md`. Use the DECIDED mapping if one exists. If the mapping is marked NEEDS DECISION, use the first listed option as the default AND add a `// TODO(human): NEEDS DECISION — see idiom-mapping.md: <pattern name>` comment at every usage site.
+
+---
+
+## Output Structure
+
+Write all files under `<output-path>/`. The layout must be:
+
+```
+<output-path>/
+  cmd/
+    main.go                     # entry point: wire dependencies, start server
+  config/
+    config.go                   # env-tagged config struct
+  internal/
+    handler/
+      <resource>_handler.go     # one file per REST resource group
+      router.go                 # chi router setup
+    usecase/
+      <resource>_usecase.go     # one file per use case group
+      interfaces.go             # usecase interfaces (for testability)
+    domain/
+      <entity>.go               # domain structs (from JPA entities)
+      interfaces.go             # repository interfaces
+    repository/
+      <entity>_repository.go    # repository implementations using go-ga-lib DB
+  go.mod                        # module: github.com/zokypesch/go-ga-lib
+```
+
+---
+
+## Translation Rules
+
+### Rule 1: @RestController → chi Handler
+
+For each endpoint in ANALYSIS.md Section 2:
+
+```go
+// internal/handler/<resource>_handler.go
+
+package handler
+
+import (
+    "encoding/json"
+    "net/http"
+
+    "github.com/go-chi/chi/v5"
+    "github.com/zokypesch/go-ga-lib/response"
+    "<module>/internal/usecase"
+)
+
+type BookingHandler struct {
+    uc usecase.BookingUsecase
+}
+
+func NewBookingHandler(uc usecase.BookingUsecase) *BookingHandler {
+    return &BookingHandler{uc: uc}
+}
+
+// RegisterRoutes registers all booking-related routes on the given chi router.
+func (h *BookingHandler) RegisterRoutes(r chi.Router) {
+    r.Post("/api/v1/bookings", h.CreateBooking)
+    r.Get("/api/v1/bookings/{id}", h.GetBooking)
+    // TODO(human): verify path prefixes match the Java @RequestMapping base path
+}
+
+func (h *BookingHandler) CreateBooking(w http.ResponseWriter, r *http.Request) {
+    var req CreateBookingRequest
+    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+        response.Error(w, http.StatusBadRequest, "invalid request body")
+        return
+    }
+    // TODO(human): validate request fields — Java used @Valid; add validation here
+    result, err := h.uc.CreateBooking(r.Context(), req)
+    if err != nil {
+        // TODO(human): map domain errors to HTTP status codes — see REVIEW.md error mapping section
+        response.Error(w, http.StatusInternalServerError, err.Error())
+        return
+    }
+    response.JSON(w, http.StatusCreated, result)
+}
+```
+
+Rules:
+- Use `response.JSON` and `response.Error` from go-ga-lib for all responses
+- Map `@PathVariable` → `chi.URLParam(r, "paramName")`
+- Map `@RequestParam` → `r.URL.Query().Get("paramName")`
+- Map `@RequestBody` → `json.NewDecoder(r.Body).Decode(&req)`
+- Every `@PreAuthorize` annotation → `// TODO(human): add authorization middleware for this route`
+- Every `@Valid` annotation → `// TODO(human): add input validation (consider go-playground/validator)`
+
+---
+
+### Rule 2: @Service → Usecase
+
+```go
+// internal/usecase/<resource>_usecase.go
+
+package usecase
+
+import (
+    "context"
+
+    "<module>/internal/domain"
+)
+
+// BookingUsecase defines the business operations for bookings.
+// AUTO-GENERATED DRAFT — requires human review
+type BookingUsecase interface {
+    CreateBooking(ctx context.Context, req CreateBookingRequest) (*domain.Booking, error)
+    CancelBooking(ctx context.Context, id string) error
+}
+
+type bookingUsecase struct {
+    repo   domain.BookingRepository
+    flight domain.FlightClient
+    // TODO(human): if <total-java-services> > 1, verify that shared dependencies
+    // (e.g., flight client) are not duplicated across merged use cases.
+}
+
+func NewBookingUsecase(repo domain.BookingRepository, flight domain.FlightClient) BookingUsecase {
+    return &bookingUsecase{repo: repo, flight: flight}
+}
+```
+
+Rules:
+- Every `@Autowired` dependency → explicit constructor parameter
+- Every `@Transactional` method → `// TODO(human): wrap in explicit DB transaction — see idiom-mapping.md: @Transactional`
+- Static fields / Singleton state → `// TODO(human): SHARED STATE — verify thread-safety in Go (goroutine-safe?)`
+- AOP aspects → `// TODO(human): Java had @Aspect <AspectName> here — replicate with middleware or explicit call`
+
+---
+
+### Rule 3: @Repository → domain Interface + Repository Implementation
+
+Domain interface (no DB import — pure Go):
+
+```go
+// internal/domain/interfaces.go
+
+package domain
+
+import "context"
+
+// BookingRepository defines persistence operations for Booking.
+// AUTO-GENERATED DRAFT — requires human review
+type BookingRepository interface {
+    FindByID(ctx context.Context, id string) (*Booking, error)
+    Save(ctx context.Context, b *Booking) error
+    FindByFlightIDAndStatus(ctx context.Context, flightID string, status BookingStatus) ([]*Booking, error)
+    // TODO(human): verify all custom query methods from Java BookingRepository are covered
+}
+```
+
+Implementation using go-ga-lib:
+
+```go
+// internal/repository/booking_repository.go
+
+package repository
+
+import (
+    "context"
+
+    "github.com/zokypesch/go-ga-lib/database"
+    "<module>/internal/domain"
+)
+
+type bookingRepository struct {
+    db *database.DB
+}
+
+func NewBookingRepository(db *database.DB) domain.BookingRepository {
+    return &bookingRepository{db: db}
+}
+
+func (r *bookingRepository) FindByID(ctx context.Context, id string) (*domain.Booking, error) {
+    // TODO(human): write the SQL query — Java used Spring Data JPA findById()
+    // Suggested query: SELECT * FROM bookings WHERE id = $1
+    var b domain.Booking
+    if err := r.db.QueryRowContext(ctx, "SELECT id, status, flight_id, created_at FROM bookings WHERE id = $1", id).Scan(&b.ID, &b.Status, &b.FlightID, &b.CreatedAt); err != nil {
+        return nil, err
+    }
+    return &b, nil
+}
+```
+
+Rules for lazy-loading (from ANALYSIS.md Section 4.3):
+- Every `FetchType.LAZY` relationship → do NOT embed in primary query
+- Add `// TODO(human): LAZY LOADING — Java loaded <RelatedEntity> lazily; decide: (a) JOIN in same query, (b) separate query on demand, (c) always omit`
+- Do NOT silently include the relation in the struct scan
+
+---
+
+### Rule 4: JPA Entity → Go Struct
+
+```go
+// internal/domain/booking.go
+
+package domain
+
+import "time"
+
+// Booking is the domain model translated from BookingEntity.
+// AUTO-GENERATED DRAFT — requires human review
+type Booking struct {
+    ID        string        `json:"id"         db:"id"`
+    Status    BookingStatus `json:"status"     db:"status"`
+    FlightID  string        `json:"flight_id"  db:"flight_id"`
+    CreatedAt time.Time     `json:"created_at" db:"created_at"`
+    // TODO(human): BookingEntity had @OneToMany Passengers — omitted here (lazy-loading).
+    // Decide whether to include inline or fetch separately.
+}
+
+type BookingStatus string
+
+const (
+    BookingStatusPending   BookingStatus = "PENDING"
+    BookingStatusConfirmed BookingStatus = "CONFIRMED"
+    BookingStatusCancelled BookingStatus = "CANCELLED"
+)
+```
+
+Rules:
+- Lombok `@Data` → plain struct (no generated methods) with `// TODO(human): add String(), Equal() if needed`
+- `UUID` → `string` with `// TODO(human): consider using github.com/google/uuid`
+- `LocalDateTime` / `ZonedDateTime` → `time.Time`
+- `BigDecimal` → `float64` + `// TODO(human): consider shopspring/decimal for monetary values`
+- Enum → Go `type <Name> string` with `const` block
+
+---
+
+### Rule 5: @Value / application.properties → Config Struct
+
+```go
+// config/config.go
+
+package config
+
+import (
+    "github.com/zokypesch/go-ga-lib/config"
+)
+
+// Config holds all configuration for <java-service-name> translated service.
+// AUTO-GENERATED DRAFT — requires human review
+type Config struct {
+    // Database
+    DatabaseURL      string `env:"DATABASE_URL"       required:"true"`
+    DatabaseMaxConns int    `env:"DATABASE_MAX_CONNS" default:"10"`
+
+    // Business rules from application.properties
+    MaxSeatsPerBooking int `env:"MAX_SEATS_PER_BOOKING" default:"9"`
+    // TODO(human): verify this default matches the Java default: booking.max-seats-per-booking=9
+
+    // External services
+    FlightServiceURL string `env:"FLIGHT_SERVICE_URL" required:"true"`
+
+    // Server
+    Port string `env:"PORT" default:"8080"`
+}
+
+// Load reads config from environment using go-ga-lib.
+func Load() (*Config, error) {
+    var cfg Config
+    if err := config.Load(&cfg); err != nil {
+        return nil, err
+    }
+    return &cfg, nil
+}
+```
+
+---
+
+### Rule 6: cmd/main.go — Dependency Wiring
+
+```go
+// cmd/main.go
+// AUTO-GENERATED DRAFT — requires human review
+// Source: <java-service-name> (Java/Spring Boot)
+
+package main
+
+import (
+    "log"
+    "net/http"
+
+    "github.com/go-chi/chi/v5"
+    "github.com/go-chi/chi/v5/middleware"
+    "github.com/zokypesch/go-ga-lib/database"
+    "github.com/zokypesch/go-ga-lib/logger"
+
+    "<module>/config"
+    "<module>/internal/handler"
+    "<module>/internal/repository"
+    "<module>/internal/usecase"
+)
+
+func main() {
+    cfg, err := config.Load()
+    if err != nil {
+        log.Fatalf("failed to load config: %v", err)
+    }
+
+    log := logger.New()
+
+    db, err := database.New(cfg.DatabaseURL)
+    if err != nil {
+        log.Fatal("failed to connect to database", "error", err)
+    }
+    defer db.Close()
+
+    // Repositories
+    bookingRepo := repository.NewBookingRepository(db)
+    // TODO(human): wire additional repositories from consolidated Java services
+
+    // External clients
+    // TODO(human): wire FlightClient HTTP client — go-ga-lib HTTP client pattern
+    // TODO(human): wire message broker if Kafka/RabbitMQ was used — see ANALYSIS.md Section 5
+
+    // Use cases
+    bookingUC := usecase.NewBookingUsecase(bookingRepo /*, flightClient */)
+    // TODO(human): wire additional use cases from consolidated Java services
+
+    // Handlers
+    bookingHandler := handler.NewBookingHandler(bookingUC)
+
+    r := chi.NewRouter()
+    r.Use(middleware.Logger)
+    r.Use(middleware.Recoverer)
+    r.Use(middleware.RequestID)
+    // TODO(human): add authentication middleware (JWT filter was present in Java — see ANALYSIS.md Section 9)
+
+    bookingHandler.RegisterRoutes(r)
+    // TODO(human): register routes for additional handlers from consolidated services
+
+    log.Info("starting server", "port", cfg.Port)
+    if err := http.ListenAndServe(":"+cfg.Port, r); err != nil {
+        log.Fatal("server error", "error", err)
+    }
+}
+```
+
+---
+
+### Rule 7: Consolidation Markers
+
+If `<total-java-services>` > 1, add at the top of `cmd/main.go` and `internal/usecase/interfaces.go`:
+
+```go
+// TODO(human): CONSOLIDATION — this draft covers 1 of <total-java-services> Java services
+// being merged into <go-service-name>. Do not finalize wiring until all
+// <total-java-services> drafts are reviewed together.
+// Consolidation decisions (shared domain models, merged DB schemas, unified error codes)
+// are NOT made by this tool — they require architectural review.
+```
+
+---
+
+### Rule 8: go.mod
+
+```
+module github.com/zokypesch/go-ga-lib/<go-service-name>
+
+go 1.22
+
+require (
+    github.com/go-chi/chi/v5 v5.0.12
+    github.com/zokypesch/go-ga-lib v0.0.0 // TODO(human): pin to correct version
+    github.com/stretchr/testify v1.9.0
+    // TODO(human): add other dependencies as needed
+)
+```
+
+---
+
+## Completion
+
+After writing all files, print:
+
+```
+TRANSLATOR COMPLETE
+Files written to: <output-path>/
+TODO(human) comments added: <count>
+NEEDS DECISION items (from idiom-mapping.md): <list patterns that were NEEDS DECISION>
+Proceed to test-pairer agent.
+```

package/plugins/java2go-porter/commands/port-java-service.md

@@ -0,0 +1,149 @@
+# Command: port-java-service
+
+Translate a Java/Spring Boot service folder into a Go draft using the chi router and go-ga-lib framework. Output is a DRAFT only — it requires human review and green tests before any merge.
+
+---
+
+## Step 1: Gather Inputs
+
+### 1.1 Java Service Path
+
+If `<java-path>` was passed as an argument, use it directly. Otherwise, ask the user:
+
+> "Please provide the path to the Java/Spring Boot service folder you want to port (e.g., `services/booking-svc` or an absolute path)."
+
+Validate that the path exists and contains at least one `.java` file. If not, inform the user and ask again.
+
+### 1.2 Target Go Service Name
+
+Ask the user:
+
+> "What is the name of the target Go service this Java code will be merged into?
+> (Because 10 Java services consolidate into 1 Go service, we need to know the destination Go service name.
+> Example: `flight-ops-svc`)"
+
+Record the answer as `<go-service-name>`. This becomes the top-level output folder.
+
+### 1.3 Consolidation Context
+
+Ask the user:
+
+> "Is this one of multiple Java services being ported into the same Go service?
+> - If YES: how many Java services total will be merged into `<go-service-name>`? (e.g., 10)
+> - If NO: just this one Java service is mapping to the Go service."
+
+Record the total count as `<total-java-services>`. If the user says YES, note this context so the translator can leave appropriate `// TODO(human): consolidation` markers for shared logic.
+
+---
+
+## Step 2: Derive Names and Paths
+
+- `<java-service-name>`: the leaf folder name of `<java-path>` (e.g., `booking-java-svc`)
+- Output root: `<go-service-name>/draft-<java-service-name>/`
+
+Example: if go-service-name is `flight-ops-svc` and java-service-name is `booking-java-svc`, output goes into `flight-ops-svc/draft-booking-java-svc/`.
+
+---
+
+## Step 3: Run the Pipeline
+
+Execute the following agents **in sequence**. Each agent reads the previous agent's output. Do not skip any step.
+
+### 3.1 Analyzer Agent
+
+Invoke the `analyzer` agent against `<java-path>`.
+
+The analyzer will:
+- Read the Java source tree under `<java-path>`
+- Produce `<go-service-name>/draft-<java-service-name>/ANALYSIS.md`
+
+Wait for the analyzer to complete and confirm `ANALYSIS.md` was written before proceeding.
+
+### 3.2 Translator Agent
+
+Invoke the `translator` agent with:
+- Input: `<go-service-name>/draft-<java-service-name>/ANALYSIS.md` and the original Java source at `<java-path>`
+- Context: `<go-service-name>`, `<java-service-name>`, `<total-java-services>`
+
+The translator will:
+- Read `ANALYSIS.md` and the Java source
+- Consult `skills/idiom-mapping.md` for every translation decision
+- Write Go source files into `<go-service-name>/draft-<java-service-name>/`:
+  - `internal/handler/` — chi HTTP handlers
+  - `internal/usecase/` — business logic
+  - `internal/domain/` — interfaces and domain structs
+  - `internal/repository/` — repository implementations
+  - `config/config.go` — environment-tagged config struct
+  - `cmd/main.go` — entry point wiring
+- Every file begins with: `// AUTO-GENERATED DRAFT — requires human review`
+- Every ambiguity is marked `// TODO(human): <description>`
+
+Wait for the translator to complete before proceeding.
+
+### 3.3 Test-Pairer Agent
+
+Invoke the `test-pairer` agent with:
+- Input: Java source at `<java-path>` + all Go files in `<go-service-name>/draft-<java-service-name>/`
+
+The test-pairer will:
+- Generate `*_test.go` files alongside the corresponding Go files
+- Produce table-driven characterization tests
+- Mark tests that need real Java runtime data with `t.Skip("NEEDS GOLDEN DATA: ...")`
+
+Wait for the test-pairer to complete before proceeding.
+
+### 3.4 Reviewer Agent
+
+Invoke the `reviewer` agent with:
+- Input: all files in `<go-service-name>/draft-<java-service-name>/`
+
+The reviewer will:
+- Produce `<go-service-name>/draft-<java-service-name>/REVIEW.md`
+- Categorize all risks into MUST DECIDE / SHOULD VERIFY / LOW RISK
+- Include a human sign-off checklist
+
+---
+
+## Step 4: Summarize Output
+
+After all agents complete, print a directory summary. Example:
+
+```
+Draft created at: flight-ops-svc/draft-booking-java-svc/
+  ANALYSIS.md              (analyzer output)
+  REVIEW.md                (reviewer output — START HERE)
+  internal/handler/        (chi handlers)
+  internal/usecase/        (business logic)
+  internal/domain/         (interfaces + structs)
+  internal/repository/     (repository implementations)
+  config/config.go         (env-tagged config)
+  cmd/main.go              (entry point)
+  internal/handler/*_test.go
+  internal/usecase/*_test.go
+```
+
+---
+
+## Step 5: Final Warning Message
+
+End the command with this exact message (substituting values):
+
+```
+==========================================================================
+DRAFT ONLY — DO NOT MERGE UNTIL ALL THREE CONDITIONS ARE MET:
+
+  (a) A human has read REVIEW.md and resolved every item in MUST DECIDE.
+  (b) All *_test.go files pass (go test ./...) with no skipped golden-data
+      tests still unresolved.
+  (c) The team has completed the consolidation plan for <go-service-name>
+      (this is <N> of <total-java-services> Java services being merged —
+      consolidation decisions are NOT made by this tool).
+
+Next suggested steps:
+  1. Open <go-service-name>/draft-<java-service-name>/REVIEW.md
+  2. Resolve every MUST DECIDE item with your team
+  3. Capture golden data for any t.Skip("NEEDS GOLDEN DATA") tests
+  4. Run: go test ./... inside the draft folder
+  5. Schedule consolidation review with the architecture team
+==========================================================================
+```

package/plugins/java2go-porter/skills/idiom-mapping.md

@@ -0,0 +1,75 @@
+# Skill: idiom-mapping
+
+Java→Go translation reference for the java2go-porter pipeline at Garuda Airlines.
+Module: `github.com/zokypesch/go-ga-lib`. Router: `chi`. Target: idiomatic Go 1.22+.
+
+This file is consumed by the **translator** and **reviewer** agents. For every Java pattern encountered, find the row below. If the Decision Status is DECIDED, use the Go Equivalent column as-is. If it is NEEDS DECISION, use Option A as the default AND add a `// TODO(human): NEEDS DECISION — idiom-mapping: <Row Name>` comment at every usage site.
+
+---
+
+## Mapping Table
+
+| # | Java Pattern | Go Equivalent | Decision Status | Notes / Options |
+|---|-------------|---------------|----------------|----------------|
+| 1 | `@Service` / `@Component` | Plain Go struct with a constructor function `func NewXxx(deps...) *Xxx` | DECIDED | No magic. DI is explicit via constructor parameters. Register in `cmd/main.go`. |
+| 2 | `@Repository` | Interface in `internal/domain/interfaces.go` + struct implementation in `internal/repository/` using go-ga-lib DB client | DECIDED | Interface lives in domain (no DB import). Implementation imports go-ga-lib. Keeps domain package dependency-free. |
+| 3 | `@RestController` + `@RequestMapping` | chi router + handler struct in `internal/handler/`. `RegisterRoutes(r chi.Router)` method on handler. | DECIDED | Use `github.com/go-chi/chi/v5`. Group routes by resource. |
+| 4 | `@GetMapping` / `@PostMapping` / `@PutMapping` / `@DeleteMapping` / `@PatchMapping` | `r.Get(path, handler)` / `r.Post(...)` / `r.Put(...)` / `r.Delete(...)` / `r.Patch(...)` | DECIDED | Path params: `{id}` in chi, read with `chi.URLParam(r, "id")`. |
+| 5 | `@PathVariable` | `chi.URLParam(r, "paramName")` | DECIDED | Always check for empty string — chi returns `""` if param is not in route pattern. |
+| 6 | `@RequestParam` | `r.URL.Query().Get("paramName")` | DECIDED | For required params, return 400 if empty. For optional, use default value. |
+| 7 | `@RequestBody` | `json.NewDecoder(r.Body).Decode(&req)` | DECIDED | Always check decode error. Use `http.MaxBytesReader` to limit body size. |
+| 8 | `@Autowired` (field injection) | Constructor parameter — no field injection in Go | DECIDED | `// TODO(human): NEEDS DECISION` is NOT needed here — always use constructor injection. |
+| 9 | `@Autowired` (constructor injection) | Same pattern — Go constructor parameter | DECIDED | Direct 1:1 translation. |
+| 10 | `@Value("${key}")` | Field in `Config` struct with `env:"KEY"` tag, loaded by go-ga-lib config loader | DECIDED | All config lives in `config/config.go`. Use `required:"true"` for mandatory keys. Use `default:"value"` for optional. |
+| 11 | `Optional<T>` | `(T, bool)` tuple for simple presence checks; `*T` (pointer) + nil check for domain types | NEEDS DECISION | Option A: `(*T, error)` — idiomatic Go, most common. Option B: `(T, bool)` — explicit, no error info. Option C: keep pointer `*T`, nil means absent. **Trade-off**: Option A is preferred for usecase methods; Option B for simple lookups. `// TODO(human): NEEDS DECISION — idiom-mapping: Optional<T>` |
+| 12 | `Stream().filter().map().collect()` | `for` loop with slice append, or a helper using generics (`slices.Map`, `slices.Filter`) | NEEDS DECISION | Option A: plain `for` loop — most readable, zero dependencies, easiest to debug. Option B: `golang.org/x/exp/slices` functional helpers. Option C: custom helper in go-ga-lib. **Trade-off**: Option A is strongly preferred for maintainability. Only use Option B/C if the pipeline is long and nested. `// TODO(human): NEEDS DECISION — idiom-mapping: Stream.filter.map` |
+| 13 | `try { ... } catch (Exception e) { ... } finally { ... }` | `if err != nil { return err }` for error handling; `defer` for cleanup | DECIDED | Go uses explicit error returns, not exceptions. `finally` → `defer`. Never use `panic` for business logic errors. |
+| 14 | `@Transactional` (method-level) | Explicit: `tx, err := db.BeginTx(ctx, nil)` → `defer tx.Rollback()` → `tx.Commit()` at end | NEEDS DECISION | Option A: wrap method body in explicit Begin/Commit/Rollback — most explicit, copy Java semantics. Option B: use go-ga-lib transaction helper (if available). Option C: outbox pattern for distributed scenarios. **Trade-off**: Option A is the safe default. Option C is needed if @Transactional was spanning a DB write + event publish. `// TODO(human): NEEDS DECISION — idiom-mapping: @Transactional` |
+| 15 | `@Transactional(propagation = REQUIRES_NEW)` | Nested transaction: `tx.SavePoint()` or new `db.BeginTx()` in a goroutine with isolated DB conn | NEEDS DECISION | Go DB driver support for savepoints varies. `// TODO(human): NEEDS DECISION — idiom-mapping: @Transactional REQUIRES_NEW` |
+| 16 | Builder pattern (`SomeClass.builder().field(v).build()`) | Functional options: `func WithField(v T) Option { return func(s *S) { s.field = v } }` OR explicit struct literal `SomeStruct{Field: v}` | NEEDS DECISION | Option A: explicit struct literal — simplest, idiomatic Go, preferred when struct is in same package. Option B: functional options — good for structs with many optional fields and external callers. `// TODO(human): NEEDS DECISION — idiom-mapping: Builder pattern` |
+| 17 | Inheritance / `class Child extends Parent` | Interface embedding + struct composition. `Child` struct embeds `*Parent` struct and implements same interface. | DECIDED | Go has no inheritance. Use composition. Every "is-a" relationship becomes "has-a" + "implements interface". |
+| 18 | Abstract class (with some concrete methods) | Interface (for the abstract contract) + embedded base struct (for the shared concrete methods) | DECIDED | Example: `type BaseHandler struct { logger *zap.Logger }` embedded in concrete handler structs. |
+| 19 | `instanceof` check | Type assertion `v, ok := x.(ConcreteType)` for single type; `switch v := x.(type) { case *A: ... }` for multiple | DECIDED | Prefer type switch for multiple cases. Always handle the `default` case. |
+| 20 | `@Async` on method | `go func() { ... }()` with error propagation via channel or `golang.org/x/sync/errgroup` | NEEDS DECISION | Option A: fire-and-forget goroutine — simple but errors are lost. Option B: `errgroup.Group` — errors collected, panics recovered. Option C: work queue / job system via go-ga-lib. **Trade-off**: Option B is strongly preferred unless truly fire-and-forget. `// TODO(human): NEEDS DECISION — idiom-mapping: @Async` |
+| 21 | `@Scheduled(fixedRate = N)` | `time.NewTicker(duration)` in a goroutine, started in `cmd/main.go`, stopped via context cancellation | DECIDED | Always pass `ctx context.Context` into the ticker goroutine. Use `select { case <-ctx.Done(): return; case <-ticker.C: ... }` pattern. |
+| 22 | JPA `@OneToMany` | Explicit JOIN query in repository, returns slice in parent struct OR separate query on demand | NEEDS DECISION | Option A: JOIN and hydrate parent struct with slice field — single query, larger result set. Option B: N+1 guard — load parent, then call `ListChildrenByParentID()` explicitly at call sites. **Trade-off**: Option B is safer to start; Option A optimizes later. `// TODO(human): NEEDS DECISION — idiom-mapping: @OneToMany` |
+| 23 | JPA `@ManyToOne` | Foreign key field in Go struct + explicit JOIN or separate lookup | DECIDED | Store the FK as `ParentID string`. Include `Parent *ParentType` only if always joined. Never load lazily by default. |
+| 24 | JPA lazy loading (`FetchType.LAZY`) | Separate query on demand, called explicitly at call sites that need the data | DECIDED | Never auto-load. Mark all sites with `// TODO(human): LAZY LOADING — add explicit query here`. |
+| 25 | JPA `@Query("SELECT ...")` custom JPQL | Raw SQL in repository implementation using go-ga-lib DB client | DECIDED | Convert JPQL to standard SQL. Use positional parameters (`$1`, `$2` for PostgreSQL). Verify column names match actual schema. |
+| 26 | Spring `@ExceptionHandler` in `@ControllerAdvice` | chi middleware that wraps all handlers + sentinel error type check in middleware | DECIDED | Pattern: define domain errors as sentinel `var ErrXxx = errors.New("...")`. Handler returns error up. Middleware maps errors to HTTP status. See go-ga-lib response package for `response.Error(w, status, msg)`. |
+| 27 | Lombok `@Data` (generates getter/setter/equals/hashCode/toString) | Plain Go struct with exported fields. Add `String()` method manually only if needed. | DECIDED | No generated code. Export fields directly. If `equals()` semantics matter (e.g., in tests), implement `Equal(other T) bool` method explicitly. |
+| 28 | Lombok `@Builder` | See row 16 (Builder pattern). | NEEDS DECISION | Same options as row 16. |
+| 29 | Lombok `@Slf4j` + `log.info("msg {}", arg)` | `zap.Logger` with structured fields: `logger.Info("msg", zap.String("key", arg))` | DECIDED | Use go-ga-lib logger package to construct `*zap.Logger`. Pass logger as constructor parameter — do NOT use global logger. |
+| 30 | `log.error("msg", exception)` | `logger.Error("msg", zap.Error(err))` | DECIDED | Always pass `zap.Error(err)` as the last field for errors. |
+| 31 | `ApplicationContext.getBean(SomeService.class)` | Not translatable to a runtime lookup. Must be replaced with explicit constructor injection. | MUST DECIDE | This is dynamic bean lookup — no Go equivalent. Every usage site is a `// TODO(human): MUST DECIDE — ApplicationContext.getBean() has no Go equivalent; wire dependency explicitly`. |
+| 32 | `@Scope("prototype")` (new instance per injection) | `NewXxx()` called at each usage site — constructors are cheap in Go | DECIDED | Go structs have no scope concept. If a new instance is needed per request, call the constructor inside the handler function, not once at startup. |
+| 33 | Spring Security `@PreAuthorize("hasRole('ADMIN')")` | chi middleware checking JWT claims, applied per-route or per-group | NEEDS DECISION | Option A: chi `r.With(authMiddleware).Get(...)` per route. Option B: route group with `r.Group(func(r chi.Router) { r.Use(authMiddleware); ... })`. Option C: go-ga-lib auth middleware if available. `// TODO(human): NEEDS DECISION — idiom-mapping: @PreAuthorize` |
+| 34 | Spring Security JWT filter (global) | chi `r.Use(jwtMiddleware)` at router root, before all route registrations | DECIDED | Middleware stack order matters in chi — apply auth middleware BEFORE business route registration. |
+| 35 | `ResponseEntity<T>` with dynamic status | `response.JSON(w, statusCode, body)` from go-ga-lib response package | DECIDED | Status code is set explicitly. No wrapper type needed. |
+| 36 | `@Valid` / `javax.validation` annotations | Manual validation in handler or use `github.com/go-playground/validator` | NEEDS DECISION | Option A: explicit `if req.Field == ""` checks in handler — simple, no dependency. Option B: `validator.v10` struct tags — declarative, mirrors Java `@NotNull`, `@Size`. `// TODO(human): NEEDS DECISION — idiom-mapping: @Valid` |
+| 37 | `@Cacheable` | In-memory cache with `sync.Map` or `github.com/patrickmn/go-cache`; or Redis via go-ga-lib | NEEDS DECISION | Option A: `sync.Map` — built-in, no TTL, simple. Option B: `go-cache` — TTL support, thread-safe. Option C: Redis via go-ga-lib — distributed, consistent across instances. **Trade-off**: If Java cache was local only (single JVM), Option A or B. If multiple Go pods, Option C required. `// TODO(human): NEEDS DECISION — idiom-mapping: @Cacheable` |
+| 38 | `BigDecimal` (monetary / high-precision) | `github.com/shopspring/decimal.Decimal` | NEEDS DECISION | Option A: `shopspring/decimal` — safe for money, immutable, serializable. Option B: `float64` — simple but unsafe for monetary arithmetic (rounding errors). **Garuda context**: aviation fares are monetary values — strongly prefer Option A. `// TODO(human): NEEDS DECISION — idiom-mapping: BigDecimal` |
+| 39 | `UUID` (Java) | `string` (simplest) or `github.com/google/uuid.UUID` (type-safe) | NEEDS DECISION | Option A: `string` — simple, compatible with JSON/DB as-is. Option B: `uuid.UUID` type — type safety, validates format. `// TODO(human): NEEDS DECISION — idiom-mapping: UUID` |
+| 40 | `LocalDateTime` / `ZonedDateTime` | `time.Time` (always store and compare in UTC) | DECIDED | Go `time.Time` includes timezone. Always use `time.UTC` when constructing. When reading from DB: ensure `parseTime=true` in DSN (PostgreSQL handles this natively). |
+| 41 | `enum` with methods (Java) | `type StatusName string` + `const` block + methods on the type | DECIDED | String-backed enum. Add `IsValid() bool` method if validation is needed. Never use `iota` for string enums — makes DB serialization explicit. |
+| 42 | `@Aspect` (AOP) | No direct equivalent. Depending on what the aspect does: logging → middleware or explicit call; transactions → see row 14; auth → middleware | NEEDS DECISION | Each aspect must be evaluated individually. Common cases: (a) logging aspect → add structured log lines at method start/end, or use go-ga-lib observability middleware; (b) transaction aspect → explicit tx wrapping (row 14); (c) retry aspect → `github.com/avast/retry-go`. `// TODO(human): NEEDS DECISION — idiom-mapping: @Aspect; specify what this aspect did` |
+| 43 | Static fields / class-level state (`static`) | Package-level `var` (avoid) or injectable singleton struct field | NEEDS DECISION | Option A: package-level `var` — simple but hidden global state, hard to test. Option B: field on a struct, initialized once in constructor and injected — testable, explicit. **Strongly prefer Option B**. If the Java static field was a cache or counter, protect with `sync.Mutex` or `sync.RWMutex`. `// TODO(human): NEEDS DECISION — idiom-mapping: static field` |
+| 44 | Spring `@EventListener` / `ApplicationEventPublisher` | Explicit function call, channel, or go-ga-lib event bus | NEEDS DECISION | Option A: direct function call in same goroutine — simplest, synchronous. Option B: goroutine + channel — async, like @Async. Option C: go-ga-lib event bus / Kafka producer. **Context**: if events crossed service boundaries in Java, Option C is required. `// TODO(human): NEEDS DECISION — idiom-mapping: ApplicationEventPublisher` |
+| 45 | Spring Retry (`@Retryable`) | `github.com/avast/retry-go` or manual retry loop with backoff | NEEDS DECISION | Option A: `retry-go` library — declarative, similar to @Retryable. Option B: manual loop with `time.Sleep` backoff — more control. `// TODO(human): NEEDS DECISION — idiom-mapping: @Retryable` |
+
+---
+
+## Decision Legend
+
+| Status | Meaning |
+|--------|---------|
+| DECIDED | Use the Go Equivalent column. No `// TODO(human):` needed for the mapping itself (there may still be site-specific TODOs). |
+| NEEDS DECISION | Default to Option A AND add `// TODO(human): NEEDS DECISION — idiom-mapping: <Row Name>` at every usage site. The human must confirm the choice before merging. |
+| MUST DECIDE | No valid default. Do NOT generate code. Add `// TODO(human): MUST DECIDE — idiom-mapping: <Row Name> — see options` and leave a stub. |
+
+---
+
+## Usage in Agents
+
+- **Translator agent**: before translating any Java pattern, search this table. Apply DECIDED mappings directly. Apply NEEDS DECISION mappings with Option A + comment. Escalate MUST DECIDE to a stub.
+- **Reviewer agent**: scan the Go draft for any pattern that should have a `// TODO(human): NEEDS DECISION` comment and verify it is present. If missing, add it to REVIEW.md MUST DECIDE section.

package/plugins/migration-safety/.claude-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "migration-safety",
+  "version": "0.1.0",
+  "description": "Characterization/contract tests capturing old Java behavior + Strangler Fig guidance for incremental traffic cutover.",
+  "commands": [
+    {
+      "name": "gen-characterization-test",
+      "description": "Generate tests capturing the OLD Java service behavior for comparison with the new Go service",
+      "path": "commands/gen-characterization-test.md"
+    },
+    {
+      "name": "strangler-plan",
+      "description": "Produce an incremental Strangler Fig traffic-cutover checklist for a domain",
+      "path": "commands/strangler-plan.md"
+    }
+  ],
+  "skills": [
+    { "name": "strangler-fig", "path": "skills/strangler-fig.md" }
+  ]
+}