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

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:
2026-08-07 12:21:00 -06:00
parent 13a186c60a
commit 262eade93d
8 changed files with 624 additions and 85 deletions
+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
}