coding-os 0.3.2__py3-none-any.whl

templates/go-fiber/skills/go-fiber/references/anatomy.md

@@ -0,0 +1,116 @@
+<!-- domain:GOFIBER | layer:reference | ssot:true | updated:2026-04-29 -->
+# Go + Fiber Anatomy
+
+> P: Canonical file map and entity recipes for the Go + Fiber v3 stack.
+> R: Adding any `.go` file under `src/backend/` or `cmd/`, or routing a backend task.
+> S: Working on frontend / mobile / web code.
+> N: [SKILL.md](../SKILL.md), [scaffold-boundary.yaml](../../../scaffold-boundary.yaml)
+
+> Nav: [Skill](../SKILL.md)
+
+---
+
+## 1. Boundary
+
+SSOT: [`src/templates/go-fiber/scaffold-boundary.yaml`](../../../scaffold-boundary.yaml).
+
+## 2. Layout map
+
+| Pattern | Location | Naming | Imports from | Description |
+|---|---|---|---|---|
+| App entry | `cmd/<service>/main.go` | `main.go` | `internal/...` | Wires fiber.New() |
+| Fiber handler | `internal/<domain>/handler.go` | `handler.go` | `..service` | `func(c fiber.Ctx) error` |
+| Middleware | `internal/middleware/<name>.go` | `<name>.go` | `fiber.Handler` | Auth, logging, etc. |
+| Service | `internal/<domain>/service.go` | `service.go` | `..repo` | Business logic |
+| Repository | `internal/<domain>/repo.go` | `repo.go` | `database/sql` | DB access |
+| Domain entity | `internal/<domain>/<entity>.go` | `<entity>.go` | `time` | Plain struct + methods |
+| DTO / Request | `internal/<domain>/dto.go` | `dto.go` | `validator` | Wire format + validation tags |
+| Errors | `internal/<domain>/errors.go` | `errors.go` | none | Sentinel + wrap helpers |
+| Migration | `migrations/<rev>_<slug>.up.sql` | `<rev>_<slug>.up.sql` | none | golang-migrate format |
+| Config | `internal/config/config.go` | `config.go` | `os`, `flag` | env / flag binding |
+| Test | `internal/<domain>/<file>_test.go` | `<file>_test.go` | source under test | Table-driven |
+| Integration test | `internal/<domain>/integration_test.go` | tagged `//go:build integration` | testcontainers | Real DB |
+
+## 3. Entity recipes
+
+### Add a new Fiber handler
+
+- **Trigger:** "add POST /api/users", "expose endpoint X".
+- **Files:**
+  1. `internal/<domain>/handler.go` (extend or create)
+  2. `internal/<domain>/dto.go`
+  3. `internal/<domain>/handler_test.go`
+- **Steps:**
+  1. Handler returns `fiber.Handler`; constructor takes the service.
+  2. Bind body via `c.Bind().Body(&req)`; validate via tags.
+  3. Call into service; map sentinel errors to status codes via a single helper.
+  4. Use `c.Status(code).JSON(envelope)` — never write raw bytes.
+  5. Test with `app.Test(req)` + table-driven cases.
+- **Generator:** [`src/scripts/new_endpoint.py`](../scripts/new_endpoint.py).
+
+### Add a new middleware
+
+- **Trigger:** "add auth middleware", "log every request".
+- **Files:**
+  1. `internal/middleware/<name>.go`
+  2. `internal/middleware/<name>_test.go`
+- **Steps:**
+  1. Return `fiber.Handler`; pass dependencies via the constructor.
+  2. Always call `c.Next()` on the success path; return `nil` only after Next.
+  3. Recover panics where applicable (`c.Status(500).JSON(...)`).
+  4. Test with a fake fiber app and table-driven cases.
+
+### Add a new service
+
+- **Trigger:** "extract logic", "share business rule".
+- **Files:**
+  1. `internal/<domain>/service.go`
+  2. `internal/<domain>/service_test.go`
+- **Steps:**
+  1. Constructor `NewService(repo Repo) *Service`.
+  2. Methods take `context.Context` first; pass `c.Context()` from handler.
+  3. Wrap errors with `fmt.Errorf("...: %w", err)`.
+  4. Mock the repo via interface in tests.
+
+### Add a new migration
+
+- **Trigger:** schema change.
+- **Files:**
+  1. `migrations/<rev>_<slug>.up.sql`
+  2. `migrations/<rev>_<slug>.down.sql`
+- **Steps:**
+  1. Append-only — never edit a merged migration.
+  2. Up must be reversible by down on a copy of prod.
+
+### Add a new test
+
+- **Trigger:** any new handler / middleware / service / repo requires tests.
+- **Files:**
+  1. `<source>_test.go` next to source.
+- **Steps:**
+  1. Table-driven; sub-tests via `t.Run(tt.name, …)`.
+  2. `app.Test(req)` for HTTP-level; mock service for handler tests.
+  3. Race detector on CI: `go test -race ./...`.
+
+## 4. Conventions
+
+#### Naming
+
+- Files: `snake_case.go`.
+- Packages: `lowercase`, no underscores.
+- Exported symbols: `PascalCase`.
+- Unexported symbols: `camelCase`.
+- Interfaces named for the role (`Reader`, `Repo`).
+
+#### Test colocation
+
+Colocated. `service.go` ⇄ `service_test.go` in the same package. Integration tests carry `//go:build integration`. No mirror dirs.
+
+#### Dependency rules
+
+- ✓ `cmd/` may import from `internal/`.
+- ✓ `internal/<domain>/handler.go` → `service.go` → `repo.go`.
+- ✓ Middleware lives in `internal/middleware/` and may import from `internal/contracts/` only.
+- ✗ Repos may NOT import from services or handlers.
+- ✗ Domains may NOT import from sibling `internal/<other-domain>/` — go through `internal/contracts/`.
+- ✗ `src/backend/` may NOT import from `src/frontend/`, `src/mobile/`, `src/ai-service/`.

