magic-framework

Magic Framework

Laravel-inspired Flutter framework: IoC container, 18 facades, Eloquent-style ORM, service providers, reactive controllers, and GoRouter-backed routing. This skill makes an agent write code that an experienced magic developer would write: facade-first, IoC-resolved, reactive, and verified against the real API in lib/src. All visual styling is handled by Wind (load the wind-ui skill for className work); this skill owns architecture, data, navigation, auth, and testing.

The host app already depends on package:magic/magic.dart. The accuracy contract for this skill: every API you write must exist in lib/src. When unsure of a signature, open the source or the matching doc/** page rather than guessing; magic is pre-1.0 and the surface is exact, not approximate.

0. Before writing code in this project

Three checks, each pays off across the whole session.

1. Read lib/main.dart and lib/config/app.dart. Note the providers list and its ORDER (AppServiceProvider must precede AuthServiceProvider so setUserFactory is set before auth restore runs), and whether configFactories or configs is used.
2. Scan one existing controller + view pair in lib/app/ for the project's idioms: the singleton accessor shape, how views resolve controllers, how forms are wired. Match the surrounding code, do not invent a dialect.
3. CLI invocation. Magic ships an artisan executable, so every command runs as dart run magic:artisan <cmd> from any app that depends on magic (no package-name placeholder, no global activate).

1. Core Laws

Hard constraints for every line of magic code.

1. await Magic.init() first. It must be awaited in main() before any facade call and before runApp(). Never .then(); providers are not booted until the future completes.
2. Facade-first. Reach for Auth, Http, Config, Cache, DB, Schema, Log, Event, Echo, Lang, MagicRoute, Gate, Session, Vault, Storage, Pick, Crypt, Launch. Resolve from the container manually (Magic.make<T>('key')) only when extending the framework.
3. Controllers are singletons. static X get instance => Magic.findOrPut(X.new); is the canonical accessor. Views resolve controllers via Magic.find<T>() (automatic in MagicView), never through constructors.
4. IoC over new for services. Bind in a provider's register(), resolve via the facade or Magic.make<T>('key'). Do not scatter Service() construction across the app.
5. Provider discipline. register() is synchronous and is where routes and bindings go. boot() is async and may resolve other services; set Auth.manager.setUserFactory(...) here.
6. Reactive state, not setState. Controllers extend MagicController (a ChangeNotifier); state flows through MagicStateMixin + RxStatus. Use refreshUI() (guarded notifyListeners, and the single seam every controller notification goes through, including validation), setLoading/setSuccess/setError/setEmpty, and MagicBuilder for sections. MagicController.onRefreshUI is a null-by-default static debug tooling sets to observe those notifications. Local setState belongs only to genuine widget-local UI state inside a MagicStatefulView.
7. Typed attribute access. Models use get<T>('key') and set('key', v), never raw getAttribute. Declare fillable; use fill(validated, strict: true) after validation so schema drift throws MassAssignmentException.
8. Context-free navigation and feedback. MagicRoute.to/back/replace, Magic.snackbar/toast/dialog/confirm/loading. Never depend on a BuildContext for navigation or feedback. Never navigate or fetch inside build().
9. Validate at the boundary. MagicFormData for forms, FormRequest for complex payloads, Validator for ad hoc checks. Surface server errors with handleApiError(response) (from the ValidatesRequests mixin).
10. Trailing commas, multi-line collections. Always. Match the project's existing style.