einherjar/mcp
2
0
Fork 0
Code Issues Pull Requests Packages Releases Activity

feat(mcp): scaffold tool, config/env conventions, and scaffold-hygiene rules

Browse Source 
Major release to v1.0.0, aligned with the v1.0.0 framework. The MCP documented
the wiring conventions but not the config half of a project, and its example
main.go omitted the godotenv autoload — so an assistant starting a service from
zero still hand-rolled main.go and the launcher, and got config wrong. This adds
a first-class scaffold, completes the config/.env.example conventions, and adds
rules that catch the "mess in main" pattern.

internal/tools:
- New get_scaffold: returns the canonical minimum application scaffold as
  ready-to-write files (main.go with godotenv autoload + wire.Run(), wire.go,
  a composed config.go, a health hook, .env.example), with import paths filled
  from a `module` argument. Registered in tools.go.

internal/rules:
- Three new validate_snippet rules, appended in scaffold_rules.go: main.dirty
  (launcher/components built in main instead of internal/wire),
  main.no-godotenv-autoload (a wire-convention main that never loads .env), and
  config.raw-getenv (an EINHERJAR_* var read via os.Getenv instead of composing
  the component Config; EINHERJAR_LOG_* stays with logz.direct-env-read).
- scaffold_rules_test.go — internal/rules had no tests; asserts each new rule
  fires and that a clean main is not flagged.

internal/index (builtins):
- The synthetic wire module gains a Config section (compose the framework's
  component configs, load with caarlos0/env, APP_* app fields / EINHERJAR_*
  framework fields) and a Config & .env.example discipline (every env var the
  config reads is documented in .env.example, kept in lock-step).
- main.go now shows the `_ "github.com/joho/godotenv/autoload"` blank import,
  previously omitted. The assembly file is renamed launcher.go -> wire.go.
- Migrations and seeding removed from the documented scaffold — developer
  choices, not framework conventions. Re-synced against iron-dough-api / pei-api.

Version:
- Badge and serverVersion const were stale at v0.1.0; both now v1.0.0.

Docs:
- README (eleven tools, eleven validation rules) and CHANGELOG updated.

No new dependencies. The wire conventions are embedded at build time
(//go:embed builtins/README.md) and the new tool and rules are compiled in, so a
deployment must be rebuilt to serve them; a server still running the v0.2.0
binary keeps serving the old conventions until redeployed.
This commit is contained in:
Rene Nochebuena
2026-08-07 12:21:00 -06:00
parent 13a186c60a
commit 262eade93d
8 changed files with 624 additions and 85 deletions
Download Patch File Download Diff File Expand all files Collapse all files
internal/index/builtins/README.md
+167 -80
View File
@@ -2,37 +2,165 @@
> 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 a production service that has shipped on the predecessor
micro-libs (`code.nochebuena.dev/go/*`) and have been re-mapped to the
einherjar import paths.
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 that calls wire.Run()
internal/wire/launcher.go Run() — builds infra and registers feature hooks
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/wire/migrations.go withMigrations hook
internal/wire/seed.go withSuperAdminSeed and other startup seeds
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
```
`cmd/<app>/main.go` must contain nothing but the call to `wire.Run()` and an
`os.Exit(1)` on error. Everything else lives in `internal/wire/`.
## main.go
## Run
`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.
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 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
@@ -45,15 +173,12 @@ import (
authjwt "code.nochebuena.dev/einherjar/auth-jwt"
"code.nochebuena.dev/einherjar/auth/authmw"
"code.nochebuena.dev/einherjar/auth/rbac"
"code.nochebuena.dev/einherjar/cache-valkey"
"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/storage-minio"
"code.nochebuena.dev/einherjar/web/mw"
"code.nochebuena.dev/einherjar/web/server"
"code.nochebuena.dev/einherjar/worker"
"myapp/internal/config"
)
@@ -77,11 +202,8 @@ func Run() error {
"/api/v1/auth/refresh",
}
db := postgres.New(logger, cfg.PG)
cache := valkey.New(logger, cfg.VK)
pool := worker.New(logger, cfg.Worker)
mc := minio.New(logger, cfg.MinIO)
srv := server.New(logger, cfg.Server,
db := postgres.New(logger, cfg.PG)
srv := server.New(logger, cfg.Server,
server.WithMiddleware(
mw.RequestID(uuid.NewString),
mw.Recover(logger),
@@ -96,12 +218,9 @@ func Run() error {
provider := rbac.NewClaimsPermissionProvider("masks", claimsFromCtx)
lc := launcher.New(logger)
lc.Append(db, cache, pool, mc, srv)
lc.Append(db, srv)
withMigrations(lc, logger, cfg)
withSuperAdminSeed(lc, db, logger, cfg)
withHealth(lc, srv, logger, db, cache, mc)
withHealth(lc, srv, logger, db)
withUsers(lc, srv, db, logger, provider, v)
// … one withFeature(...) call per feature in your domain.
@@ -112,9 +231,8 @@ func Run() error {
## 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 construction, service construction, handler construction, route
`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
@@ -149,9 +267,6 @@ func withUsers(
h := userhandler.New(svc, v)
// Literal-segment routes register BEFORE parametrised siblings.
// chi matches the first registered route that fits; if /users/{id}
// came first, "me" would bind to {id} and /users/me/password would
// never be reached.
srv.Put("/api/v1/users/me/password", h.ChangeOwnPassword)
srv.With(authz(provider, domains.ResourceUsers, domains.GrantReadUser)).
@@ -160,8 +275,6 @@ func withUsers(
Post("/api/v1/users", h.CreateUser)
srv.With(authz(provider, domains.ResourceUsers, domains.GrantUpdateUser)).
Put("/api/v1/users/{user_id}", h.UpdateUser)
srv.With(authz(provider, domains.ResourceUsers, domains.GrantDeleteUser)).
Delete("/api/v1/users/{user_id}", h.DeleteUser)
return nil
})
@@ -170,8 +283,8 @@ func withUsers(
## Route ordering
chi matches paths in registration order. Always register literal-segment
routes before parametrised-segment routes that share the same prefix.
chi matches paths in registration order. Always register literal-segment routes before
parametrised-segment routes that share the same prefix.
✅ Correct:
@@ -196,14 +309,12 @@ 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.
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.
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.
@@ -229,11 +340,10 @@ func skipPublicPaths(publicPaths []string, mw func(http.Handler) http.Handler) f
}
}
// 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().
// 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)
@@ -252,16 +362,14 @@ func skipMethodPath(method, pathPattern string, mw func(http.Handler) http.Handl
## 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)`.
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.
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 (
@@ -315,24 +423,3 @@ func (a *tokenSignerAdapter) IssueTokenPair(subject string, custom map[string]an
}, nil
}
```
## Migrations and seeds
Migrations and seeds register as `BeforeStart` hooks too. They run after all
components have initialised but before any of them have started, so the
database is reachable and the server is not yet accepting traffic.
```go
func withMigrations(lc launcher.Launcher, logger logz.Logger, cfg config.Config) {
lc.BeforeStart(func() error {
if err := migrations.RunMigrations(context.Background(), logger, cfg); err != nil {
logger.Error("migrations: failed to apply", err)
return err
}
return nil
})
}
```
Seeds must be **idempotent**: count first, only mutate when needed, log the
skip when nothing was done.