@eonium/ff-migrator

FlutterFlow-to-Flutter FF Migrator scaffold generator.

This package initializes the repo-local FF Migrator cockpit under .eonium/compass/ff_migrator/. FF Migrator is the migration-specific surface for FlutterFlow source requirements, migration thesis, source inventory, source-to-target mapping, visual baselines, backend linkage notes, prompt packs, graph-backed progress, decisions and changelog history.

What this package does

initFfMigrator generates the first production-useful FF Migrator scaffold for a FlutterFlow-to-Flutter migration workflow. The generated files are intentionally mostly empty until a human or external agent fills them with verified migration evidence from a target Flutter repo and a FlutterFlow source export.

Generated files:

.eonium/compass/ff_migrator/LLMsherpa.md
.eonium/compass/ff_migrator/README.md
.eonium/compass/ff_migrator/migration-thesis.md
.eonium/compass/ff_migrator/source-requirements.md
.eonium/compass/ff_migrator/ff-code-practice-rules.md
.eonium/compass/ff_migrator/ff-inventory.md
.eonium/compass/ff_migrator/source-to-target-map.md
.eonium/compass/ff_migrator/visual-baselines.md
.eonium/compass/ff_migrator/backend-linkage.md
.eonium/compass/ff_migrator/backend-contract-gaps.md
.eonium/compass/ff_migrator/migration-graph.json
.eonium/compass/ff_migrator/sprint-graph.json
.eonium/compass/ff_migrator/step-graph.json
.eonium/compass/ff_migrator/schemas/migration-graph.schema.json
.eonium/compass/ff_migrator/schemas/sprint-graph.schema.json
.eonium/compass/ff_migrator/schemas/step-graph.schema.json
.eonium/compass/ff_migrator/schemas/ai-output.schema.json
.eonium/compass/ff_migrator/progress-log.md
.eonium/compass/ff_migrator/decisions.md
.eonium/compass/ff_migrator/changelog.md
.eonium/compass/ff_migrator/prompts/00-initial-analysis.md
.eonium/compass/ff_migrator/prompts/01-populate-sherpa-and-migrator.md
.eonium/compass/ff_migrator/prompts/02-generate-sprints.md
.eonium/compass/ff_migrator/prompts/03-generate-step-list.md
.eonium/compass/ff_migrator/prompts/04-complete-step.md
.eonium/compass/ff_migrator/prompts/05-finalize-overlay.md

Prompt packs

The prompt packs are first-class scaffold outputs for bounded external-AI and repo-local-agent workflows.

| Prompt | Purpose | | --- | --- | | 00-initial-analysis.md | Inspect the supplied target Flutter repo and FlutterFlow source evidence without implementing app code. | | 01-populate-sherpa-and-migrator.md | Populate FE Sherpa, Business Sherpa and FF Migrator with verified evidence while preserving the boundary between durable truth and migration tactics. | | 02-generate-sprints.md | Generate or refine the migration sprint graph from verified source evidence and repo-local truth. | | 03-generate-step-list.md | Generate a bounded step graph for one selected sprint only. | | 04-complete-step.md | Complete exactly one active graph step and return a repo-accurate drop-in ZIP, overlay or patch when requested. | | 05-finalize-overlay.md | Consolidate completed, validated work into a final overlay or ZIP plus release-readiness instructions. |

Each prompt is written for two operating modes:

• Uploaded-ZIP workflow: a human uploads the target repo snapshot and FlutterFlow source export to ChatGPT, Codex, Claude or a similar external AI environment, then requests a repo-accurate drop-in ZIP or overlay.
• Repo-local agent workflow: an agent runs in the checked-out repo and reads .eonium/compass/ before making bounded changes.

Prompt packs are not executed by Eonium. They are operating instructions that help humans and external agents avoid drift.

Anti-drift invariant

Every migration task should follow this invariant before making changes:

1. Check FF Migrator to understand the current migration objective, graph location, locked dependencies and exact step scope.
2. Check FE Sherpa and Business Sherpa to understand long-lived app truth, naming, architecture, backend contracts and already-completed work.
3. Do not implement outside the active graph step.
4. Do not create files unless the graph calls for them or the need is explicitly justified.
5. Update logs after work changes behaviour, architecture, current state, graph status or important project knowledge.

Write behaviour