templates/go-fiber/skills/go-fiber/references/fiber-v3-patterns.md

@@ -0,0 +1,89 @@
+<!-- domain:GO | layer:reference | ssot:true | updated:2026-06-04 -->
+# Fiber v3 Patterns (2026)
+
+> P: Build Fiber v3 handlers/middleware correctly — routing, binding, validation, errors.
+> R: Writing or reviewing a Fiber handler, middleware, or app setup.
+> S: General Go idioms — see the go-patterns skill's go-2026-idioms reference.
+> N: [SKILL.md](../SKILL.md), [fiber-checklist.md](../assets/fiber-checklist.md)
+
+> Nav: [Skill](../SKILL.md)
+
+Fiber v3 (GA Feb 2026) requires Go 1.25+. Some v2 signatures changed — check
+[versions.json](../versions.json) and the migration notes when porting.
+
+## Handler + error model
+
+```go
+app.Get("/users/:id", func(c fiber.Ctx) error {     // v3: fiber.Ctx (interface), return error
+    id, err := c.ParamsInt("id")
+    if err != nil {
+        return fiber.NewError(fiber.StatusBadRequest, "invalid id")
+    }
+    u, err := svc.Get(c.Context(), id)               // pass the request context down
+    if err != nil {
+        return err                                    // central error handler formats it
+    }
+    return c.JSON(u)
+})
+```
+
+Handlers return `error` — don't write error responses inline; return a
+`fiber.NewError(status, msg)` (or a wrapped error) and let a **central error
+handler** render the envelope consistently:
+
+```go
+app := fiber.New(fiber.Config{
+    ErrorHandler: func(c fiber.Ctx, err error) error {
+        code := fiber.StatusInternalServerError
+        var fe *fiber.Error
+        if errors.As(err, &fe) { code = fe.Code }
+        return c.Status(code).JSON(fiber.Map{"error": fiber.Map{"message": err.Error()}})
+    },
+})
+```
+
+## Binding + validation
+
+```go
+type CreateUser struct {
+    Email string `json:"email" validate:"required,email"`
+    Name  string `json:"name"  validate:"required,min=2"`
+}
+
+func create(c fiber.Ctx) error {
+    var body CreateUser
+    if err := c.Bind().Body(&body); err != nil {      // v3 binding API
+        return fiber.NewError(fiber.StatusBadRequest, "bad body")
+    }
+    if err := validate.Struct(body); err != nil {     // go-playground/validator
+        return fiber.NewError(fiber.StatusUnprocessableEntity, err.Error())
+    }
+    ...
+}
+```
+
+Bind then validate at the boundary; never trust the body. Keep DTOs separate from
+domain types (the api-contract-discipline applied to Fiber).
+
+## Middleware — order matters
+
+```go
+app.Use(recover.New())        // catch panics → 500, don't crash the process
+app.Use(requestid.New())      // correlation id for logs/traces
+app.Use(logger.New())         // structured request log
+app.Use(cors.New(corsCfg))    // before auth
+// auth middleware AFTER cors, BEFORE protected routes
+protected := app.Group("/api", authMiddleware)
+```
+
+Recover first (so a panic in any later middleware/handler is caught), then
+requestid/logger, then cross-cutting (cors), then auth on the protected group.
+Auth is owned by [auth-patterns](../../../core/skills/auth-patterns/SKILL.md);
+security review by [security-web](../../../core/skills/security-web/SKILL.md).
+
+## Performance notes
+
+Fiber is fasthttp-based — `fiber.Ctx` and its buffers are **reused across
+requests**; never retain a reference to `c` or its byte slices after the handler
+returns (copy what you need). Stream large bodies; set sane `BodyLimit`,
+`ReadTimeout`, `WriteTimeout` in `fiber.Config`.

