feat(mcp): initial implementation — MCP server, framework indexer, 10 tools, 8 validation rules (v0.1.0)
Introduces code.nochebuena.dev/einherjar/mcp — the Einherjar Model Context Protocol
server. A remote, streamable-HTTP service that teaches AI assistants about every
other module of the framework: which package exposes which type, what each module
guarantees through its compliance tests, the canonical wiring shape for a service,
and whether a Go snippet follows the conventions. Indexes the framework on disk at
build time and ships a self-contained binary via go:embed; imports nothing from
other einherjar/* modules at compile time.
server (cmd/server):
- Streamable-HTTP MCP server built on github.com/modelcontextprotocol/go-sdk v1.0.0
- mcp.NewServer + mcp.NewStreamableHTTPHandler, served via net/http on EINHERJAR_MCP_ADDR
(default :8080) and EINHERJAR_MCP_PATH (default /mcp)
- /healthz liveness endpoint; structured JSON logging via log/slog
- Loads the embedded data/index.json once at startup; in-memory for the process lifetime
indexer (cmd/indexer):
- Walks an Einherjar repository checkout (default ../), parses every sibling
module's go.mod, README.md, CHANGELOG.md, docs/adr/ADR-*.md, doc.go package
comments, every exported type/interface/func/method/const/var (via go/doc on
go/parser ASTs), and compliance_test.go
- Captures module dependency edges by regex over each go.mod's require lines
(einherjar/* paths only; self-reference filtered)
- Appends a synthetic "wire" module documenting canonical application wiring
conventions, authored at internal/index/builtins/README.md and embedded via
go:embed; participates in list_modules / get_module / get_example like a real module
internal/index:
- Schema einherjar.mcp/index/v1; types: Index, Module, SubPackage, Symbol, ADR,
Example, Compliance, InterfaceAssert, ComplianceTest
- Build(repoRoot) → *Index walks the repo; BuildBuiltins() returns the synthetic
wire module from the embedded markdown
- Load([]byte) → *Index validates the schema version on read
- FindModule, SearchSymbols helpers used by tools
internal/tools (10 tools):
- list_modules — enumerate every module with purpose + sub-packages
- get_module — package doc, dependencies, sub-packages, key symbols, ADRs,
compliance counts; optional embedded README
- search_symbols — full-text across name, doc, sub-package, module; filterable by
module and kind
- get_symbol — full signature, doc comment, source file:line for one symbol
- list_adrs — list ADRs across the framework or within one module
- get_adr — fetch one ADR's markdown body
- get_example — canonical usage snippets extracted from module READMEs and from
the synthetic wire conventions
- get_compliance — interface assertions (var _ Iface = impl) 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
internal/rules (8 rules, registered via init() against a single registered slice):
- launcher.missing-run — launcher constructed but Run() never called
- launcher.no-components — launcher.New() called without any .Append(...)
- launcher.run-error-discarded — lc.Run() invoked as an ExprStmt (return ignored)
- logz.direct-env-read — os.Getenv("EINHERJAR_LOG_*") bypassing logz config
- web.server-not-appended — web/server constructed but not added to the launcher
- wire.hook-bad-signature — with<Feature>(...) first param is not launcher.Launcher
- wire.hook-outside-beforestart — repo/service/handler construction or route
registration at the top level of a hook (outside lc.BeforeStart)
- wire.route-specific-after-param — /users/{id} registered before a sibling
/users/me of the same length and method (chi would shadow the literal route)
Synthetic wire module (internal/index/builtins/README.md):
- Project layout (cmd/<app>/main.go + internal/wire/*.go + per-feature domain dirs)
- Canonical Run() shape: config → logger → infra (db, cache, pool, mc, srv) → cross-
cutting (validator, permission provider) → launcher.New → lc.Append(infra...) →
withMigrations / withSuperAdminSeed / withHealth / withFeature hooks → return lc.Run()
- Canonical with<Feature> hook shape: signature (launcher.Launcher first, server.Server
second, deps last), single lc.BeforeStart closure containing all construction +
route registration
- chi route ordering, srv.With(authz(...)) authorization, middleware helpers
(authz / skipPublicPaths / skipMethodPath), tokenSignerAdapter pattern showing
that the framework exposes Signer.Sign as a primitive and the application owns
the access/refresh response shape
Packaging:
- Multi-stage Dockerfile that builds from the einherjar repository root
(docker build -f mcp/Dockerfile .) so cmd/indexer can walk every sibling module
at image-build time; runtime layer is gcr.io/distroless/static-debian12:nonroot
- 86-byte placeholder data/index.json committed once with `git add -f`; subsequent
indexer runs overwrite it locally but the file is .gitignored
- .gitea/CODEOWNERS and pull_request_template.md mirror the sibling layout
Design notes:
- mcp depends on nothing in einherjar/* — it reads the framework via the filesystem
at index time. This keeps mcp outside the framework dependency graph and lets it
index any version of einherjar without versioning itself in lock-step.
- All structured-output tool responses initialise empty slices ([]Type{}) rather
than relying on Go's nil-marshals-to-null default, so the SDK's JSON-schema
output validator never rejects a tools/call result.
This commit is contained in:
415
internal/index/builder.go
Normal file
415
internal/index/builder.go
Normal file
@@ -0,0 +1,415 @@
|
||||
package index
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"fmt"
|
||||
"go/ast"
|
||||
"go/doc"
|
||||
"go/parser"
|
||||
"go/printer"
|
||||
"go/token"
|
||||
"io/fs"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"regexp"
|
||||
"sort"
|
||||
"strings"
|
||||
"time"
|
||||
)
|
||||
|
||||
// Build walks the Einherjar repository rooted at repoRoot, indexes every
|
||||
// sibling module (any immediate subdirectory containing a go.mod), and
|
||||
// returns an Index ready to be written to disk.
|
||||
//
|
||||
// The mcp module itself is skipped to avoid self-reference.
|
||||
func Build(repoRoot string) (*Index, error) {
|
||||
idx := &Index{
|
||||
Schema: SchemaVersion,
|
||||
Framework: "einherjar",
|
||||
BuiltAt: time.Now().UTC(),
|
||||
}
|
||||
entries, err := os.ReadDir(repoRoot)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("read repo root: %w", err)
|
||||
}
|
||||
for _, e := range entries {
|
||||
if !e.IsDir() {
|
||||
continue
|
||||
}
|
||||
name := e.Name()
|
||||
if strings.HasPrefix(name, ".") || name == "mcp" || name == "vendor" {
|
||||
continue
|
||||
}
|
||||
modDir := filepath.Join(repoRoot, name)
|
||||
if _, err := os.Stat(filepath.Join(modDir, "go.mod")); err != nil {
|
||||
continue
|
||||
}
|
||||
mod, err := buildModule(modDir, name)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("module %s: %w", name, err)
|
||||
}
|
||||
idx.Modules = append(idx.Modules, *mod)
|
||||
}
|
||||
return idx, nil
|
||||
}
|
||||
|
||||
func buildModule(modDir, name string) (*Module, error) {
|
||||
m := &Module{
|
||||
Name: name,
|
||||
DependsOn: []string{},
|
||||
Compliance: Compliance{
|
||||
InterfaceAsserts: []InterfaceAssert{},
|
||||
Tests: []ComplianceTest{},
|
||||
},
|
||||
}
|
||||
|
||||
if data, err := os.ReadFile(filepath.Join(modDir, "go.mod")); err == nil {
|
||||
m.ImportPath = parseModulePath(data)
|
||||
m.GoVersion = parseGoVersion(data)
|
||||
m.DependsOn = parseDependsOn(data, name)
|
||||
}
|
||||
if data, err := os.ReadFile(filepath.Join(modDir, "README.md")); err == nil {
|
||||
m.Readme = string(data)
|
||||
m.Purpose = extractPurpose(string(data))
|
||||
m.Examples = extractExamples(name, string(data))
|
||||
}
|
||||
if data, err := os.ReadFile(filepath.Join(modDir, "CHANGELOG.md")); err == nil {
|
||||
m.Changelog = string(data)
|
||||
}
|
||||
m.Compliance = parseCompliance(name, modDir)
|
||||
|
||||
adrDir := filepath.Join(modDir, "docs", "adr")
|
||||
if adrs, err := os.ReadDir(adrDir); err == nil {
|
||||
for _, a := range adrs {
|
||||
if a.IsDir() || !strings.HasPrefix(a.Name(), "ADR-") || !strings.HasSuffix(a.Name(), ".md") {
|
||||
continue
|
||||
}
|
||||
body, err := os.ReadFile(filepath.Join(adrDir, a.Name()))
|
||||
if err != nil {
|
||||
continue
|
||||
}
|
||||
id, title := parseADRHeader(a.Name(), body)
|
||||
m.ADRs = append(m.ADRs, ADR{Module: name, ID: id, Title: title, Body: string(body)})
|
||||
}
|
||||
}
|
||||
|
||||
if err := indexPackages(modDir, m); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return m, nil
|
||||
}
|
||||
|
||||
func indexPackages(modDir string, m *Module) error {
|
||||
return filepath.WalkDir(modDir, func(path string, d fs.DirEntry, err error) error {
|
||||
if err != nil {
|
||||
return nil
|
||||
}
|
||||
if !d.IsDir() {
|
||||
return nil
|
||||
}
|
||||
base := d.Name()
|
||||
if base != filepath.Base(modDir) && (strings.HasPrefix(base, ".") || base == "vendor" || base == "testdata" || base == "docs") {
|
||||
return filepath.SkipDir
|
||||
}
|
||||
|
||||
fset := token.NewFileSet()
|
||||
pkgs, err := parser.ParseDir(fset, path, func(fi os.FileInfo) bool {
|
||||
return !strings.HasSuffix(fi.Name(), "_test.go")
|
||||
}, parser.ParseComments)
|
||||
if err != nil || len(pkgs) == 0 {
|
||||
return nil
|
||||
}
|
||||
rel, _ := filepath.Rel(modDir, path)
|
||||
if rel == "." {
|
||||
rel = ""
|
||||
}
|
||||
for pkgName, pkg := range pkgs {
|
||||
if pkgName == "main" {
|
||||
continue
|
||||
}
|
||||
subName := pkgName
|
||||
if rel == "" {
|
||||
subName = ""
|
||||
}
|
||||
docPkg := doc.New(pkg, "./", doc.AllDecls)
|
||||
if rel == "" && m.Doc == "" && docPkg.Doc != "" {
|
||||
m.Doc = strings.TrimSpace(docPkg.Doc)
|
||||
}
|
||||
if rel != "" || docPkg.Doc != "" {
|
||||
m.SubPackages = append(m.SubPackages, SubPackage{
|
||||
Name: subName,
|
||||
ImportPath: joinImport(m.ImportPath, rel),
|
||||
Doc: strings.TrimSpace(docPkg.Doc),
|
||||
})
|
||||
}
|
||||
collectSymbols(m, subName, modDir, fset, docPkg)
|
||||
}
|
||||
return nil
|
||||
})
|
||||
}
|
||||
|
||||
func collectSymbols(m *Module, sub, modDir string, fset *token.FileSet, p *doc.Package) {
|
||||
for _, t := range p.Types {
|
||||
kind := "type"
|
||||
if isInterface(t.Decl) {
|
||||
kind = "interface"
|
||||
}
|
||||
m.Symbols = append(m.Symbols, newSymbol(m.Name, sub, kind, t.Name, t.Doc, t.Decl, fset, modDir))
|
||||
for _, f := range t.Funcs {
|
||||
m.Symbols = append(m.Symbols, newSymbol(m.Name, sub, "func", f.Name, f.Doc, f.Decl, fset, modDir))
|
||||
}
|
||||
for _, f := range t.Methods {
|
||||
m.Symbols = append(m.Symbols, newSymbol(m.Name, sub, "method", t.Name+"."+f.Name, f.Doc, f.Decl, fset, modDir))
|
||||
}
|
||||
}
|
||||
for _, f := range p.Funcs {
|
||||
m.Symbols = append(m.Symbols, newSymbol(m.Name, sub, "func", f.Name, f.Doc, f.Decl, fset, modDir))
|
||||
}
|
||||
for _, v := range p.Consts {
|
||||
for _, name := range v.Names {
|
||||
m.Symbols = append(m.Symbols, newSymbol(m.Name, sub, "const", name, v.Doc, v.Decl, fset, modDir))
|
||||
}
|
||||
}
|
||||
for _, v := range p.Vars {
|
||||
for _, name := range v.Names {
|
||||
m.Symbols = append(m.Symbols, newSymbol(m.Name, sub, "var", name, v.Doc, v.Decl, fset, modDir))
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func newSymbol(mod, sub, kind, name, docStr string, decl ast.Node, fset *token.FileSet, modDir string) Symbol {
|
||||
pos := fset.Position(decl.Pos())
|
||||
rel, _ := filepath.Rel(modDir, pos.Filename)
|
||||
return Symbol{
|
||||
Module: mod,
|
||||
SubPackage: sub,
|
||||
Kind: kind,
|
||||
Name: name,
|
||||
Signature: formatNode(fset, decl),
|
||||
Doc: strings.TrimSpace(docStr),
|
||||
File: rel,
|
||||
Line: pos.Line,
|
||||
}
|
||||
}
|
||||
|
||||
func formatNode(fset *token.FileSet, node ast.Node) string {
|
||||
var buf bytes.Buffer
|
||||
cfg := printer.Config{Mode: printer.UseSpaces, Tabwidth: 4}
|
||||
if err := cfg.Fprint(&buf, fset, node); err != nil {
|
||||
return ""
|
||||
}
|
||||
s := buf.String()
|
||||
if i := strings.Index(s, "{"); i > 0 && (strings.HasPrefix(s, "func") || strings.HasPrefix(s, "type")) {
|
||||
return strings.TrimSpace(s[:i])
|
||||
}
|
||||
return strings.TrimSpace(s)
|
||||
}
|
||||
|
||||
func isInterface(decl *ast.GenDecl) bool {
|
||||
if decl == nil {
|
||||
return false
|
||||
}
|
||||
for _, spec := range decl.Specs {
|
||||
ts, ok := spec.(*ast.TypeSpec)
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
if _, ok := ts.Type.(*ast.InterfaceType); ok {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
var (
|
||||
modulePathRe = regexp.MustCompile(`(?m)^module\s+(\S+)`)
|
||||
goVersionRe = regexp.MustCompile(`(?m)^go\s+(\S+)`)
|
||||
adrNameRe = regexp.MustCompile(`^(ADR-\d+)-(.+)\.md$`)
|
||||
h1Re = regexp.MustCompile(`(?m)^#\s+(.+)$`)
|
||||
fenceRe = regexp.MustCompile("(?s)```([a-zA-Z0-9_+\\-]*)\\n(.*?)```")
|
||||
einherjarDepRe = regexp.MustCompile(`code\.nochebuena\.dev/einherjar/([a-zA-Z0-9_-]+)`)
|
||||
)
|
||||
|
||||
func parseModulePath(data []byte) string {
|
||||
if m := modulePathRe.FindSubmatch(data); m != nil {
|
||||
return string(m[1])
|
||||
}
|
||||
return ""
|
||||
}
|
||||
|
||||
func parseGoVersion(data []byte) string {
|
||||
if m := goVersionRe.FindSubmatch(data); m != nil {
|
||||
return string(m[1])
|
||||
}
|
||||
return ""
|
||||
}
|
||||
|
||||
// parseDependsOn extracts the set of einherjar modules referenced by go.mod's
|
||||
// require/replace lines. The module's own name is filtered out so a module
|
||||
// never lists itself as a dependency.
|
||||
func parseDependsOn(data []byte, self string) []string {
|
||||
seen := map[string]bool{}
|
||||
for _, m := range einherjarDepRe.FindAllSubmatch(data, -1) {
|
||||
name := string(m[1])
|
||||
if name == self {
|
||||
continue
|
||||
}
|
||||
seen[name] = true
|
||||
}
|
||||
out := make([]string, 0, len(seen))
|
||||
for k := range seen {
|
||||
out = append(out, k)
|
||||
}
|
||||
sort.Strings(out)
|
||||
return out
|
||||
}
|
||||
|
||||
// parseCompliance parses compliance_test.go (when present) and returns its
|
||||
// interface assertions and test functions. Missing or unparseable files yield
|
||||
// an empty Compliance, not an error — the file is optional.
|
||||
func parseCompliance(modName, modDir string) Compliance {
|
||||
c := Compliance{
|
||||
InterfaceAsserts: []InterfaceAssert{},
|
||||
Tests: []ComplianceTest{},
|
||||
}
|
||||
path := filepath.Join(modDir, "compliance_test.go")
|
||||
data, err := os.ReadFile(path)
|
||||
if err != nil {
|
||||
return c
|
||||
}
|
||||
fset := token.NewFileSet()
|
||||
file, err := parser.ParseFile(fset, path, data, parser.ParseComments)
|
||||
if err != nil {
|
||||
return c
|
||||
}
|
||||
rel, _ := filepath.Rel(modDir, path)
|
||||
|
||||
for _, decl := range file.Decls {
|
||||
switch d := decl.(type) {
|
||||
case *ast.GenDecl:
|
||||
if d.Tok != token.VAR {
|
||||
continue
|
||||
}
|
||||
for _, spec := range d.Specs {
|
||||
vs, ok := spec.(*ast.ValueSpec)
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
if len(vs.Names) != 1 || vs.Names[0].Name != "_" {
|
||||
continue
|
||||
}
|
||||
if vs.Type == nil || len(vs.Values) == 0 {
|
||||
continue
|
||||
}
|
||||
c.InterfaceAsserts = append(c.InterfaceAsserts, InterfaceAssert{
|
||||
Module: modName,
|
||||
Interface: formatNode(fset, vs.Type),
|
||||
Impl: formatNode(fset, vs.Values[0]),
|
||||
File: rel,
|
||||
Line: fset.Position(vs.Pos()).Line,
|
||||
})
|
||||
}
|
||||
case *ast.FuncDecl:
|
||||
if d.Recv != nil {
|
||||
continue
|
||||
}
|
||||
if !strings.HasPrefix(d.Name.Name, "Test") {
|
||||
continue
|
||||
}
|
||||
testDoc := ""
|
||||
if d.Doc != nil {
|
||||
testDoc = strings.TrimSpace(d.Doc.Text())
|
||||
}
|
||||
c.Tests = append(c.Tests, ComplianceTest{
|
||||
Module: modName,
|
||||
Name: d.Name.Name,
|
||||
Doc: testDoc,
|
||||
File: rel,
|
||||
Line: fset.Position(d.Pos()).Line,
|
||||
})
|
||||
}
|
||||
}
|
||||
return c
|
||||
}
|
||||
|
||||
func parseADRHeader(filename string, body []byte) (id, title string) {
|
||||
if m := adrNameRe.FindStringSubmatch(filename); m != nil {
|
||||
id = m[1]
|
||||
title = strings.ReplaceAll(m[2], "-", " ")
|
||||
}
|
||||
if m := h1Re.FindSubmatch(body); m != nil {
|
||||
title = strings.TrimSpace(string(m[1]))
|
||||
}
|
||||
return id, title
|
||||
}
|
||||
|
||||
// extractPurpose returns the first non-empty, non-heading, non-badge paragraph
|
||||
// from the README — typically the blockquote tagline or opening sentence.
|
||||
func extractPurpose(readme string) string {
|
||||
for _, line := range strings.Split(readme, "\n") {
|
||||
t := strings.TrimSpace(line)
|
||||
if t == "" || strings.HasPrefix(t, "#") || strings.HasPrefix(t, "[!") || strings.HasPrefix(t, "[![") {
|
||||
continue
|
||||
}
|
||||
t = strings.TrimPrefix(t, "> ")
|
||||
t = strings.TrimPrefix(t, ">")
|
||||
if t == "" {
|
||||
continue
|
||||
}
|
||||
return t
|
||||
}
|
||||
return ""
|
||||
}
|
||||
|
||||
// extractExamples lifts fenced code blocks from a README, attaching them to
|
||||
// the most recent H2/H3 heading as the example title and the best-guess
|
||||
// sub-package (the heading lowercased, matched against known sub-packages
|
||||
// later — or left blank).
|
||||
func extractExamples(module, readme string) []Example {
|
||||
var out []Example
|
||||
lines := strings.Split(readme, "\n")
|
||||
currentHeading := ""
|
||||
for _, l := range lines {
|
||||
t := strings.TrimSpace(l)
|
||||
if strings.HasPrefix(t, "## ") || strings.HasPrefix(t, "### ") {
|
||||
currentHeading = strings.TrimSpace(strings.TrimLeft(t, "# "))
|
||||
}
|
||||
}
|
||||
_ = currentHeading // headings are walked again below to correlate blocks
|
||||
|
||||
matches := fenceRe.FindAllStringSubmatchIndex(readme, -1)
|
||||
for _, m := range matches {
|
||||
lang := readme[m[2]:m[3]]
|
||||
code := readme[m[4]:m[5]]
|
||||
title := nearestHeading(readme, m[0])
|
||||
out = append(out, Example{
|
||||
Module: module,
|
||||
Title: title,
|
||||
Code: strings.TrimSpace(code),
|
||||
Language: lang,
|
||||
})
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
func nearestHeading(readme string, before int) string {
|
||||
prefix := readme[:before]
|
||||
lines := strings.Split(prefix, "\n")
|
||||
for i := len(lines) - 1; i >= 0; i-- {
|
||||
t := strings.TrimSpace(lines[i])
|
||||
if strings.HasPrefix(t, "## ") || strings.HasPrefix(t, "### ") {
|
||||
return strings.TrimSpace(strings.TrimLeft(t, "# "))
|
||||
}
|
||||
}
|
||||
return ""
|
||||
}
|
||||
|
||||
func joinImport(base, rel string) string {
|
||||
if base == "" {
|
||||
return ""
|
||||
}
|
||||
if rel == "" || rel == "." {
|
||||
return base
|
||||
}
|
||||
return base + "/" + filepath.ToSlash(rel)
|
||||
}
|
||||
35
internal/index/builtins.go
Normal file
35
internal/index/builtins.go
Normal file
@@ -0,0 +1,35 @@
|
||||
package index
|
||||
|
||||
import (
|
||||
_ "embed"
|
||||
)
|
||||
|
||||
//go:embed builtins/README.md
|
||||
var builtinsReadme string
|
||||
|
||||
// BuildBuiltins returns the synthetic "wire" module that documents canonical
|
||||
// Einherjar application wiring conventions. The content is authored as
|
||||
// markdown in builtins/README.md and embedded at compile time.
|
||||
//
|
||||
// The returned module participates in list_modules, get_module, and
|
||||
// get_example exactly like a real Einherjar module — applications can ask
|
||||
// the MCP server for "wire" knowledge the same way they ask for "core" or
|
||||
// "web" knowledge.
|
||||
func BuildBuiltins() Module {
|
||||
m := Module{
|
||||
Name: "wire",
|
||||
ImportPath: "(application internal/wire)",
|
||||
Purpose: extractPurpose(builtinsReadme),
|
||||
Readme: builtinsReadme,
|
||||
DependsOn: []string{},
|
||||
SubPackages: []SubPackage{},
|
||||
Symbols: []Symbol{},
|
||||
ADRs: []ADR{},
|
||||
Compliance: Compliance{
|
||||
InterfaceAsserts: []InterfaceAssert{},
|
||||
Tests: []ComplianceTest{},
|
||||
},
|
||||
}
|
||||
m.Examples = extractExamples("wire", builtinsReadme)
|
||||
return m
|
||||
}
|
||||
338
internal/index/builtins/README.md
Normal file
338
internal/index/builtins/README.md
Normal file
@@ -0,0 +1,338 @@
|
||||
# Wiring Conventions
|
||||
|
||||
> 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.
|
||||
|
||||
## Project layout
|
||||
|
||||
```
|
||||
cmd/<app>/main.go one-line entrypoint that calls wire.Run()
|
||||
internal/wire/launcher.go Run() — builds infra and 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/<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/`.
|
||||
|
||||
## 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
|
||||
|
||||
import (
|
||||
"strings"
|
||||
|
||||
"github.com/google/uuid"
|
||||
|
||||
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"
|
||||
)
|
||||
|
||||
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", "myapp", "env", cfg.AppEnv},
|
||||
})
|
||||
|
||||
signer := authjwt.NewHMACSigner([]byte(cfg.JWT.Secret))
|
||||
|
||||
publicPaths := []string{
|
||||
"/health",
|
||||
"/api/v1/auth/login",
|
||||
"/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,
|
||||
server.WithMiddleware(
|
||||
mw.RequestID(uuid.NewString),
|
||||
mw.Recover(logger),
|
||||
mw.CORS(cfg.CORSOrigins),
|
||||
mw.RequestLogger(logger),
|
||||
authjwt.AuthMiddleware(logger, signer, publicPaths),
|
||||
authmw.EnrichmentMiddleware(logger, &claimsEnricher{}),
|
||||
),
|
||||
)
|
||||
|
||||
v := valid.New(valid.WithMessageProvider(valid.SpanishMessages))
|
||||
provider := rbac.NewClaimsPermissionProvider("masks", claimsFromCtx)
|
||||
|
||||
lc := launcher.New(logger)
|
||||
lc.Append(db, cache, pool, mc, srv)
|
||||
|
||||
withMigrations(lc, logger, cfg)
|
||||
withSuperAdminSeed(lc, db, logger, cfg)
|
||||
|
||||
withHealth(lc, srv, logger, db, cache, mc)
|
||||
withUsers(lc, srv, db, logger, provider, v)
|
||||
// … one withFeature(...) call per feature in your domain.
|
||||
|
||||
return lc.Run()
|
||||
}
|
||||
```
|
||||
|
||||
## 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
|
||||
registration — lives inside the closure.
|
||||
|
||||
```go
|
||||
package wire
|
||||
|
||||
import (
|
||||
"code.nochebuena.dev/einherjar/contracts/security"
|
||||
"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/web/server"
|
||||
|
||||
"myapp/internal/domains"
|
||||
userhandler "myapp/internal/user/handler"
|
||||
userrepo "myapp/internal/user/repository"
|
||||
usersvc "myapp/internal/user/service"
|
||||
)
|
||||
|
||||
func withUsers(
|
||||
lc launcher.Launcher,
|
||||
srv server.Server,
|
||||
db postgres.Component,
|
||||
logger logz.Logger,
|
||||
provider security.PermissionProvider,
|
||||
v valid.Validator,
|
||||
) {
|
||||
lc.BeforeStart(func() error {
|
||||
repo := userrepo.New(db)
|
||||
uow := postgres.NewUnitOfWork(logger, db)
|
||||
svc := usersvc.New(repo, uow)
|
||||
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)).
|
||||
Get("/api/v1/users", h.ListUsers)
|
||||
srv.With(authz(provider, domains.ResourceUsers, domains.GrantCreateUser)).
|
||||
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
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
## Route ordering
|
||||
|
||||
chi matches paths in registration order. Always register literal-segment
|
||||
routes before parametrised-segment routes that share the same prefix.
|
||||
|
||||
✅ Correct:
|
||||
|
||||
```go
|
||||
srv.Put("/api/v1/users/me/password", h.ChangeOwnPassword)
|
||||
srv.Put("/api/v1/users/{user_id}", h.UpdateUser)
|
||||
```
|
||||
|
||||
❌ Wrong — chi binds `me` to `{user_id}` and the literal route is unreachable:
|
||||
|
||||
```go
|
||||
srv.Put("/api/v1/users/{user_id}", h.UpdateUser)
|
||||
srv.Put("/api/v1/users/me/password", h.ChangeOwnPassword)
|
||||
```
|
||||
|
||||
## Authorization
|
||||
|
||||
Every protected route registers with `.With(authz(provider, resource, grant))`:
|
||||
|
||||
```go
|
||||
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.
|
||||
|
||||
## Middleware helpers
|
||||
|
||||
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.
|
||||
func authz(p security.PermissionProvider, resource string, bit int) func(http.Handler) http.Handler {
|
||||
return authmw.AuthzMiddleware(nil, p, resource, security.Permission(bit))
|
||||
}
|
||||
|
||||
// skipPublicPaths wraps mw so it is bypassed for any path that matches publicPaths.
|
||||
// Use this for middleware that must not run on unauthenticated endpoints
|
||||
// (e.g. EnrichmentMiddleware).
|
||||
func skipPublicPaths(publicPaths []string, mw func(http.Handler) http.Handler) func(http.Handler) http.Handler {
|
||||
return func(next http.Handler) http.Handler {
|
||||
inner := mw(next)
|
||||
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
for _, p := range publicPaths {
|
||||
if matched, _ := path.Match(p, r.URL.Path); matched {
|
||||
next.ServeHTTP(w, r)
|
||||
return
|
||||
}
|
||||
}
|
||||
inner.ServeHTTP(w, r)
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
// 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)
|
||||
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
if r.Method == method {
|
||||
if matched, _ := path.Match(pathPattern, r.URL.Path); matched {
|
||||
next.ServeHTTP(w, r)
|
||||
return
|
||||
}
|
||||
}
|
||||
inner.ServeHTTP(w, r)
|
||||
})
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 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)`.
|
||||
|
||||
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 (
|
||||
"time"
|
||||
|
||||
"github.com/golang-jwt/jwt/v5"
|
||||
"github.com/google/uuid"
|
||||
|
||||
authjwt "code.nochebuena.dev/einherjar/auth-jwt"
|
||||
)
|
||||
|
||||
type tokenSignerAdapter struct {
|
||||
signer authjwt.Signer
|
||||
cfg authjwt.TokenConfig
|
||||
}
|
||||
|
||||
var _ authsvc.TokenSigner = (*tokenSignerAdapter)(nil)
|
||||
|
||||
func (a *tokenSignerAdapter) IssueTokenPair(subject string, custom map[string]any) (authdto.TokenPairResponse, error) {
|
||||
now := time.Now()
|
||||
|
||||
access := jwt.MapClaims{
|
||||
"sub": subject,
|
||||
"iss": a.cfg.Issuer,
|
||||
"iat": now.Unix(),
|
||||
"exp": now.Add(a.cfg.AccessTTL).Unix(),
|
||||
}
|
||||
for k, v := range custom {
|
||||
access[k] = v
|
||||
}
|
||||
accessToken, err := a.signer.Sign(access)
|
||||
if err != nil {
|
||||
return authdto.TokenPairResponse{}, err
|
||||
}
|
||||
|
||||
refreshToken, err := a.signer.Sign(jwt.MapClaims{
|
||||
"sub": subject,
|
||||
"jti": uuid.NewString(),
|
||||
"iat": now.Unix(),
|
||||
"exp": now.Add(a.cfg.RefreshTTL).Unix(),
|
||||
})
|
||||
if err != nil {
|
||||
return authdto.TokenPairResponse{}, err
|
||||
}
|
||||
|
||||
return authdto.TokenPairResponse{
|
||||
AccessToken: accessToken,
|
||||
RefreshToken: refreshToken,
|
||||
TokenType: "Bearer",
|
||||
ExpiresIn: int(a.cfg.AccessTTL.Seconds()),
|
||||
}, 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.
|
||||
164
internal/index/index.go
Normal file
164
internal/index/index.go
Normal file
@@ -0,0 +1,164 @@
|
||||
// Package index defines the on-disk schema of the Einherjar framework index
|
||||
// and provides a loader for the embedded JSON blob.
|
||||
//
|
||||
// The index is built once at deploy time by cmd/indexer and consumed by every
|
||||
// MCP tool. Keeping it small, denormalised, and JSON-shaped means tools can
|
||||
// be implemented as straightforward in-memory filters.
|
||||
package index
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"strings"
|
||||
"time"
|
||||
)
|
||||
|
||||
// SchemaVersion identifies the on-disk index format. Bump when fields change
|
||||
// in a way that breaks older consumers.
|
||||
const SchemaVersion = "einherjar.mcp/index/v1"
|
||||
|
||||
// Index is the root of the embedded framework knowledge.
|
||||
type Index struct {
|
||||
Schema string `json:"schema"`
|
||||
Framework string `json:"framework"`
|
||||
BuiltAt time.Time `json:"builtAt"`
|
||||
Modules []Module `json:"modules"`
|
||||
}
|
||||
|
||||
// Module describes one Einherjar module (e.g. core, web, auth-jwt).
|
||||
type Module struct {
|
||||
Name string `json:"name"`
|
||||
ImportPath string `json:"importPath"`
|
||||
Purpose string `json:"purpose"`
|
||||
Doc string `json:"doc,omitempty"`
|
||||
GoVersion string `json:"goVersion"`
|
||||
DependsOn []string `json:"dependsOn"`
|
||||
SubPackages []SubPackage `json:"subPackages"`
|
||||
Symbols []Symbol `json:"symbols"`
|
||||
ADRs []ADR `json:"adrs"`
|
||||
Examples []Example `json:"examples"`
|
||||
Compliance Compliance `json:"compliance"`
|
||||
Readme string `json:"readme,omitempty"`
|
||||
Changelog string `json:"changelog,omitempty"`
|
||||
}
|
||||
|
||||
// Compliance captures a module's compliance_test.go contents: compile-time
|
||||
// interface assertions and the names of structural tests. It exists so an AI
|
||||
// assistant can know about machine-checked conventions before it writes code
|
||||
// that would violate them.
|
||||
type Compliance struct {
|
||||
InterfaceAsserts []InterfaceAssert `json:"interfaceAsserts"`
|
||||
Tests []ComplianceTest `json:"tests"`
|
||||
}
|
||||
|
||||
// InterfaceAssert mirrors one `var _ Iface = impl` line in compliance_test.go.
|
||||
type InterfaceAssert struct {
|
||||
Module string `json:"module"`
|
||||
Interface string `json:"interface"`
|
||||
Impl string `json:"impl"`
|
||||
File string `json:"file"`
|
||||
Line int `json:"line"`
|
||||
}
|
||||
|
||||
// ComplianceTest mirrors one Test* function in compliance_test.go.
|
||||
type ComplianceTest struct {
|
||||
Module string `json:"module"`
|
||||
Name string `json:"name"`
|
||||
Doc string `json:"doc"`
|
||||
File string `json:"file"`
|
||||
Line int `json:"line"`
|
||||
}
|
||||
|
||||
// SubPackage is one importable sub-package of a module.
|
||||
type SubPackage struct {
|
||||
Name string `json:"name"`
|
||||
ImportPath string `json:"importPath"`
|
||||
Doc string `json:"doc"`
|
||||
}
|
||||
|
||||
// Symbol is one exported declaration (type, func, interface, const, var).
|
||||
type Symbol struct {
|
||||
Module string `json:"module"`
|
||||
SubPackage string `json:"subPackage"`
|
||||
Kind string `json:"kind"`
|
||||
Name string `json:"name"`
|
||||
Signature string `json:"signature"`
|
||||
Doc string `json:"doc"`
|
||||
File string `json:"file"`
|
||||
Line int `json:"line"`
|
||||
}
|
||||
|
||||
// ADR is one architectural decision record.
|
||||
type ADR struct {
|
||||
Module string `json:"module"`
|
||||
ID string `json:"id"`
|
||||
Title string `json:"title"`
|
||||
Body string `json:"body"`
|
||||
}
|
||||
|
||||
// Example is a fenced code block lifted from a module README.
|
||||
type Example struct {
|
||||
Module string `json:"module"`
|
||||
SubPackage string `json:"subPackage"`
|
||||
Title string `json:"title"`
|
||||
Code string `json:"code"`
|
||||
Language string `json:"language"`
|
||||
}
|
||||
|
||||
// Load parses the embedded JSON blob into an Index. It validates the schema
|
||||
// version and returns an empty (but non-nil) Index when the blob is the
|
||||
// placeholder shipped before the indexer has been run.
|
||||
func Load(raw []byte) (*Index, error) {
|
||||
if len(raw) == 0 {
|
||||
return &Index{Schema: SchemaVersion, Framework: "einherjar"}, nil
|
||||
}
|
||||
idx := &Index{}
|
||||
if err := json.Unmarshal(raw, idx); err != nil {
|
||||
return nil, fmt.Errorf("index: parse: %w", err)
|
||||
}
|
||||
if idx.Schema != "" && idx.Schema != SchemaVersion {
|
||||
return nil, fmt.Errorf("index: schema mismatch: got %q want %q", idx.Schema, SchemaVersion)
|
||||
}
|
||||
return idx, nil
|
||||
}
|
||||
|
||||
// FindModule returns the module with the given name, or nil if absent.
|
||||
func (i *Index) FindModule(name string) *Module {
|
||||
for k := range i.Modules {
|
||||
if i.Modules[k].Name == name {
|
||||
return &i.Modules[k]
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// SearchSymbols returns up to limit symbols whose name or doc contains q
|
||||
// (case-insensitive). Module name and sub-package are also searched.
|
||||
func (i *Index) SearchSymbols(q string, limit int) []Symbol {
|
||||
if limit <= 0 {
|
||||
limit = 25
|
||||
}
|
||||
needle := strings.ToLower(q)
|
||||
out := make([]Symbol, 0, limit)
|
||||
for _, m := range i.Modules {
|
||||
for _, s := range m.Symbols {
|
||||
if matches(s, needle) {
|
||||
out = append(out, s)
|
||||
if len(out) >= limit {
|
||||
return out
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
func matches(s Symbol, needle string) bool {
|
||||
if needle == "" {
|
||||
return true
|
||||
}
|
||||
return strings.Contains(strings.ToLower(s.Name), needle) ||
|
||||
strings.Contains(strings.ToLower(s.Doc), needle) ||
|
||||
strings.Contains(strings.ToLower(s.SubPackage), needle) ||
|
||||
strings.Contains(strings.ToLower(s.Module), needle)
|
||||
}
|
||||
Reference in New Issue
Block a user