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.
internal/rules/scaffold_rules.go
+104
View File
@@ -0,0 +1,104 @@
package rules
import (
"go/ast"
"strings"
)
// Scaffolding conventions: keep main.go clean, load .env, and compose framework
// component configs instead of reading EINHERJAR_* env vars by hand. These catch
// the "cochinero in main.go" an AI produces when starting a project from zero.
func init() {
registered = append(registered,
Rule{
ID: "main.dirty",
Severity: SeverityError,
Module: "wire",
Check: checkMainDirty,
},
Rule{
ID: "main.no-godotenv-autoload",
Severity: SeverityWarning,
Module: "wire",
Check: checkMainGodotenv,
},
Rule{
ID: "config.raw-getenv",
Severity: SeverityWarning,
Module: "wire",
Check: checkConfigRawGetenv,
},
)
}
func isMainPackage(c *Context) bool {
return c.File != nil && c.File.Name != nil && c.File.Name.Name == "main"
}
// hasGodotenv reports whether the file loads a local .env, by either the blank
// autoload import (the standard) or the plain godotenv package.
func hasGodotenv(c *Context) bool {
return c.Importing("godotenv/autoload") || c.Importing("joho/godotenv")
}
// checkMainDirty flags a main.go that constructs the framework launcher itself.
// The launcher and every component belong in internal/wire; main.go must contain
// nothing but the godotenv autoload and wire.Run().
func checkMainDirty(c *Context) []Finding {
if !isMainPackage(c) {
return nil
}
if !c.Importing("einherjar/core/launcher") && !c.Called("launcher.New") {
return nil
}
return []Finding{{
Message: "main.go constructs the launcher/components directly — composition belongs in internal/wire, not main",
Hint: `Keep main.go to _ "github.com/joho/godotenv/autoload" + wire.Run(). Move launcher.New/Append and every component into internal/wire/wire.go Run().`,
}}
}
// checkMainGodotenv flags a wire-convention main.go that never loads .env, so
// local APP_*/EINHERJAR_* variables would be missing at config.Load().
func checkMainGodotenv(c *Context) []Finding {
if !isMainPackage(c) {
return nil
}
if !c.Called("wire.Run") && !c.Importing("internal/wire") {
return nil
}
if hasGodotenv(c) {
return nil
}
return []Finding{{
Message: "main.go calls wire.Run() but never loads .env — local config will be missing at boot",
Hint: `Add the blank import _ "github.com/joho/godotenv/autoload" (the documented standard); it never overrides real environment variables and a missing file is not an error.`,
}}
}
// checkConfigRawGetenv flags reading a framework EINHERJAR_* env var directly via
// os.Getenv, which bypasses the component-config composition. (EINHERJAR_LOG_* is
// left to logz.direct-env-read, which carries a logz-specific hint.)
func checkConfigRawGetenv(c *Context) []Finding {
var hits []Finding
ast.Inspect(c.File, func(n ast.Node) bool {
call, ok := n.(*ast.CallExpr)
if !ok || exprName(call.Fun) != "os.Getenv" || len(call.Args) == 0 {
return true
}
lit, ok := call.Args[0].(*ast.BasicLit)
if !ok {
return true
}
key := strings.Trim(lit.Value, `"`)
if !strings.HasPrefix(key, "EINHERJAR_") || strings.HasPrefix(key, "EINHERJAR_LOG_") {
return true
}
hits = append(hits, Finding{
Message: "reading " + key + " directly via os.Getenv bypasses the framework config composition",
Hint: "Compose the component's Config type (e.g. postgres.Config) into your Config struct and let caarlos0/env load its EINHERJAR_* tags through config.Load().",
Line: c.Fset.Position(call.Pos()).Line,
})
return true
})
return hits
}
internal/rules/scaffold_rules_test.go
+81
View File
@@ -0,0 +1,81 @@
package rules
import "testing"
func hasRule(fs []Finding, id string) bool {
for _, f := range fs {
if f.RuleID == id {
return true
}
}
return false
}
func TestMainDirty_flagsLauncherInMain(t *testing.T) {
src := `package main
import (
"code.nochebuena.dev/einherjar/core/launcher"
"code.nochebuena.dev/einherjar/core/logz"
)
func main() {
logger := logz.New(logz.Config{})
lc := launcher.New(logger)
_ = lc.Run()
}`
if !hasRule(Run(src), "main.dirty") {
t.Fatal("expected main.dirty when the launcher is constructed in main")
}
}
func TestCleanMain_isNotFlagged(t *testing.T) {
src := `package main
import (
"os"
_ "github.com/joho/godotenv/autoload"
"myapp/internal/wire"
)
func main() {
if err := wire.Run(); err != nil {
os.Exit(1)
}
}`
fs := Run(src)
if hasRule(fs, "main.dirty") {
t.Fatal("clean main must not trip main.dirty")
}
if hasRule(fs, "main.no-godotenv-autoload") {
t.Fatal("clean main has autoload; must not trip main.no-godotenv-autoload")
}
}
func TestMainNoGodotenv_flagsMissingAutoload(t *testing.T) {
src := `package main
import "myapp/internal/wire"
func main() {
_ = wire.Run()
}`
if !hasRule(Run(src), "main.no-godotenv-autoload") {
t.Fatal("expected main.no-godotenv-autoload when .env is never loaded")
}
}
func TestConfigRawGetenv_flagsEinherjarVar(t *testing.T) {
src := `package config
import "os"
func Load() string {
return os.Getenv("EINHERJAR_PG_HOST")
}`
if !hasRule(Run(src), "config.raw-getenv") {
t.Fatal("expected config.raw-getenv when an EINHERJAR_* var is read via os.Getenv")
}
}
internal/tools/scaffold.go
+226
View File
@@ -0,0 +1,226 @@
package tools
import (
"context"
"strings"
"code.nochebuena.dev/einherjar/mcp/internal/index"
"github.com/modelcontextprotocol/go-sdk/mcp"
)
type getScaffoldInput struct {
Module string `json:"module,omitempty" jsonschema:"the go.mod module path of the new app, e.g. code.nochebuena.dev/org/myapp; used to fill import paths. Defaults to 'myapp'."`
Service string `json:"service,omitempty" jsonschema:"short service name for the cmd/ dir and the logz service tag, e.g. myapp. Defaults to the last path segment of module."`
}
type scaffoldFile struct {
Path string `json:"path"`
Content string `json:"content"`
}
type getScaffoldOutput struct {
Layout string `json:"layout"`
Files []scaffoldFile `json:"files"`
Notes []string `json:"notes"`
}
func registerGetScaffold(s *mcp.Server, idx *index.Index) {
mcp.AddTool(s, &mcp.Tool{
Name: "get_scaffold",
Description: "Return the canonical MINIMUM Einherjar application scaffold as ready-to-write files: " +
"a clean main.go (godotenv autoload + wire.Run), internal/wire/wire.go (the launcher assembly), " +
"internal/config/config.go (one Config composing the framework's component configs via caarlos0/env), " +
"a health feature hook, and .env.example. This is the one opinionated starting point — call it when " +
"creating a new Einherjar service so main.go and the launcher stay clean instead of being hand-rolled. " +
"Migrations and seeding are deliberately excluded — those are the developer's choice, not a framework convention.",
}, func(ctx context.Context, req *mcp.CallToolRequest, args getScaffoldInput) (*mcp.CallToolResult, getScaffoldOutput, error) {
module := strings.TrimSpace(args.Module)
if module == "" {
module = "myapp"
}
service := strings.TrimSpace(args.Service)
if service == "" {
service = module
if i := strings.LastIndex(module, "/"); i >= 0 {
service = module[i+1:]
}
}
repl := strings.NewReplacer("%%MODULE%%", module, "%%APP%%", service)
out := getScaffoldOutput{
Layout: scaffoldLayout,
Files: []scaffoldFile{
{Path: "cmd/" + service + "/main.go", Content: repl.Replace(tplMain)},
{Path: "internal/wire/wire.go", Content: repl.Replace(tplWire)},
{Path: "internal/wire/health.go", Content: repl.Replace(tplHealth)},
{Path: "internal/config/config.go", Content: repl.Replace(tplConfig)},
{Path: ".env.example", Content: repl.Replace(tplEnvExample)},
},
Notes: []string{
"main.go contains ONLY the godotenv autoload blank import and wire.Run() — never construct components there.",
"Every env var the config reads must also appear in .env.example, kept in lock-step. When a feature adds a var, update both.",
"App-owned config fields use the APP_* prefix; framework component configs load their own EINHERJAR_* tags through the same env.Parse.",
"Add one internal/wire/<feature>.go per feature (a with<Feature> hook) plus its internal/<feature>/{dto,handler,repository,service} layers; call validate_snippet / get_example(\"wire\") for the hook shape.",
"Migrations and seeding are the developer's choice — not part of this scaffold.",
},
}
return jsonText(out), out, nil
})
}
const scaffoldLayout = `cmd/%%APP%%/main.go godotenv autoload + wire.Run()
internal/wire/wire.go Run() — config, infra, feature hooks
internal/wire/<feature>.go one file per feature (with<Feature> hook)
internal/wire/middleware.go authz / skip helpers (add when you add authz'd routes)
internal/config/config.go Config composing framework component configs
.env.example every env var the config reads, in sync
internal/<feature>/{dto,handler,repository,service}/`
const tplMain = `package main
import (
"fmt"
"os"
_ "github.com/joho/godotenv/autoload"
"%%MODULE%%/internal/wire"
)
func main() {
if err := wire.Run(); err != nil {
fmt.Fprintln(os.Stderr, "fatal:", err)
os.Exit(1)
}
}
`
const tplWire = `package wire
import (
"strings"
"github.com/google/uuid"
"code.nochebuena.dev/einherjar/core/launcher"
"code.nochebuena.dev/einherjar/core/logz"
"code.nochebuena.dev/einherjar/db-postgres"
"code.nochebuena.dev/einherjar/web/mw"
"code.nochebuena.dev/einherjar/web/server"
"%%MODULE%%/internal/config"
)
// Run loads configuration, builds infrastructure, registers feature hooks, and
// blocks until shutdown. Order is load-bearing: config, logger, infra, launcher
// with every component appended, then feature hooks, then lc.Run().
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", "%%APP%%", "env", cfg.AppEnv},
})
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),
),
)
lc := launcher.New(logger)
lc.Append(db, srv)
withHealth(lc, srv, logger, db)
// … one withFeature(lc, srv, …) call per feature in your domain.
return lc.Run()
}
`
const tplHealth = `package wire
import (
"net/http"
"code.nochebuena.dev/einherjar/core/launcher"
"code.nochebuena.dev/einherjar/core/logz"
"code.nochebuena.dev/einherjar/db-postgres"
"code.nochebuena.dev/einherjar/web/server"
)
// withHealth registers a liveness endpoint. Grow it into a readiness check
// (ping db and other dependencies) as the service gains infrastructure.
func withHealth(lc launcher.Launcher, srv server.Server, logger logz.Logger, db postgres.Component) {
lc.BeforeStart(func() error {
srv.Get("/health", func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(http.StatusOK)
_, _ = w.Write([]byte(` + "`" + `{"status":"ok"}` + "`" + `))
})
return nil
})
}
`
const tplConfig = `// Package config loads %%APP%%'s startup configuration from the environment.
//
// Einherjar component configs (server.Config, postgres.Config, …) are composed
// verbatim as nested fields so their EINHERJAR_* env tags load alongside the
// app-owned APP_* fields through a single caarlos0/env parse. Every env var
// declared here must also be documented in .env.example, kept in lock-step.
package config
import (
"github.com/caarlos0/env/v11"
"code.nochebuena.dev/einherjar/db-postgres"
"code.nochebuena.dev/einherjar/web/server"
)
// Config is the fully-resolved startup configuration. caarlos0/env recurses into
// the nested framework configs, populating their EINHERJAR_SERVER_* / EINHERJAR_PG_*
// tags from the environment next to the app-owned APP_* fields.
type Config struct {
AppEnv string ` + "`" + `env:"APP_ENV" envDefault:"local"` + "`" + `
CORSOrigins []string ` + "`" + `env:"APP_CORS_ORIGINS" envSeparator:","` + "`" + `
// Framework component configs — composed verbatim; their EINHERJAR_* tags
// load through this same 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
}
`
const tplEnvExample = `# .env.example — copy to .env for local dev (godotenv autoloads it).
# Every variable the config package reads lives here, documented. Keep in sync.
# ── App (APP_*) ────────────────────────────────────────────────────────────
APP_ENV=local
APP_CORS_ORIGINS=*
# ── 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=%%APP%%
`
internal/tools/tools.go
+1
View File
@@ -19,6 +19,7 @@ func Register(s *mcp.Server, idx *index.Index) {
registerListADRs(s, idx)
registerGetADR(s, idx)
registerGetExample(s, idx)
registerGetScaffold(s, idx)
registerValidateSnippet(s, idx)
registerGetCompliance(s, idx)
registerGetChangelog(s, idx)