mcp/internal/index/builtins/README.md

# Wiring Conventions

> Forging a service is mostly wiring. Do it the same way every time.

This is not an Einherjar *module* — it is the canonical *application* shape that uses
Einherjar modules. Apps live in their own repository with an `internal/wire/` package that
mirrors this template. The conventions here are distilled from production services built on
Einherjar v1 (`iron-dough-api`, `pei-api`) and describe the **one opinionated minimum** a
scaffolded app should have. You *can* hand-roll something else — but then it is yours to
maintain, and it will not match what the rest of the ecosystem reads at a glance.

## The opinionated minimum

Every scaffolded Einherjar application has, at minimum:

1. **A clean `main.go`** — nothing but `.env` autoload and a call to `wire.Run()`.
2. **An `internal/wire/` package** — one file per feature plus `wire.go`, which assembles everything.
3. **An `internal/config/config.go`** — one global `Config` that *composes* the framework's
   component configs, loaded from the environment with `caarlos0/env`.
4. **A `.env.example`** kept in lock-step with that config (see *Config & .env.example*).

Anything a developer freely chooses — how migrations run, how the first admin is seeded, an
init-by-endpoint/webhook/email flow — is **not** part of this convention and is left to the app.

## Project layout

```
cmd/<app>/main.go              one-line entrypoint: godotenv autoload + wire.Run()
internal/wire/wire.go          Run() — loads config, builds infra, registers feature hooks
internal/wire/<feature>.go     one file per feature, hosts a with<Feature> hook
internal/wire/middleware.go    authz, skipPublicPaths, skipMethodPath helpers
internal/config/config.go      global Config composing framework component configs
.env.example                   every env var the config reads, documented, in sync
internal/<feature>/dto/        request/response DTOs
internal/<feature>/handler/    HTTP handlers
internal/<feature>/repository/ data access
internal/<feature>/service/    domain logic
```

## main.go

`cmd/<app>/main.go` contains **nothing** but the `.env` autoload and the call to `wire.Run()`.
The blank import `_ "github.com/joho/godotenv/autoload"` is the standard, documented way to load
a local `.env` — it never overrides variables already set in the real environment, and a missing
file is not an error, so deployments (vars injected by the platform, no `.env`) are unaffected.

```go
package main

import (
	"fmt"
	"os"

	_ "github.com/joho/godotenv/autoload"

	"myapp/internal/wire"
)

func main() {
	if err := wire.Run(); err != nil {
		fmt.Fprintln(os.Stderr, "fatal:", err)
		os.Exit(1)
	}
}
```

No config parsing, no component construction, no logging setup — all of that lives in
`internal/wire/`. A `main.go` that builds anything itself is the single most common scaffolding
mistake.

## Config

`internal/config/config.go` is **one** `Config` struct that *composes* the framework's component
configs as nested fields, alongside the app's own settings. `caarlos0/env` recurses into the
nested fields, so each Einherjar component's `EINHERJAR_*` env tags load automatically next to
the app-owned fields. App-owned fields use the `APP_*` prefix so they never collide with the
framework's `EINHERJAR_*` namespace. There is exactly one `Load()`.

```go
package config

import (
	"time"

	"github.com/caarlos0/env/v11"

	"code.nochebuena.dev/einherjar/db-postgres"
	"code.nochebuena.dev/einherjar/web/server"
)

// JWTConfig is app-owned: the secret is handed to the signer in code, not consumed
// by a framework component, so it carries no EINHERJAR_ prefix.
type JWTConfig struct {
	Secret     string        `env:"APP_JWT_SECRET,required,notEmpty"`
	Issuer     string        `env:"APP_JWT_ISSUER"      envDefault:"myapp"`
	AccessTTL  time.Duration `env:"APP_JWT_ACCESS_TTL"  envDefault:"1h"`
	RefreshTTL time.Duration `env:"APP_JWT_REFRESH_TTL" envDefault:"168h"`
}

// Config is the fully-resolved startup configuration. Einherjar component configs
// are nested fields; caarlos0/env recurses into them, populating their
// EINHERJAR_SERVER_* / EINHERJAR_PG_* tags from the environment.
type Config struct {
	AppEnv      string   `env:"APP_ENV"          envDefault:"local"`
	CORSOrigins []string `env:"APP_CORS_ORIGINS" envSeparator:","`

	JWT JWTConfig

	// Framework component configs — composed verbatim. Their own EINHERJAR_* tags
	// load through this one env.Parse call.
	Server server.Config   // EINHERJAR_SERVER_*
	PG     postgres.Config // EINHERJAR_PG_*
}

func Load() (Config, error) {
	var cfg Config
	if err := env.Parse(&cfg); err != nil {
		return Config{}, err
	}
	return cfg, nil
}
```

Never read framework env vars (`EINHERJAR_*`) with `os.Getenv` — compose the component's `Config`
type and let `caarlos0/env` load it. A raw `os.Getenv("EINHERJAR_PG_HOST")` in application code is
the mistake this convention removes.

## Config & .env.example

