Wheels 4.0: Module system and package format

[bpamiri]

Summary

Self-contained module system with declarative package format for Wheels 4.0.

Details

• Modules declare provides, requires, replaces, suggests in box.json
• Module discovery CLI: wheels module:search, wheels module:install, wheels module:create
• Module registry for community modules
• Lazy loading and compiled module dependency graph
• Part of Wheels 4.0 epic (Plugin system → Service Provider model (Wheels 4.0) #1917)

Source

design_docs/architecture/wheels-4-architecture-guide.md

[bpamiri]

Analysis

Synopsis

This issue proposes a self-contained module system for Wheels 4.0 with declarative box.json metadata (provides, requires, replaces, suggests), module CLI commands, a community registry, lazy loading, and a compiled dependency graph.

Merit Assessment

Recommendation: Proceed with modifications

• Strong foundation exists. The current plugin system (vendor/wheels/Plugins.cfc) already reads box.json for metadata (lines 184-196) and has basic dependency tracking via component @dependency metadata (lines 198-213). This is a natural evolution, not a greenfield rewrite.
• Solves real problems. The existing system uses zip extraction + StructAppend mixin injection into variables scope (line 313 of Plugins.cfc), which has collision risk and no namespacing. Two plugins with the same method name silently overwrite each other.
• CLI scaffolding already exists. The wheels CLI has module-adjacent commands today; adding module:search/install/create is incremental.
• Modification needed: scope the registry. A full community registry is a significant operational burden (hosting, moderation, security). Start with Git-based resolution (ForgeBox/GitHub) and add a curated registry later. Phase the CLI commands — module:create first, module:install second, module:search last.

Implementation Plan

1. Define module manifest schema — Extend box.json with provides, requires, replaces, suggests keys. Document the schema. No code change needed for reading — $pluginMetaData() in Plugins.cfc (line 184) already deserializes box.json.
2. Build module loader — New vendor/wheels/ModuleLoader.cfc that replaces the zip-extract-and-mixin flow in Plugins.cfc. Should resolve the dependency graph at startup using the requires/suggests metadata, topologically sort, and instantiate in order. Integrate with Injector.cfc for service registration.
3. Implement register() / boot() lifecycle — Per the parent epic (Plugin system → Service Provider model (Wheels 4.0) #1917), modules should implement a ServiceProvider interface with register(container) and boot(app) hooks. This replaces the current $processMixins() approach (line 219 of Plugins.cfc).
4. Wire into bootstrap — Modify vendor/wheels/events/onapplicationstart.cfc (around line 236) to call ModuleLoader instead of (or alongside) $loadPlugins().
5. CLI commands — module:create scaffold (generates box.json + ServiceProvider.cfc stub), then module:install (ForgeBox/GitHub resolution).
6. Lazy loading — Defer module instantiation until first getInstance() call via the DI container; the container already supports this pattern.

Estimated complexity: Large. Core loader + lifecycle hooks = ~2-3 weeks. CLI commands = ~1 week. Registry = deferred.

Dependencies & Risks

• Prerequisite: Wheels 4.0: Interface-driven design contracts #1967 (interface-driven contracts) should land first so modules can declare which interfaces they implement via provides.
• Prerequisite: Plugin system → Service Provider model (Wheels 4.0) #1917 (ServiceProvider model) is the parent — the module system is the packaging format for service providers.
• Breaking change risk: Medium. The $processMixins() path must remain functional during transition (see Wheels 4.0: Legacy compatibility adapter and migration path #1969 legacy adapter). The mixableComponents list (line 15 of Plugins.cfc: "application,dispatch,controller,mapper,model,base,sqlserver,mysql,postgresql,h2,test") would be replaced by explicit contract registration.
• Related: Wheels 4.0: Legacy compatibility adapter and migration path #1969 (legacy adapter) must ship simultaneously to preserve backward compatibility for existing plugins.

---

Automated analysis by @claude — review and adjust as needed.