e1802e4c259c3b9a75249d729b308896ab04b49a
10
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 Rene Nochebuena
|
e1802e4c25
|
fix(mcp): allowedorigins-removed message says v1.3.0, not v2.0.0 | ||
|
Rene Nochebuena
|
3961ae7175
|
feat(mcp): add web.allowedorigins-removed rule; document v1.3.0 CORS migration | ||
|
Rene Nochebuena
|
03a8d8a641
|
feat(mcp): scaffold uses real EINHERJAR_SERVER_CORS_ORIGINS; document web.New vs server.New (v1.2.0) | ||
|
Rene Nochebuena
|
6b4d9be141
|
fix(mcp): CORS-aware scaffold, cors.wildcard rule, server-not-appended FP; v1.1.2 | ||
|
Rene Nochebuena
|
81233311d9
|
feat(mcp): check_env struct-level granularity via composes selectors (#4)
Patch to v1.1.1. check_env could only reason at module granularity, so a var that lives on one struct of a multi-struct module (e.g. EINHERJAR_SERVER_CORS_ORIGINS on web.Config, not web/server.Config) couldn't be flagged dead when the app composes the sibling struct. Adds struct-level selectors to close that gap. internal/tools (check_env): - New `composes` input: exact config structs as module/subpackage/Struct selectors (e.g. web/server/Config, db-postgres/Config, core/logz/Config), alongside or instead of the coarse `modules` list. - not-composed now reasons over the union of composed vars (from modules AND struct selectors), so it surfaces struct-level dead vars. Coarse modules:["web"] keeps the prior behavior. - parseStructSelector helper; errors on malformed or non-existent selectors. Tests: struct-level dead-var catch (CORS flagged with web/server/Config but not with module web), bad-selector errors; existing calls updated to the new arg. Version bumped to v1.1.1 (badge + serverVersion). No dependency changes. Reviewed-on: #4 Co-authored-by: Rene Nochebuena Guerrero <rene@nochebuena.dev> Co-committed-by: Rene Nochebuena Guerrero <rene@nochebuena.dev> |
||
|
Rene Nochebuena
|
850b63607c
|
feat(mcp): derive env vars from the framework's real struct tags (#3)
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>
|
||
|
Rene Nochebuena
|
a0b803cb40
|
feat(mcp): scaffold tool, config/env conventions, and scaffold-hygiene rules (#2)
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: #2 Co-authored-by: Rene Nochebuena Guerrero <rene@nochebuena.dev> Co-committed-by: Rene Nochebuena Guerrero <rene@nochebuena.dev> |
||
|
Rene Nochebuena
|
13a186c60a
|
feat(mcp): index struct fields and interface method sets (#1)
Minor release. The indexer named composite types but could not describe their shape: every declaration was truncated at the first brace, so a struct symbol carried only its `type X struct` header and an interface symbol only its `type X interface` header. Field names, field types, and — most painfully — struct tags such as `env:"EINHERJAR_PG_HOST"` were dropped, as were the method sets of every port interface. An assistant could be told that `db-postgres` has a `Config` and a `Provider`, but not what env vars configure the one or what methods the other requires. This change captures both. internal/index (schema): - Symbol gains two optional fields. `fields` ([]Field) carries a struct's field set — name, type, raw struct tag (surrounding backticks stripped), doc comment, and an `embedded` marker. `methods` ([]Method) carries an interface's method set — name, signature without the leading `func`, and doc comment, including embedded interfaces. Both are omitempty and absent for every other kind. - SchemaVersion is deliberately unchanged. The two additions are additive and omitempty, so an older consumer parses the new index unchanged; per the existing rule the constant only bumps on a breaking format change. internal/index (builder): - collectSymbols now inspects each type's TypeSpec and, for a *ast.StructType or *ast.InterfaceType, fills the new Symbol members. A grouped field declaration (`x, y int`) yields one Field per name; an embedded field or interface yields an entry with an empty name. - New helpers: typeSpecType (underlying type expr of a lone type spec), extractFields, extractIfaceMethods, fieldDoc (doc comment or trailing line comment), and nodeString — a non-truncating printer used for field types, tags, and method signatures, distinct from formatNode which keeps truncating to produce the one-line header. internal/index (search): - matches() now also tests the query against struct field names, field types, and struct tags, and against interface method names and signatures. A query like an env-var key or a method name now resolves to the type that declares it. internal/tools: - get_symbol and search_symbols descriptions updated to advertise the new struct-field and interface-method coverage. No input/output schema change beyond the additive Symbol fields, which get_symbol already returns whole. internal/index (tests): - New builder_test.go — the package previously had no tests. Builds a temporary module fixture and asserts capture of struct fields (with tags and docs), embedded fields, interface methods (with signatures and docs), embedded interfaces, and discovery of a struct by one of its struct tags (the failure mode that motivated the change). Docs: - CHANGELOG.md gains an [Unreleased] entry; README.md tool table updated to state that get_symbol returns struct fields and interface methods and that search_symbols matches fields, tags, and methods. No new dependencies. The committed data/index.json placeholder is untouched — the index is regenerated at image build (Dockerfile runs cmd/indexer), so a deployment must be rebuilt to serve the richer index; a server still running the prior image keeps serving the older, member-less one. Reviewed-on: #1 Co-authored-by: Rene Nochebuena Guerrero <rene@nochebuena.dev> Co-committed-by: Rene Nochebuena Guerrero <rene@nochebuena.dev> |
||
|
Rene Nochebuena
|
e23e86b06c
|
feat(mcp): systemd socket activation and healthz under /mcp (v0.1.1)
Patch release. Two changes to cmd/server, both motivated by running the service behind a unix socket on a reverse-proxied host: the binary now inherits a systemd-passed listener when present, and the healthz handler moves under the same path prefix as the MCP endpoint so a single proxy location forwards both. Bundled with two repository-hygiene changes. cmd/server: - chooseListener (new) — picks a listener at startup. When systemd has passed a LISTEN_FDS fd via github.com/coreos/go-systemd/v22/activation, the binary uses the inherited listener; otherwise it binds TCP at -addr as before. The startup log records "mode":"socket-activated" or "mode":"tcp" so operators can confirm which path is live. Same binary works for local dev and for systemd-managed deployment with no flags or env vars to toggle. - Health probe path is now derived from -path. With the default -path /mcp the probe is served at /mcp/healthz; the legacy /healthz route is no longer registered. A reverse proxy can now route the whole MCP service through a single "/mcp" location prefix instead of maintaining a second forward for /healthz. Consumers of v0.1.0 that hit /healthz directly must switch to /mcp/healthz. Dependencies: - github.com/coreos/go-systemd/v22 v22.7.0 — listener inheritance via LISTEN_FDS. Loaded only by cmd/server. Docs: - README.md "Deployment" section rewritten to be hosting-agnostic. The v0.1.0 draft prescribed a specific systemd-on-HestiaCP layout; the new text points at the Dockerfile and at systemd socket activation as a supported binary mode without dictating one operator's setup. Adds an explicit note that any reverse proxy must disable response buffering on the /mcp location — streamable MCP delivers tool results via Server-Sent Events and default proxy buffering breaks the stream. Repository hygiene: - /deploy/ is now .gitignored. Local deployment artefacts (systemd units, reverse-proxy templates, per-release scripts) are operator-specific by design and live outside the public repository. The Dockerfile at the module root remains the only portable, public-facing build artefact. No tool surface, no validation rules, no index schema, and no behaviour of the indexer changed. Operators upgrading from v0.1.0 must update their health-probe URL to /mcp/healthz (or whichever path matches their -path flag); MCP-protocol clients (Claude, Cursor, Zed, etc.) need no changes. |
||
|
Rene Nochebuena
|
cc62906c6f
|
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.
|