Every environment variable the `config` package reads **must** also appear in `.env.example` at
the repo root, documented. The two are kept in **lock-step**: when a feature introduces a new env
var, the same change adds its `env:"..."` tag to `config` **and** a documented line to
`.env.example`. This is not optional bookkeeping — it is what stops a long feature from shipping
and then failing at boot because nobody knew which variables to set.

```bash
# .env.example — copy to .env for local dev. Every var the app reads lives here.

# ── App ───────────────────────────────────────────────────────────────────
APP_ENV=local
APP_CORS_ORIGINS=*
APP_JWT_SECRET=change-me
APP_JWT_ISSUER=myapp

# ── Einherjar: HTTP server (EINHERJAR_SERVER_*) ───────────────────────────
EINHERJAR_SERVER_ADDR=:8080

# ── Einherjar: PostgreSQL (EINHERJAR_PG_*) ────────────────────────────────
EINHERJAR_PG_HOST=localhost
EINHERJAR_PG_PORT=5432
EINHERJAR_PG_USER=postgres
EINHERJAR_PG_PASSWORD=postgres
EINHERJAR_PG_DATABASE=myapp
```

To discover the full set, walk every `env:"..."` tag reachable from `config.Config` (including the
nested framework configs) — every one of them belongs in `.env.example`.

## wire.go — Run()

The application entry point. The order below is load-bearing: configuration first, observability
second, infrastructure third, cross-cutting helpers fourth, then the launcher with every component
appended, then feature hooks, then `lc.Run()`.

```go
package wire

import (
	"strings"

	"github.com/google/uuid"

	authjwt "code.nochebuena.dev/einherjar/auth-jwt"
	"code.nochebuena.dev/einherjar/auth/authmw"
	"code.nochebuena.dev/einherjar/auth/rbac"
	"code.nochebuena.dev/einherjar/core/launcher"
	"code.nochebuena.dev/einherjar/core/logz"
	"code.nochebuena.dev/einherjar/core/valid"
	"code.nochebuena.dev/einherjar/db-postgres"
	"code.nochebuena.dev/einherjar/web/mw"
	"code.nochebuena.dev/einherjar/web/server"

	"myapp/internal/config"
)

func Run() error {
	cfg, err := config.Load()
	if err != nil {
		return err
	}

	logger := logz.New(logz.Config{
		JSON:       !strings.EqualFold(cfg.AppEnv, "local"),
		StaticArgs: []any{"service", "myapp", "env", cfg.AppEnv},
	})

	signer := authjwt.NewHMACSigner([]byte(cfg.JWT.Secret))

	publicPaths := []string{
		"/health",
		"/api/v1/auth/login",
		"/api/v1/auth/refresh",
	}

	db  := postgres.New(logger, cfg.PG)
	srv := server.New(logger, cfg.Server,
		server.WithMiddleware(
			mw.RequestID(uuid.NewString),
			mw.Recover(logger),
			mw.CORS(cfg.CORSOrigins),
			mw.RequestLogger(logger),
			authjwt.AuthMiddleware(logger, signer, publicPaths),
			authmw.EnrichmentMiddleware(logger, &claimsEnricher{}),
		),
	)

	v        := valid.New(valid.WithMessageProvider(valid.SpanishMessages))
	provider := rbac.NewClaimsPermissionProvider("masks", claimsFromCtx)

	lc := launcher.New(logger)
	lc.Append(db, srv)

	withHealth(lc, srv, logger, db)
	withUsers(lc, srv, db, logger, provider, v)
	// … one withFeature(...) call per feature in your domain.

	return lc.Run()
}
```

## Feature hook

One file per feature in `internal/wire/`. The function signature is fixed:
`launcher.Launcher` first, `server.Server` second when registering routes, deps last. The body is
*one* call to `lc.BeforeStart`. Everything else — repository, service, handler construction, route
registration — lives inside the closure.

```go
package wire

import (
	"code.nochebuena.dev/einherjar/contracts/security"
	"code.nochebuena.dev/einherjar/core/launcher"
	"code.nochebuena.dev/einherjar/core/logz"
	"code.nochebuena.dev/einherjar/core/valid"
	"code.nochebuena.dev/einherjar/db-postgres"
	"code.nochebuena.dev/einherjar/web/server"

	"myapp/internal/domains"
	userhandler "myapp/internal/user/handler"
	userrepo    "myapp/internal/user/repository"
	usersvc     "myapp/internal/user/service"
)

func withUsers(
	lc       launcher.Launcher,
	srv      server.Server,
	db       postgres.Component,
	logger   logz.Logger,
	provider security.PermissionProvider,
	v        valid.Validator,
) {
	lc.BeforeStart(func() error {
		repo := userrepo.New(db)
		uow  := postgres.NewUnitOfWork(logger, db)
		svc  := usersvc.New(repo, uow)
		h    := userhandler.New(svc, v)

		// Literal-segment routes register BEFORE parametrised siblings.
		srv.Put("/api/v1/users/me/password", h.ChangeOwnPassword)

		srv.With(authz(provider, domains.ResourceUsers, domains.GrantReadUser)).
			Get("/api/v1/users", h.ListUsers)
		srv.With(authz(provider, domains.ResourceUsers, domains.GrantCreateUser)).
			Post("/api/v1/users", h.CreateUser)
		srv.With(authz(provider, domains.ResourceUsers, domains.GrantUpdateUser)).
			Put("/api/v1/users/{user_id}", h.UpdateUser)

		return nil
	})
}
```

