Eonium

Eonium is the open-source initiative and package namespace.

The first product being built here is Eonium Compass: an AI-native, repo-located development enablement suite that helps humans and coding agents understand, extend, test, migrate, and ship software projects faster.

This repo uses Compass/Sherpa as its own operating guide. Before making changes, read:

.eonium/compass/sherpa/LLMsherpa.md
.eonium/compass/sherpa/backend/LLMsherpa.md

Current status

The repo now contains the Phase 1 foundation, the Phase 2 backend Sherpa package, the MVP runtime/generator surface, and the 0.5.1 Compass surface expansion. Compass is organized around three product surfaces:

• Sherpa records what is true.
• Create moves the repo toward what should be true.
• Portability keeps business logic from being trapped by today's stack.

Implemented workspace packages:

• @eonium/config
• @eonium/compass-core
• @eonium/compass-sherpa
• @eonium/compass-be-sherpa
• @eonium/cli
• @eonium/any-db
• @eonium/any-auth
• @eonium/be-http
• @eonium/be-jobs

Bounded scaffold generator packages that are implemented enough to create repo-local Compass surfaces but are not full engines:

• @eonium/compass-create generates the Create artifact scaffold for specs, plans, runs, overlays, validation and finalize notes; it does not implement Create Build or Finalize engines.
• @eonium/compass-fe-sherpa generates the long-lived frontend truth scaffold; it does not parse FlutterFlow exports or own migration tactics.
• @eonium/compass-business-sherpa generates durable business-truth scaffolds; it does not perform source-code archaeology or backend mapping.
• @eonium/compass-migrate generates the Portability/Migrate placeholder scaffold for FlutterFlow-to-Flutter status, provider-coupling and compatibility planning; it does not execute migrations.
• @eonium/ff-migrator generates the FlutterFlow Migrator instruction, prompt-pack, graph-schema, seed-graph and log scaffold; it does not call AI, parse exports or convert apps automatically.

Shell packages that are intentionally importable/buildable but not product-complete yet:

• @eonium/compass-portability
• @eonium/create-project
• @eonium/create-analyze
• @eonium/create-spec
• @eonium/create-plan
• @eonium/create-build
• @eonium/create-test
• @eonium/create-finalize
• @eonium/create-publish
• @eonium/publisher as the legacy compatibility shell for Create Publish
• @eonium/any-ai
• @eonium/any-comms
• @eonium/logging
• @eonium/utils
• @eonium/provider-adapter-protocol
• @eonium/db-synchroniser and @eonium/db-tester as compatibility shells under Portability Migrate
• @eonium/compass-graph
• @eonium/compass-overlay
• @eonium/compass-validation
• @eonium/package-manager-adapters
• @eonium/stack-detectors

The runtime packages are extracted from Nexeo-compatible code paths while keeping application-owned schema, DB names, provider credentials, HTTP handler naming, and job definitions in the target app. Generator-backed scaffold packages create bounded repo-local instructions, prompt packs, graph/log placeholders and config pointers through explicit CLI commands. Remaining shell packages expose status metadata and non-mutating placeholder initializers only.

Install / target project direction

The root package is prepared to be packed or published as eonium. Consumer-facing imports are exposed as package subpaths:

import { dbRead, dbCreate } from "eonium/any-db";
import { FirebaseAuthAdapter } from "eonium/any-auth";
import { withApi } from "eonium/be-http";
import { registerRuntimeJob } from "eonium/be-jobs";

A Nexeo-shaped config template is included at:

templates/target-configs/nexeo/eonium.config.json

It uses the published JSON Schema and ${.env...} / ${.env.secrets...} reference syntax for secret-backed values rather than storing secret literals in git.

Local development

Required runtime: Node.js 24.x with npm 11.x. The repo pins the local runtime through .node-version and .nvmrc, and the root package declares packageManager as [email protected].

Install dependencies once after cloning or after package metadata changes:

npm install

Run the canonical local verification command before committing:

npm run verify

npm run verify is the same npm-first verification path used by CI. It runs ordered package build, typecheck, lint, package self-tests, config schema validation, Sherpa validation, backend graph validation, backend graph dry-run generation, and package dry-run checks.

The individual checks are also available when narrowing down a failure:

npm run build
npm run typecheck
npm run lint
npm run test
npm run schema:validate
npm run sherpa:validate
npm run sherpa:graph:validate
npm run sherpa:graph:build:dry-run
npm run pack:check

npm run build, npm run typecheck, npm run lint, and npm run test are npm aliases over the ordered workspace runner so the package order is deterministic and the Nexeo-compatible runtime dependencies are built before dependent packages. npm run sherpa:graph:validate expects the canonical graph artifacts to exist and is now part of npm run verify; npm run sherpa:graph:build:dry-run remains a non-mutating reproducibility check.