templates/go-fiber/skills/go-fiber/scripts/new_endpoint.py

@@ -0,0 +1,107 @@
+"""Generate a Go + Fiber handler scaffold per `references/anatomy.md`.
+
+PURPOSE:      Emit handler + dto + service + test stubs in one shot.
+INPUT:        --domain <name>   — internal/<domain>/.
+              [--root <dir>]    — defaults to repo root (cwd).
+OUTPUT:       Four files: handler.go, dto.go, service.go, handler_test.go
+              under `internal/<domain>/`.
+DEPENDENCIES: stdlib only.
+NOTES:        Idempotent — refuses to overwrite existing files.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+
+def _pascal(name: str) -> str:
+    return "".join(part.capitalize() for part in name.split("-") if part)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    parser.add_argument("--domain", required=True)
+    parser.add_argument("--root", default=".")
+    args = parser.parse_args()
+
+    pkg_dir = Path(args.root) / "internal" / args.domain
+    pkg_dir.mkdir(parents=True, exist_ok=True)
+    pkg_name = args.domain.replace("-", "")
+    type_name = _pascal(args.domain)
+
+    files = {
+        pkg_dir / "dto.go": (
+            f"package {pkg_name}\n\n"
+            f"type {type_name}Request struct {{\n"
+            f"    // TODO: fields with `validate:` tags\n"
+            f"}}\n\n"
+            f"type {type_name}Response struct {{\n"
+            f"    // TODO: fields\n"
+            f"}}\n"
+        ),
+        pkg_dir / "service.go": (
+            f"package {pkg_name}\n\n"
+            f'import "context"\n\n'
+            f"type Service struct {{\n"
+            f"    // TODO: repo deps\n"
+            f"}}\n\n"
+            f"func NewService() *Service {{ return &Service{{}} }}\n\n"
+            f"func (s *Service) Create(ctx context.Context, req {type_name}Request) ({type_name}Response, error) {{\n"
+            f"    return {type_name}Response{{}}, nil\n"
+            f"}}\n"
+        ),
+        pkg_dir / "handler.go": (
+            f"package {pkg_name}\n\n"
+            f'import "github.com/gofiber/fiber/v3"\n\n'
+            f"type Handler struct {{ Service *Service }}\n\n"
+            f"func NewHandler(s *Service) *Handler {{ return &Handler{{Service: s}} }}\n\n"
+            f"func (h *Handler) Create(c fiber.Ctx) error {{\n"
+            f"    var req {type_name}Request\n"
+            f"    if err := c.Bind().Body(&req); err != nil {{\n"
+            f'        return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{{"error": err.Error()}})\n'
+            f"    }}\n"
+            f"    resp, err := h.Service.Create(c.Context(), req)\n"
+            f"    if err != nil {{\n"
+            f'        return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{{"error": err.Error()}})\n'
+            f"    }}\n"
+            f"    return c.Status(fiber.StatusCreated).JSON(resp)\n"
+            f"}}\n"
+        ),
+        pkg_dir / "handler_test.go": (
+            f"package {pkg_name}\n\n"
+            f"import (\n"
+            f'    "net/http/httptest"\n'
+            f'    "strings"\n'
+            f'    "testing"\n\n'
+            f'    "github.com/gofiber/fiber/v3"\n'
+            f")\n\n"
+            f"func TestCreate_ReturnsCreated(t *testing.T) {{\n"
+            f"    app := fiber.New()\n"
+            f"    h := NewHandler(NewService())\n"
+            f'    app.Post("/{args.domain}/", h.Create)\n'
+            f'    req := httptest.NewRequest("POST", "/{args.domain}/", strings.NewReader("{{}}"))\n'
+            f'    req.Header.Set("Content-Type", "application/json")\n'
+            f"    resp, err := app.Test(req)\n"
+            f"    if err != nil {{ t.Fatal(err) }}\n"
+            f"    if resp.StatusCode != fiber.StatusCreated {{\n"
+            f'        t.Fatalf("want 201, got %d", resp.StatusCode)\n'
+            f"    }}\n"
+            f"}}\n"
+        ),
+    }
+
+    for path in files:
+        if path.exists():
+            print(f"ERROR: refuse to overwrite existing file: {path}", file=sys.stderr)
+            return 1
+    for path, body in files.items():
+        path.write_text(body, encoding="utf-8")
+        print(f"OK: wrote {path}")
+    print(f"INFO: register the handler in cmd/<service>/main.go (fiber.New)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

templates/go-fiber/skills/go-fiber/versions.json

@@ -0,0 +1,16 @@
+{
+  "go": {
+    "ecosystem": "gotoolchain",
+    "package": "go",
+    "version": "1.26.4",
+    "source": "https://go.dev/dl/",
+    "checked": "2026-06-04"
+  },
+  "fiber": {
+    "ecosystem": "go",
+    "package": "github.com/gofiber/fiber/v3",
+    "version": "3.0.0",
+    "source": "https://github.com/gofiber/fiber/releases",
+    "checked": "2026-06-04"
+  }
+}

templates/go-fiber/stack.yaml

@@ -0,0 +1,59 @@
+version: 1
+id: go-fiber
+language: go
+label: "Go + Fiber (gofiber/fiber v3) + PostgreSQL"
+category: backend
+
+structure:
+  root: src/backend
+  tree: |
+    src/backend/
+    ├── cmd/api/
+    └── internal/{domain,ports,adapters,handlers,middleware}
+  notes: "hexagonal: domain/ports/adapters; fiber handlers stay thin"
+primary_skill: go-fiber
+skills: [go-fiber]
+
+# These substitution keys are joined across stacks by the aggregator via
+# _derive_substitutions (joined on " | "). VERIFY_BACKEND_* override the
+# "(none)" defaults from base.yaml.
+substitutions:
+  DOMAIN_ROUTES: "Backend→`docs/playbooks/fiber-service.md`"
+  SKILL_ROUTES: "Backend→`go-fiber`"
+  ENGINEERING_RULE_ROUTING: "Backend→`docs/engineering/fiber-rules.md`, Error format→`docs/api-contracts/error-format.md`"
+  TOOL_ROUTING_IMPL: "`lint-backend`, `test-backend`"
+  VERIFY_BACKEND_GLOB: "`src/backend/`"
+  VERIFY_BACKEND_SUITES: "lint-backend + test-backend"
+  VERIFY_BACKEND: "`cd src/backend && go vet ./... && go test ./...`"
+  QUICK_ROUTING: |-
+    - Backend / API task → [Fiber Service Playbook](./playbooks/fiber-service.md)
+  STACK_REF_CODES: |-
+    - `REF:PLAYBOOK-FIBER` → `./playbooks/fiber-service.md`
+    - `REF:FIBER-RULES` → `./engineering/fiber-rules.md`
+
+ref_codes:
+  - {code: "REF:PLAYBOOK-FIBER", path: "./playbooks/fiber-service.md", desc: "Fiber service playbook"}
+  - {code: "REF:FIBER-RULES",    path: "./engineering/fiber-rules.md",  desc: "Fiber engineering rules"}
+
+routing_entries:
+  - "Backend / API task → [Fiber Service Playbook](./docs/playbooks/fiber-service.md)"
+
+rules:
+  - {file: rules/backend.md, globs: ["src/backend/**/*.go"]}
+
+makefile_targets:
+  - {name: lint-backend, cmd: "cd src/backend && go vet ./..."}
+  - {name: test-backend, cmd: "cd src/backend && go test ./..."}
+
+verify:
+  - {glob: "src/backend/**/*.go", suites: "lint-backend + test-backend", cmd: "cd src/backend && go vet ./... && go test ./..."}
+
+dimensions:
+  - {name: "Fiber handler",    read_files: ["docs/playbooks/fiber-service.md", "docs/engineering/fiber-rules.md"]}
+  - {name: "Middleware / auth", read_files: ["docs/engineering/fiber-rules.md"]}
+  - {name: "Request validation / DTO", read_files: ["docs/engineering/fiber-rules.md", "docs/api-contracts/error-format.md"]}
+
+skill_enforcement:
+  - {globs: ["src/backend/**/*.go"], primary: go-fiber, secondary: [clean-code, backend-fundamentals, api-design, hexagonal-architecture, auth-patterns, security-web, testing-strategy, observability]}
+  - {globs: ["src/backend/**/db/**/*.go", "src/backend/**/migrations/**/*.go", "src/backend/**/repository/**/*.go"], primary: go-fiber, secondary: [clean-code, db-design, backend-fundamentals]}
+  - {globs: ["src/backend/**/auth*.go", "src/backend/**/middleware/auth*.go"], primary: go-fiber, secondary: [auth-patterns, security-web, clean-code]}

templates/go-plain/scaffold/src/backend/go.mod

@@ -0,0 +1,3 @@
+module {{PROJECT_NAME}}
+
+go 1.22

templates/go-plain/scaffold/src/backend/main.go

@@ -0,0 +1,7 @@
+package main
+
+import "fmt"
+
+func main() {
+	fmt.Println("{{PROJECT_NAME}} — scaffolded by coding-os (go-plain)")
+}

templates/go-plain/scaffold-boundary.yaml

@@ -0,0 +1,22 @@
+# Scaffold boundary for the go-plain stack (stdlib only).
+# Schema: docs/governance/scaffold-boundary-contract.md
+
+version: 1
+stack: go-plain
+
+roots:
+  - src/backend/
+
+file_patterns:
+  - "src/backend/**/*.go"
+
+imports_from:
+  - src/shared/
+  - src/shared/contracts/
+
+forbids_writing_in:
+  - src/frontend/
+  - src/mobile/
+
+notes:
+  - "Plain Go module — go.mod lives in src/backend/. Framework stacks (go, go-fiber) replace this layout."

templates/go-plain/stack.yaml

@@ -0,0 +1,51 @@
+version: 1
+id: go-plain
+language: go
+label: "Go (plain — stdlib only, no framework)"
+category: backend
+primary_skill: null
+skills: []
+
+structure:
+  root: src/backend
+  tree: |
+    src/backend/
+    ├── go.mod
+    ├── main.go
+    └── internal/        # grow into internal/-centric layout as the module grows
+  notes: "plain module; hexagonal internal/{domain,ports,adapters} when it becomes a service"
+
+# Plain-language stack (template-authoring.md § Language layer): picked when
+# the user chooses "go" without a framework. Ships a runnable module skeleton
+# and the verify wiring; framework stacks (go, go-fiber) extend the language
+# with their own conventions.
+
+substitutions:
+  DOMAIN_ROUTES: "Go module / CLI task → AGENTS.md critical rules"
+  SKILL_ROUTES: "Go → `clean-code` (generic) + `thinking_os` (kernel)"
+  ENGINEERING_RULE_ROUTING: "Go → AGENTS.md critical rules + `docs/governance/`"
+  TOOL_ROUTING_IMPL: "`lint-go`, `test-go`"
+  VERIFY_BACKEND_GLOB: "`src/backend/`"
+  VERIFY_BACKEND_SUITES: "lint-go + test-go"
+  VERIFY_BACKEND: "`cd src/backend && go vet ./... && go test ./...`"
+  QUICK_ROUTING: |-
+    - Go module / package task → see AGENTS.md critical rules
+  STACK_REF_CODES: ""
+
+ref_codes: []
+
+routing_entries:
+  - "Go module / CLI task → see AGENTS.md critical rules"
+
+rules: []
+
+makefile_targets:
+  - {name: lint-go, cmd: "cd src/backend && go vet ./..."}
+  - {name: test-go, cmd: "cd src/backend && go test ./..."}
+
+verify:
+  - {glob: "src/backend/**/*.go", suites: "lint-go + test-go", cmd: "cd src/backend && go vet ./... && go test ./..."}
+
+dimensions: []
+
+skill_enforcement: []