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 from the first four completed steps, and the MVP runtime/shell package surface needed for the Nexeo migration path.

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

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

• @eonium/create-project
• @eonium/compass-fe-sherpa
• @eonium/publisher
• @eonium/ff-migrator
• @eonium/db-synchroniser
• @eonium/db-tester

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.

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

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 runs the ordered build, typecheck/lint coverage, package self-tests, Sherpa changelog validation, and the built CLI Sherpa validation command.

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 sherpa:validate
npm run eonium -- sherpa validate

npm run build, npm run typecheck, npm run lint, and npm run test use tools/workspace-runner.mjs so the package order is deterministic and the Nexeo-compatible runtime dependencies are built before dependent packages.

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 -- init --dry-run
npm run eonium -- add any-db --dry-run
npm run eonium -- add be-http --dry-run

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
.\node_modules\.bin\eonium.cmd sherpa 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.

Packaging check

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

npm pack --dry-run

The pack:all script is retained for workspace package inspection, but the MVP consumer path is the root eonium package with subpath exports.

Changelog workflow

Sherpa changelog entries live under:

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

Validate entries and derive the latest commit message with:

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

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

npm run sherpa:commit