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

feat(mcp): derive env vars from the framework's real struct tags (#3)

Browse Source 
Minor to v1.1.0. Make the whole environment-variable surface derive from the
indexed component-config tags instead of a hand-maintained list that drifts.
Also folds in the scaffold-symbol fixes staged as v1.0.1 (never tagged); the
generated scaffold compiles clean against einherjar v1.0.0.

internal/envspec (new):
- Parse index struct tags into env vars {name, module, struct, field, required,
  default}. One source of truth: ParseTag, ForModule, FindStruct, All, KnownNames.

internal/tools:
- get_config_env: list the real env vars a component config reads (or all).
- check_env: flag unknown EINHERJAR_* names, required vars missing for the
  composed modules, and dead vars (set for an uncomposed module).
- get_scaffold: .env.example is now DERIVED from the index — required vars
  uncommented with a dev value, defaulted vars commented with their default.
  The scaffold now composes logz.Config (Log logz.Config) so EINHERJAR_LOG_*
  are live and documented, not hardcoded/ignored (log format is env-driven).
- validate_snippet: inject the real env-var name set into the rules package.

internal/index/builtins (wire conventions):
- Route the incremental "compose a component later" flow to get_config_env /
  check_env; distinguish framework EINHERJAR_* from app-owned APP_* (JWT).
- Compose logz.Config in the config + Run() examples, to match the scaffold.

internal/rules:
- config.unknown-env-var (twelfth rule): reject an env:"EINHERJAR_*" struct tag
  the framework doesn't declare. No-op until the server injects the name set, so
  it never fires on incomplete knowledge.

Fixed (was v1.0.1): scaffold health hook + wire builtin used logz.Logger (real:
contracts/logging.Logger) and postgres.Component (hooks take Provider); env tags
were EINHERJAR_SERVER_ADDR / EINHERJAR_PG_DATABASE (real: _HOST/_PORT / _PG_NAME).

Tests: envspec unit tests; env tools against the real data/index.json; the rule.
Verified by generating the scaffold, building it against local einherjar v1.0.0
(exit 0), and runtime-loading the composed logz.Config (EINHERJAR_LOG_LEVEL=DEBUG
-> slog.LevelDebug, EINHERJAR_LOG_JSON=true). Version bumped to v1.1.0 (badge +
serverVersion). No dependency changes.