## Route ordering

chi matches paths in registration order. Always register literal-segment routes before
parametrised-segment routes that share the same prefix.

✅ Correct:

```go
srv.Put("/api/v1/users/me/password", h.ChangeOwnPassword)
srv.Put("/api/v1/users/{user_id}",   h.UpdateUser)
```

❌ Wrong — chi binds `me` to `{user_id}` and the literal route is unreachable:

```go
srv.Put("/api/v1/users/{user_id}",   h.UpdateUser)
srv.Put("/api/v1/users/me/password", h.ChangeOwnPassword)
```

## Authorization

Every protected route registers with `.With(authz(provider, resource, grant))`:

```go
srv.With(authz(provider, domains.ResourceUsers, domains.GrantReadUser)).
    Get("/api/v1/users", h.ListUsers)
```

Resource constants and grant bits live in `internal/domains/`. Routes that the caller owns
(`/me/...`) intentionally skip authz — they are reachable to any authenticated user.

## Middleware helpers

These belong in `internal/wire/middleware.go` and are used across every feature hook.

```go
// authz returns a per-route authorization middleware that checks one bit.
func authz(p security.PermissionProvider, resource string, bit int) func(http.Handler) http.Handler {
	return authmw.AuthzMiddleware(nil, p, resource, security.Permission(bit))
}

// skipPublicPaths wraps mw so it is bypassed for any path that matches publicPaths.
// Use this for middleware that must not run on unauthenticated endpoints
// (e.g. EnrichmentMiddleware).
func skipPublicPaths(publicPaths []string, mw func(http.Handler) http.Handler) func(http.Handler) http.Handler {
	return func(next http.Handler) http.Handler {
		inner := mw(next)
		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			for _, p := range publicPaths {
				if matched, _ := path.Match(p, r.URL.Path); matched {
					next.ServeHTTP(w, r)
					return
				}
			}
			inner.ServeHTTP(w, r)
		})
	}
}

// skipMethodPath bypasses mw only when BOTH method and path match. Use this to
// expose ONE method on an otherwise-authenticated path (e.g. GET /api/v1/config
// public while PUT is not). Adding such a path to publicPaths would silently
// strip identity from context on the protected methods, breaking authz().
func skipMethodPath(method, pathPattern string, mw func(http.Handler) http.Handler) func(http.Handler) http.Handler {
	return func(next http.Handler) http.Handler {
		inner := mw(next)
		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			if r.Method == method {
				if matched, _ := path.Match(pathPattern, r.URL.Path); matched {
					next.ServeHTTP(w, r)
					return
				}
			}
			inner.ServeHTTP(w, r)
		})
	}
}
```

## Adapters at the wire boundary

When a framework type does not match a service-layer port, write a small typed adapter in
`internal/wire/`. Always compile-time assert with `var _ TargetIface = (*adapter)(nil)`.

The framework intentionally exposes only `Signer.Sign(claims) (string, error)` — **the framework
gives you a signing primitive; the access/refresh strategy, claim layout, and response shape are
application concerns.** A "helper" that returned a fixed `{access, refresh, type, expiresIn}` struct
would silently decide for every app whether refresh tokens exist, what fields to expose, and what
casing to use. Those are wire-format choices the app owns.

```go
import (
	"time"

	"github.com/golang-jwt/jwt/v5"
	"github.com/google/uuid"

	authjwt "code.nochebuena.dev/einherjar/auth-jwt"
)

type tokenSignerAdapter struct {
	signer authjwt.Signer
	cfg    authjwt.TokenConfig
}

var _ authsvc.TokenSigner = (*tokenSignerAdapter)(nil)

func (a *tokenSignerAdapter) IssueTokenPair(subject string, custom map[string]any) (authdto.TokenPairResponse, error) {
	now := time.Now()

	access := jwt.MapClaims{
		"sub": subject,
		"iss": a.cfg.Issuer,
		"iat": now.Unix(),
		"exp": now.Add(a.cfg.AccessTTL).Unix(),
	}
	for k, v := range custom {
		access[k] = v
	}
	accessToken, err := a.signer.Sign(access)
	if err != nil {
		return authdto.TokenPairResponse{}, err
	}

	refreshToken, err := a.signer.Sign(jwt.MapClaims{
		"sub": subject,
		"jti": uuid.NewString(),
		"iat": now.Unix(),
		"exp": now.Add(a.cfg.RefreshTTL).Unix(),
	})
	if err != nil {
		return authdto.TokenPairResponse{}, err
	}

	return authdto.TokenPairResponse{
		AccessToken:  accessToken,
		RefreshToken: refreshToken,
		TokenType:    "Bearer",
		ExpiresIn:    int(a.cfg.AccessTTL.Seconds()),
	}, nil
}
```