The initializer uses the shared Compass scaffold writer from @eonium/compass-core.

• If no mode is supplied, initialization defaults to dry-run and reports a warning.
• Dry-run mode reports the files that would be created or updated without writing .eonium files.
• Write mode creates missing FF Migrator files.
• Existing files are preserved by default.
• Already-current files are skipped.
• Existing files are updated only when force: true is supplied.
• The returned result includes files, scaffoldResults, changed, dryRun, force and the shared Compass change report.
• The returned report distinguishes created, updated, skipped, warned and errored files.

Migration-specific boundary

This package creates FF Migrator scaffolds only.

FF Migrator owns FlutterFlow-to-Flutter migration state and guidance such as:

• FlutterFlow source requirements and source inventory;
• migration thesis and source-to-target mapping;
• FlutterFlow code-practice conversion rules;
• visual baseline requirements;
• backend linkage notes and backend contract gaps;
• migration, sprint and step graph seeds;
• JSON Schema files for the migration graph, sprint graph, step graph and external-agent output shape;
• prompt packs for external AI and repo-local agent workflows;
• progress logs, migration decisions and migration changelog entries.

It does not own long-lived target frontend truth. Target routes, screens, components, design system, state conventions, API assumptions and frontend commands belong in Frontend Sherpa. It also does not own durable business truth such as workflows, lifecycle rules, permissions, calculations, domain concepts or side effects; those belong in Business Sherpa.

Backend linkage modes

The scaffold supports migrations with or without backend evidence.

• No backend repo: record FlutterFlow Firebase usage, API calls, client-side business logic, security-sensitive client writes and unknown backend gaps as migration evidence.
• Backend repo without Sherpa: record backend linkage as available but unstructured; do not silently trust or duplicate backend implementation details.
• Backend repo with Backend Sherpa: summarize only frontend-relevant contracts and record disagreements between FE Sherpa, FF Migrator and Backend Sherpa as gaps.

Graph and log purpose

The generated graph files are minimal valid JSON seeds, not a full planner.

• migration-graph.json tracks top-level migration objectives and locks.
• sprint-graph.json tracks migration sprint scope once sprints are planned.
• step-graph.json tracks the active sprint's implementation steps once generated.
• schemas/migration-graph.schema.json, schemas/sprint-graph.schema.json and schemas/step-graph.schema.json document the graph contracts that humans or external agents should preserve while editing graph files.
• schemas/ai-output.schema.json documents the expected shape of external-agent reports without making Eonium an AI runtime.
• progress-log.md, decisions.md and changelog.md record what changed, why it changed, and what future humans or agents must know.

Every migration task should use the active graph scope first, then read Frontend Sherpa and Business Sherpa for durable truth before making changes.

Schema files

The generated schema files are repo-local contracts for graph and output shape. They are scaffolded alongside the graph seeds so package consumers can inspect the complete FF Migrator scaffold contract, but the initializer does not run validation, implement a planner or execute any AI workflow.

Sprint 7 validation gate

Do not call the Sprint 7 FF Migrator graph-schema work prod-ready until the repo passes all of these checks from a clean checkout after applying the Sprint 7 overlays:

npm run typecheck
npm run lint
npm run build
npm run test --workspace @eonium/ff-migrator
npm run verify

API

import { initFfMigrator } from "@eonium/ff-migrator";

const dryRun = initFfMigrator({ repoRoot: process.cwd() });
const write = initFfMigrator({ repoRoot: process.cwd(), mode: "write" });
const forced = initFfMigrator({ repoRoot: process.cwd(), mode: "write", force: true });

initFfMigrator() returns the generated file descriptors, per-file scaffold results, a boolean changed value and a Compass change report suitable for CLI orchestration.

Non-goals

This package does not:

• call AI providers;
• require BYOK configuration;
• parse FlutterFlow projects;
• inspect FlutterFlow source automatically;
• convert FlutterFlow widgets into Flutter code;
• generate target app routes, widgets, state controllers, services or tests;
• execute prompt packs or host repo-local agents;
• validate graph JSON at runtime;
• implement a full migration planner;
• create Create or Portability scaffolds;
• orchestrate the grouped CLI setup path;
• automatically migrate FlutterFlow apps.

Eonium is the repo-local rails for migration work. External humans or agents are the workers that read the generated scaffold, inspect the provided repos and fill the migration truth over time.