Reviewed-on: #3
Co-authored-by: Rene Nochebuena Guerrero <rene@nochebuena.dev>
Co-committed-by: Rene Nochebuena Guerrero <rene@nochebuena.dev>
This commit was merged in pull request #3.
This commit is contained in:
Rene Nochebuena
2026-08-07 17:00:02 -06:00
committed by NOCHEBUENADEV
parent a0b803cb40
commit 850b63607c
14 changed files with 1003 additions and 50 deletions
Download Patch File Download Diff File Expand all files Collapse all files
internal/envspec/envspec.go
+157
View File
@@ -0,0 +1,157 @@
// Package envspec derives the real environment variables of Einherjar's
// component configs from the framework index — the single source of truth for
// which EINHERJAR_* vars exist, which are required, and what they default to.
//
// Every Einherjar component (db-postgres, web/server, core/logz, …) exposes a
// Config struct whose fields carry caarlos0/env tags. The indexer already
// captures those tags (index.Field.Tag); this package parses them so tools can
// build a correct global config, generate an accurate .env.example, and reject
// invented or misspelled var names — instead of anyone maintaining that list by
// hand and drifting from the framework.
package envspec
import (
"reflect"
"sort"
"strings"
"code.nochebuena.dev/einherjar/mcp/internal/index"
)
// Var is one environment variable declared by a component Config field.
type Var struct {
Name string `json:"name"` // e.g. EINHERJAR_PG_HOST
Module string `json:"module"` // e.g. db-postgres
SubPackage string `json:"subPackage,omitempty"` // e.g. server (empty at module root)
Struct string `json:"struct"` // the declaring struct, e.g. Config
Field string `json:"field"` // the Go field, e.g. Host
Type string `json:"type"` // the Go type, e.g. string
Required bool `json:"required"` // env:"...,required"
Default string `json:"default,omitempty"` // envDefault:"..." (empty when none)
HasDefault bool `json:"hasDefault"` // distinguishes "" default from no default
Doc string `json:"doc,omitempty"` // field doc comment, if any
}
// ParseTag extracts the env var declared by a raw struct tag (backticks already
// stripped, as stored in the index). ok is false when the tag has no env key or
// the key is "-" (explicitly excluded, e.g. an http.RoundTripper field).
func ParseTag(tag string) (v struct {
Name string
Required bool
Default string
HasDefault bool
}, ok bool) {
st := reflect.StructTag(tag)
raw, present := st.Lookup("env")
if !present {
return v, false
}
parts := strings.Split(raw, ",")
name := strings.TrimSpace(parts[0])
if name == "" || name == "-" {
return v, false
}
v.Name = name
for _, opt := range parts[1:] {
if strings.TrimSpace(opt) == "required" {
v.Required = true
}
}
if def, has := st.Lookup("envDefault"); has {
v.Default = def
v.HasDefault = true
}
ok = true
return v, ok
}
// varsForSymbol returns the env vars declared directly by a struct symbol's
// fields. Nested component-config fields (a field whose type is another Config,
// carrying no env tag of its own) are not expanded here — caller-facing helpers
// surface them because sibling structs are indexed independently.
func varsForSymbol(m index.Module, s index.Symbol) []Var {
var out []Var
for _, f := range s.Fields {
parsed, ok := ParseTag(f.Tag)
if !ok {
continue
}
out = append(out, Var{
Name: parsed.Name,
Module: m.Name,
SubPackage: s.SubPackage,
Struct: s.Name,
Field: f.Name,
Type: f.Type,
Required: parsed.Required,
Default: parsed.Default,
HasDefault: parsed.HasDefault,
Doc: strings.TrimSpace(f.Doc),
})
}
return out
}
// ForModule returns every env var declared by any struct in a module, across
// all its sub-packages (e.g. web yields web/server's EINHERJAR_SERVER_* plus
// web's EINHERJAR_SERVER_CORS_ORIGINS plus web/health's timeout). Returns nil
// when the module is unknown. Order is deterministic: sub-package, then struct,
// then declaration order.
func ForModule(idx *index.Index, module string) []Var {
m := idx.FindModule(module)
if m == nil {
return nil
}
var out []Var
for _, s := range m.Symbols {
if s.Kind != "type" || len(s.Fields) == 0 {
continue
}
out = append(out, varsForSymbol(*m, s)...)
}
return out
}
// FindStruct returns the env vars of one specific struct, identified by module,
// sub-package (empty for a module-root package), and struct name — the precise
// selector a scaffold uses to compose named component configs. Returns nil when
// no such struct is indexed.
func FindStruct(idx *index.Index, module, subPackage, name string) []Var {
m := idx.FindModule(module)
if m == nil {
return nil
}
for _, s := range m.Symbols {
if s.Kind == "type" && s.Name == name && s.SubPackage == subPackage {
return varsForSymbol(*m, s)
}
}
return nil
}
// All returns every env var declared anywhere in the framework, sorted by name.
func All(idx *index.Index) []Var {
var out []Var
for i := range idx.Modules {
m := idx.Modules[i]
for _, s := range m.Symbols {
if s.Kind != "type" || len(s.Fields) == 0 {
continue
}
out = append(out, varsForSymbol(m, s)...)
}
}
sort.Slice(out, func(i, j int) bool { return out[i].Name < out[j].Name })
return out
}
// KnownNames returns the set of every valid framework env-var name. It backs the
// config.unknown-env-var rule, which rejects any EINHERJAR_* tag that is not in
// this set (the exact bug class that shipped EINHERJAR_PG_DATABASE / _SERVER_ADDR).
func KnownNames(idx *index.Index) map[string]struct{} {
names := map[string]struct{}{}
for _, v := range All(idx) {
names[v.Name] = struct{}{}
}
return names
}
internal/envspec/envspec_test.go
+132
View File
@@ -0,0 +1,132 @@
package envspec
import (
"testing"
"code.nochebuena.dev/einherjar/mcp/internal/index"
)
func TestParseTag(t *testing.T) {
cases := []struct {
tag string
wantOK bool
wantName string
wantReq bool
wantDef string
wantHas bool
}{
{`env:"EINHERJAR_PG_HOST,required"`, true, "EINHERJAR_PG_HOST", true, "", false},
{`env:"EINHERJAR_PG_PORT" envDefault:"5432"`, true, "EINHERJAR_PG_PORT", false, "5432", true},
{`env:"EINHERJAR_LOG_JSON" envDefault:"false"`, true, "EINHERJAR_LOG_JSON", false, "false", true},
{`env:"-"`, false, "", false, "", false},
{`json:"x"`, false, "", false, "", false},
{``, false, "", false, "", false},
}
for _, c := range cases {
got, ok := ParseTag(c.tag)
if ok != c.wantOK {
t.Errorf("ParseTag(%q) ok=%v want %v", c.tag, ok, c.wantOK)
continue
}
if !ok {
continue
}
if got.Name != c.wantName || got.Required != c.wantReq || got.Default != c.wantDef || got.HasDefault != c.wantHas {
t.Errorf("ParseTag(%q) = %+v, want name=%q req=%v def=%q has=%v",
c.tag, got, c.wantName, c.wantReq, c.wantDef, c.wantHas)
}
}
}
// synthIndex mirrors the shape of the real index: a web module whose server
// sub-package and root both declare env vars, plus a db-postgres module.
func synthIndex() *index.Index {
return &index.Index{
Modules: []index.Module{
{
Name: "web",
Symbols: []index.Symbol{
{Kind: "type", Name: "Config", SubPackage: "server", Fields: []index.Field{
{Name: "Host", Type: "string", Tag: `env:"EINHERJAR_SERVER_HOST" envDefault:"0.0.0.0"`},
{Name: "Port", Type: "int", Tag: `env:"EINHERJAR_SERVER_PORT" envDefault:"8080"`},
}},
{Kind: "type", Name: "Config", SubPackage: "", Fields: []index.Field{
{Name: "Server", Type: "server.Config"}, // nested, no env tag
{Name: "AllowedOrigins", Type: "[]string", Tag: `env:"EINHERJAR_SERVER_CORS_ORIGINS" envSeparator:","`},
}},
},
},
{
Name: "db-postgres",
Symbols: []index.Symbol{
{Kind: "type", Name: "Config", SubPackage: "", Fields: []index.Field{
{Name: "Host", Type: "string", Tag: `env:"EINHERJAR_PG_HOST,required"`},
{Name: "Name", Type: "string", Tag: `env:"EINHERJAR_PG_NAME,required"`},
{Name: "Port", Type: "int", Tag: `env:"EINHERJAR_PG_PORT" envDefault:"5432"`},
}},
},
},
},
}
}
func TestForModule(t *testing.T) {
idx := synthIndex()
got := ForModule(idx, "web")
if len(got) != 3 { // 2 server + 1 CORS; the nested Server field is not a leaf
t.Fatalf("ForModule(web) = %d vars, want 3: %+v", len(got), got)
}
names := map[string]bool{}
for _, v := range got {
names[v.Name] = true
}
for _, want := range []string{"EINHERJAR_SERVER_HOST", "EINHERJAR_SERVER_PORT", "EINHERJAR_SERVER_CORS_ORIGINS"} {
if !names[want] {
t.Errorf("ForModule(web) missing %s", want)
}
}
if ForModule(idx, "nope") != nil {
t.Error("ForModule(unknown) should be nil")
}
}
func TestFindStruct(t *testing.T) {
idx := synthIndex()
server := FindStruct(idx, "web", "server", "Config")
if len(server) != 2 {
t.Fatalf("FindStruct(web/server/Config) = %d, want 2", len(server))
}
// The root web.Config must NOT be returned for the server selector.
for _, v := range server {
if v.Name == "EINHERJAR_SERVER_CORS_ORIGINS" {
t.Error("server selector leaked the root web.Config CORS var")
}
}
pg := FindStruct(idx, "db-postgres", "", "Config")
if len(pg) != 3 {
t.Fatalf("FindStruct(db-postgres//Config) = %d, want 3", len(pg))
}
var host envspecVarFound
for _, v := range pg {
if v.Name == "EINHERJAR_PG_HOST" {
host = envspecVarFound{found: true, required: v.Required, hasDefault: v.HasDefault}
}
}
if !host.found || !host.required || host.hasDefault {
t.Errorf("EINHERJAR_PG_HOST: %+v, want required with no default", host)
}
}
type envspecVarFound struct {
found, required, hasDefault bool
}
func TestKnownNames(t *testing.T) {
names := KnownNames(synthIndex())
if _, ok := names["EINHERJAR_PG_NAME"]; !ok {
t.Error("KnownNames missing EINHERJAR_PG_NAME")
}
if _, ok := names["EINHERJAR_PG_DATABASE"]; ok {
t.Error("KnownNames must not contain the bogus EINHERJAR_PG_DATABASE")
}
}