From a0b803cb404a9652bd281b9aa751daf59b7a8e2f Mon Sep 17 00:00:00 2001 From: Rene Nochebuena Guerrero Date: Fri, 7 Aug 2026 12:22:14 -0600 Subject: [PATCH] feat(mcp): scaffold tool, config/env conventions, and scaffold-hygiene rules (#2) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. Reviewed-on: https://code.nochebuena.dev/einherjar/mcp/pulls/2 Co-authored-by: Rene Nochebuena Guerrero Co-committed-by: Rene Nochebuena Guerrero --- CHANGELOG.md | 38 ++++ README.md | 10 +- cmd/server/main.go | 2 +- internal/index/builtins/README.md | 247 +++++++++++++++++--------- internal/rules/scaffold_rules.go | 104 +++++++++++ internal/rules/scaffold_rules_test.go | 81 +++++++++ internal/tools/scaffold.go | 226 +++++++++++++++++++++++ internal/tools/tools.go | 1 + 8 files changed, 624 insertions(+), 85 deletions(-) create mode 100644 internal/rules/scaffold_rules.go create mode 100644 internal/rules/scaffold_rules_test.go create mode 100644 internal/tools/scaffold.go diff --git a/CHANGELOG.md b/CHANGELOG.md index 1c12878..8306ef8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,44 @@ This module adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html --- +## [1.0.0] — 2026-08-07 + +The MCP reaches **v1.0.0**, aligned with the v1.0.0 framework. The headline is the +canonical application **scaffold**: the one opinionated starting point so an AI no longer +hand-rolls `main.go` and the launcher when creating a service from zero. + +### Added + +- **`get_scaffold` tool.** Returns the canonical minimum application scaffold as + ready-to-write files, with import paths filled from a `module` argument: a clean `main.go` + (godotenv autoload + `wire.Run()`), `internal/wire/wire.go` (the launcher assembly), a + composed `internal/config/config.go`, a health feature hook, and `.env.example`. +- **Three `validate_snippet` rules** (now eleven total), with a rules test suite: + `main.dirty` (the 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` (reading a framework `EINHERJAR_*` var via `os.Getenv` instead of + composing the component's `Config` type). +- **Config conventions in the `wire` builtin.** A `Config` section (compose the framework's + component configs, load with `caarlos0/env`, `APP_*` for app-owned fields, `EINHERJAR_*` + for framework ones) and a **Config & .env.example** section: every env var the config + reads must also be documented in `.env.example`, kept in lock-step. + +### Changed + +- **`wire` builtin re-synced to the current gold standards** (`iron-dough-api`, `pei-api`): + `main.go` now shows the `_ "github.com/joho/godotenv/autoload"` blank import (previously + omitted, so the AI produced a `main` that never loaded `.env`); the assembly file is + `wire.go` (was `launcher.go`). +- **Version alignment.** The README badge and `serverVersion` were stale at `v0.1.0`; both + now read `v1.0.0`. + +### Removed + +- **Migrations and seeding from the `wire` builtin.** How migrations run and how the first + admin is seeded (via code, a DB team, an endpoint, a webhook, …) is the developer's + choice — it belongs to no Einherjar module and is not a hard convention, so it is out of + the scaffold and the documented conventions. + ## [0.2.0] — 2026-06-10 Minor release. The indexer now captures the *members* of composite types, closing a gap where `get_symbol` and `search_symbols` could name a struct or interface but not describe its shape — most painfully, struct tags (env-var keys, json names) were invisible. diff --git a/README.md b/README.md index 8733fd2..585096e 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # einherjar/mcp -[![version](https://img.shields.io/badge/version-v0.1.0-5C4EE5?style=flat-square)](https://code.nochebuena.dev/einherjar/mcp) +[![version](https://img.shields.io/badge/version-v1.0.0-5C4EE5?style=flat-square)](https://code.nochebuena.dev/einherjar/mcp) [![license](https://img.shields.io/badge/license-AGPL--3.0-22863A?style=flat-square)](LICENSE) [![go](https://img.shields.io/badge/Go-1.26+-00ADD8?style=flat-square&logo=go&logoColor=white)](https://go.dev) @@ -38,7 +38,7 @@ under pressure. ## Tools -The server exposes **ten** tools to MCP-aware clients (Claude desktop, Claude Code, +The server exposes **eleven** tools to MCP-aware clients (Claude desktop, Claude Code, Cursor, Zed, and anything else that speaks MCP): | Tool | Purpose | @@ -50,14 +50,16 @@ Cursor, Zed, and anything else that speaks MCP): | `list_adrs` | List architectural decision records, optionally restricted to one module | | `get_adr` | Fetch a single ADR's markdown body | | `get_example` | Canonical usage snippet — pulled from module READMEs and from the synthetic `wire` conventions | +| `get_scaffold` | The canonical **minimum application scaffold** as ready-to-write files — a clean `main.go`, `internal/wire/wire.go`, a composed `internal/config`, a health hook, and `.env.example`. Use it when starting a new Einherjar service | | `get_compliance` | Interface assertions and structural test names from a module's `compliance_test.go` | | `get_changelog` | Full `CHANGELOG.md` markdown for one module | | `validate_snippet` | Pattern-match a Go snippet against framework conventions; returns findings with severity, hint, and line | -`validate_snippet` ships **eight** wiring-convention rules at v0.1.0: +`validate_snippet` ships **eleven** wiring-convention rules at v1.0.0: `launcher.missing-run`, `launcher.no-components`, `launcher.run-error-discarded`, `logz.direct-env-read`, `web.server-not-appended`, `wire.hook-bad-signature`, -`wire.hook-outside-beforestart`, and `wire.route-specific-after-param`. +`wire.hook-outside-beforestart`, `wire.route-specific-after-param`, +`main.dirty`, `main.no-godotenv-autoload`, and `config.raw-getenv`. --- diff --git a/cmd/server/main.go b/cmd/server/main.go index 99e45f6..7cd51a2 100644 --- a/cmd/server/main.go +++ b/cmd/server/main.go @@ -23,7 +23,7 @@ import ( const ( serverName = "einherjar-mcp" - serverVersion = "v0.1.0" + serverVersion = "v1.0.0" ) func main() { diff --git a/internal/index/builtins/README.md b/internal/index/builtins/README.md index 9bb0d0b..a8967db 100644 --- a/internal/index/builtins/README.md +++ b/internal/index/builtins/README.md @@ -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//main.go one-line entrypoint that calls wire.Run() -internal/wire/launcher.go Run() — builds infra and registers feature hooks +cmd//main.go one-line entrypoint: godotenv autoload + wire.Run() +internal/wire/wire.go Run() — loads config, builds infra, registers feature hooks internal/wire/.go one file per feature, hosts a with 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//dto/ request/response DTOs internal//handler/ HTTP handlers internal//repository/ data access internal//service/ domain logic ``` -`cmd//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//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. diff --git a/internal/rules/scaffold_rules.go b/internal/rules/scaffold_rules.go new file mode 100644 index 0000000..23d1660 --- /dev/null +++ b/internal/rules/scaffold_rules.go @@ -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 +} diff --git a/internal/rules/scaffold_rules_test.go b/internal/rules/scaffold_rules_test.go new file mode 100644 index 0000000..3d12609 --- /dev/null +++ b/internal/rules/scaffold_rules_test.go @@ -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") + } +} diff --git a/internal/tools/scaffold.go b/internal/tools/scaffold.go new file mode 100644 index 0000000..9f3c321 --- /dev/null +++ b/internal/tools/scaffold.go @@ -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/.go per feature (a with hook) plus its internal//{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/.go one file per feature (with 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//{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%% +` diff --git a/internal/tools/tools.go b/internal/tools/tools.go index 0d5bb52..b8dbc3d 100644 --- a/internal/tools/tools.go +++ b/internal/tools/tools.go @@ -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)