@eonium/compass-fe-sherpa

Compass Frontend Sherpa scaffold generator.

This package initializes the repo-local Frontend Sherpa documentation surface under .eonium/compass/sherpa/frontend/. Frontend Sherpa is the long-lived target frontend truth layer for architecture, routes, screens, components, state, API contracts, design system, visual language, assets, layout, accessibility, platform concerns, commands, decisions and changelog history.

What this package does

initFeSherpa generates purpose-clear documentation scaffolds for the target frontend. The generated files are intentionally mostly empty until a human or agent fills them with verified repo truth.

Generated files:

.eonium/compass/sherpa/frontend/LLMsherpa.md
.eonium/compass/sherpa/frontend/current-state.md
.eonium/compass/sherpa/frontend/architecture.md
.eonium/compass/sherpa/frontend/commands.md
.eonium/compass/sherpa/frontend/design-system.md
.eonium/compass/sherpa/frontend/route-map.md
.eonium/compass/sherpa/frontend/screen-map.md
.eonium/compass/sherpa/frontend/component-map.md
.eonium/compass/sherpa/frontend/state-management.md
.eonium/compass/sherpa/frontend/api-contracts.md
.eonium/compass/sherpa/frontend/naming-conventions.md
.eonium/compass/sherpa/frontend/decisions.md
.eonium/compass/sherpa/frontend/changelog.md

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 Frontend Sherpa files.
• Existing files are preserved by default.
• Already-current files are skipped.
• Existing files are updated only when force: true is supplied.
• The returned report distinguishes created, updated, skipped, warned and errored files.

Package boundary

This package creates Frontend Sherpa documentation scaffolds only.

It does not:

• parse FlutterFlow exports;
• inspect generated FlutterFlow source code;
• migrate FlutterFlow screens into Flutter code;
• generate app widgets, routes, state controllers or services;
• call AI providers or require BYOK configuration;
• own FF Migrator prompt packs, graph files, sprint plans, step plans or migration logs.

FlutterFlow source archaeology, porting tactics, old-to-new conversion notes, active sprint or step scope, and temporary migration prompts belong in .eonium/compass/ff_migrator/, not in Frontend Sherpa.

API

import { initFeSherpa } from "@eonium/compass-fe-sherpa";

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