Command self-registration in executor to reduce agentic discovery cost

[ako]

Problem

The executor has 241 files with no structural guide for where to add a new command. Adding a command requires: (a) creating a cmd_*.go file, (b) finding and editing the central dispatch switch, and (c) knowing the correct context type. An AI code generator (or a new contributor) must read across multiple files to understand the pattern. This increases the cognitive load and the likelihood of missing a step.

Proposed solution

Replace the central dispatch switch with a registration pattern where each cmd_*.go file self-registers its handler via init(). A new command is then entirely contained in one file — no other file needs to change.

Proposed pattern:

// cmd_entities.go
func init() {
    executor.Register(ast.KindCreateEntity, handleCreateEntity)
    executor.Register(ast.KindAlterEntity, handleAlterEntity)
}

func handleCreateEntity(ctx *executor.ExecContext, stmt ast.Statement) error {
    s := stmt.(*ast.CreateEntityStatement)
    return ctx.Backend.DomainModel().CreateEntity(s.Name, ...)
}

// executor/registry.go
var handlers = map[ast.StatementKind]HandlerFunc{}

func Register(kind ast.StatementKind, fn HandlerFunc) {
    handlers[kind] = fn
}

Implementation steps

1. Add executor/registry.go with Register() and the handler map
2. Replace the central dispatch switch with a registry lookup
3. Migrate existing cmd_*.go files to register via init() — one file at a time, running tests after each
4. Remove the dispatch switch from executor.go

Expected outcome

Adding a new MDL command requires creating exactly one new file. No other file needs to change. The pattern is self-documenting — any existing cmd_*.go serves as a complete example.

See proposal: docs/11-proposals/PROPOSAL_agentic_architecture_improvements.md (Change 3)

[github-actions]

Issue Triage

Summary:
The issue proposes replacing the executor’s central dispatch switch with a self‑registration pattern so each command lives in its own cmd_*.go file, reducing the cognitive load for contributors and AI code generators.

Checklist for feature request

Required info	Present?	Notes
Use case – why the feature is needed, what problem it solves	✅	Described in the “Problem” section.
Proposed syntax or behavior (if applicable)	✅	Detailed pattern with init() registration and registry lookup.
Mendix version relevance (if version‑specific)	⚠️	Not mentioned; the change appears to be internal to mxcli and not tied to a specific Mendix version, so it’s not required.

Conclusion:
All essential information for a feature request is provided. Thank you for the clear proposal!

---

Automated triage via OpenRouter — workflow source

[retran]

Wanted to do same as one of next steps, but didn't decide on registration pattern as not sure what is idiomatic for Go.

[retran]

To elaborate on my previous comment:

The init() and registry pattern you proposed is definitely a valid and classic Go idiom (it's used a lot in the standard library, like in database/sql). It perfectly solves the issue of keeping everything in one file.

However, its main downside is that it creates a global state (the map of handlers). This can make isolated testing much harder because tests might modify the same map and interfere with each other.

This is actually why the central dispatcher is still there — my idea was to eventually replace it with an auto-generated dispatcher using go generate.

If we go with code generation:

• We still get to keep each command in its own isolated file (which is the main goal here!).

• A small script scans the files and automatically generates a dispatch_gen.go file with a giant switch statement before the build.

• We avoid global state entirely, which makes testing much easier and keeps the performance benefits of a switch.

Your proposal is a great and pragmatic solution to the problem. I just wanted to put the go generate alternative on the table.

[ako]

Change 3 is already implemented — but without init(), which directly addresses the testing concern raised above.

What's there now: mdl/executor/registry.go has a Registry struct and a NewRegistry() constructor that explicitly calls 29 registerXxxHandlers(r) functions (one per domain), defined in register_stubs.go. The comment in the source is explicit: "Registration functions are called here explicitly (no init())."

Why init() was skipped: @retran's concern is exactly right. With init(), the handler map becomes package-level global state that's pre-populated before any test runs. The test suite relies on emptyRegistry() — a factory that returns a zero-handler *Registry — for six tests:

• TestRegistry_Dispatch_UnknownStatement (verifies UnsupportedError for unregistered types)
• TestRegistry_Validate_Empty / TestRegistry_Validate_Partial (registry completeness checks)
• TestRegistry_Register_Duplicate_Panics (wiring-error detection)

None of these are writable if init() has already populated the global. Additionally, handler tests (e.g. cmd_entities_mock_test.go) call the handler functions directly with a MockBackend, bypassing the registry entirely — so they're isolated by design regardless.

What go generate would add: retran's alternative (generating a dispatch_gen.go switch from a scan) would also work and avoid global state. The explicit NewRegistry() approach gives the same properties with no tooling dependency: TestNewRegistry_Completeness fails at CI if a new statement type has no handler, which is the same safety net a generated switch would provide.

Adding a command today: Create cmd_yourfeature.go with the handler, add a registerYourFeatureHandlers(r) call in NewRegistry(), and add the stub in register_stubs.go. The completeness test catches a missed registration. register_stubs.go serves as an index of all registered commands — any existing entry is a complete example.

The proposal doc (docs/11-proposals/PROPOSAL_agentic_architecture_improvements.md) has been updated to reflect that Change 3 is shipped and to explain the init() trade-off.