@eonium/config

Config loading, defaults, and validation helpers for Eonium Compass.

This package owns the eonium.config.json contract and the deterministic logic for finding, reading, validating, and normalising config files. It does not edit project files, prompt users, install packages, call AI models, store secrets, or store migration analysis.

Current scope

• Find eonium.config.json from a working directory.
• Load and parse JSON config.
• Merge user config with Eonium defaults.
• Validate the required config shape and package-level cross-field invariants.
• Return structured diagnostics instead of throwing for expected user mistakes.
• Provide a pure FlutterFlow-to-Flutter migration-mode config builder for later CLI orchestration.
• Preserve top-level paths, validation, and ai sections when config is loaded or merged.

FlutterFlow-to-Flutter migration config

Sprint 9 adds config vocabulary for the scaffold-first FlutterFlow-to-Flutter migration workflow. The config records mode, pointers, policy and validation commands only. Migration truth stays in .eonium/compass/ff_migrator/, frontend truth stays in .eonium/compass/sherpa/frontend/, durable behaviour stays in .eonium/compass/sherpa/business/, and work artifacts stay under .eonium/compass/create/ and .eonium/compass/portability/.

The migration-mode helper is createFlutterFlowToFlutterMigrationConfig. It returns a normal EoniumConfig with Flutter app defaults and these migration-specific sections:

• compass.mode: "flutterflow_to_flutter_migration" records the active Compass mode.
• compass.surfaces.sherpa enables FE Sherpa and Business Sherpa and records backend Sherpa linkage as optional.
• compass.surfaces.create.enabled: true records that Create artifacts are part of the workflow.
• compass.surfaces.portability.enabled: true and migrations: ["flutterflow_to_flutter"] record the Portability migration context.
• compass.surfaces.ffMigrator.enabled: true records that the FF Migrator cockpit is active.
• compass.generatedFilePolicy records preserve_existing, preserveExisting: true, forceRequiresExplicitFlag: true, and the managed scaffold roots.
• paths.frontendSherpa points to .eonium/compass/sherpa/frontend.
• paths.businessSherpa points to .eonium/compass/sherpa/business.
• paths.ffMigrator points to .eonium/compass/ff_migrator.
• paths.create points to .eonium/compass/create.
• paths.portabilityMigration points to .eonium/compass/portability/migrations/flutterflow_to_flutter.
• validation.commands records the generated Flutter target repo checks: dart format --set-exit-if-changed ., flutter analyze, and flutter test.
• ai.callsModels: false records that Eonium itself does not call ChatGPT, Claude, Codex, OpenAI, Anthropic or any BYOK provider.
• ai.expectedUsage records supported external workflows: repo-local agents reading .eonium and humans uploading repo ZIPs to external AI.

eonium.config.json is not the source of truth for FlutterFlow analysis, source-to-target maps, sprint graphs, step graphs, visual baselines, backend gaps, prompt-pack content, progress logs, or migration decisions. Those belong in the generated repo-local Compass artifacts, especially FF Migrator and Sherpa.

Validation responsibility

The JSON Schema recognises the migration-mode fields, but the package validator remains the source of truth for semantic checks that need cross-field knowledge. For flutterflow_to_flutter_migration, validateEoniumConfig checks that required path pointers exist, paths are safe repo-relative strings, migration surface keys are known, backend-linkage values are valid, validation commands are non-empty, generated-file policy is explicit, and ai.callsModels is exactly false.

Not in scope yet

• CLI prompts.
• User-facing eonium init --mode flutterflow-to-flutter orchestration.
• File upserts.
• Package installation.
• Compass init or doctor commands.
• FlutterFlow parsing.
• Automatic migration, UI conversion, screenshot comparison, or target app code generation.
• AI provider calls or BYOK configuration.