Local CLI usage

Build the packages before running the repo-local CLI:

npm run build

Then use the root eonium script and pass CLI arguments after --:

npm run eonium -- help
npm run eonium -- tools list
npm run eonium -- doctor
npm run eonium -- sherpa validate
npm run eonium -- sherpa init backend --dry-run
npm run eonium -- sherpa init backend --yes
npm run eonium -- sherpa graph build --dry-run
npm run eonium -- sherpa graph validate
npm run eonium -- init --dry-run
npm run eonium -- add any-db --dry-run
npm run eonium -- add be-http --dry-run

The root npm scripts provide the supported local graph entrypoints:

npm run sherpa:graph:build:dry-run
npm run sherpa:graph:build
npm run sherpa:graph:validate

After npm install and npm run build, the package binary can also be invoked locally through npm's linked binary:

npx --no-install eonium doctor
npx --no-install eonium sherpa validate
npx --no-install eonium sherpa graph build --dry-run
npx --no-install eonium sherpa graph validate
.\node_modules\.bin\eonium.cmd sherpa validate

Target repos and published-package consumers should use the npm package binary through npx eonium ...:

npx eonium sherpa graph build --dry-run
npx eonium sherpa graph build --yes
npx eonium sherpa graph validate

Direct eonium ... commands are only expected to work after the CLI has been globally linked, globally installed, or installed as a dependency in the target project.

FlutterFlow-to-Flutter migration scaffold workflow

Eonium can scaffold a fresh Flutter target repo for a FlutterFlow-to-Flutter migration using the current npm/TypeScript CLI wedge. This is a Compass operating surface for humans and external AI coding workflows, not an automatic migration engine.

From the fresh Flutter target repo, preview the scaffold first:

npx eonium init --dry-run --mode flutterflow-to-flutter

Then write the scaffold explicitly:

npx eonium init --yes --mode flutterflow-to-flutter

The command creates the repo-local FE Sherpa, Business Sherpa, FF Migrator, Create and Portability migration scaffolds, plus the related eonium.config.json pointers. Existing user-authored files are preserved by default, and package installation alone does not mutate the repo.

After setup, upload these items to ChatGPT, Codex, Claude or another external AI workflow:

- the fresh target Flutter repo ZIP after Eonium setup
- the FlutterFlow export ZIP
- optional backend repo or backend Sherpa snapshot
- optional screenshots or visual references

Ask the AI to read .eonium/compass/ff_migrator/LLMsherpa.md first, then populate FE Sherpa with long-lived frontend truth, Business Sherpa with durable domain/workflow truth, and FF Migrator with FlutterFlow-specific source analysis, prompt/graph state and migration logs. Do not put FlutterFlow source-code archaeology or migration tactics inside FE Sherpa.

Repo-local agents should follow the same rule: start from the active FF Migrator graph objective, check FE Sherpa and Business Sherpa for existing truth, complete only the active step, preserve existing files completely, and update logs when behaviour, architecture, graph status or important project knowledge changes.

Eonium does not call ChatGPT, Claude, Codex, OpenAI, Anthropic or any other AI provider. It does not require BYOK setup, does not parse FlutterFlow exports, and does not automatically convert FlutterFlow apps to Flutter. It provides the repo-local instructions, prompt packs, scaffolds, graph files, logs and validation notes that make external AI migration sessions bounded and repeatable.

See the full guide at docs/flutterflow-to-flutter-migration.md.

Packaging check

The root package includes built dist output for the public subpaths and can be checked with:

npm run pack:root
npm run pack:all
npm run pack:check

npm run pack:check is the supported release-readiness pack entrypoint and is included in npm run verify. It runs npm pack --dry-run for the root package and npm pack --dry-run --workspaces for workspace package inspection. The MVP consumer path remains the root eonium package with subpath exports.

Changelog workflow

Sherpa changelog entries live under:

.eonium/compass/sherpa/backend/changelog/entries/

Validate Sherpa state and derive the latest commit message with:

npm run sherpa:validate
npm run sherpa:commit-message

npm run sherpa:validate is the supported repo-local validation entrypoint; it validates changelog sidecars and the built CLI Sherpa protocol path. Use npm run sherpa:changelog:validate only when isolating changelog issues.

The repo-local helper can also commit with the latest entry title when that workflow is desired:

npm run sherpa:commit

Config-driven setup flow

[email protected] adds the explicit setup-engine path for target repositories:

npm install eonium
npx eonium init --yes
# edit eonium.config.json
npx eonium setup --dry-run
npx eonium setup --yes

Package install is passive and does not mutate the target repo. eonium init creates or preserves the config/scaffold files. eonium setup reads the populated eonium.config.json and generates Eonium-managed DB, auth, HTTP and jobs integration surfaces using safe managed-file overwrite rules.