migrate-essencium-frontend

Essencium Frontend Migration Skill

You are performing an interactive, version-by-version migration of a downstream project that is based on essencium-frontend. This is a collaborative process -- be patient, explain what you are doing, and always wait for developer confirmation before making destructive or ambiguous changes.

Important references

Before you begin, be aware of two reference documents bundled with this skill:

• ./references/categories.md -- Detailed handling instructions for each of the 7 change categories. You MUST read this file during the APPLY phase (step 2c).
• ./references/manifest-format.md -- The YAML schema for migration manifests. Read this file if you need to understand the structure of a manifest entry.

The upstream essencium-frontend repository is at: https://github.com/Frachtwerk/essencium-frontend Git tags follow the pattern: essencium-app-v<version> (e.g., essencium-app-v9.4.5).

Migration manifests are fetched directly from the essencium-frontend GitHub repository at runtime. They are not bundled with this plugin — this means new manifests are available immediately when essencium-frontend publishes a release, without requiring a plugin update.

• List available manifests: https://api.github.com/repos/Frachtwerk/essencium-frontend/contents/packages/app/manifests
• Fetch a specific manifest: https://raw.githubusercontent.com/Frachtwerk/essencium-frontend/main/packages/app/manifests/<version>.yaml

GitHub API usage

This skill fetches manifests and upstream files from GitHub. Use the correct URL pattern for each case — using the wrong one is a common source of errors:

Purpose	Correct URL	Do NOT use
List available manifests	https://api.github.com/repos/Frachtwerk/essencium-frontend/contents/packages/app/manifests	—
Fetch a manifest YAML	https://raw.githubusercontent.com/Frachtwerk/essencium-frontend/main/packages/app/manifests/<version>.yaml	gh api repos/.../contents/... (returns base64 JSON, not raw content)
Fetch a source file at a tag	https://raw.githubusercontent.com/Frachtwerk/essencium-frontend/essencium-app-v<version>/packages/app/<path>	gh api for raw file content

Always use raw.githubusercontent.com for file content. gh api repos/.../contents/... returns a JSON envelope with base64-encoded content — it is not a substitute for raw file fetching and requires extra decoding.

Unauthenticated requests are limited to 60/hour. For multi-version migrations, if the user has a GITHUB_TOKEN environment variable set, use it in WebFetch headers (Authorization: token <value>) to increase the rate limit to 5000/hour. If rate limiting is encountered, suggest the developer set a GITHUB_TOKEN.

---

Step 0: PRE-FLIGHT

Before starting the migration, establish baselines and verify the environment is ready.

1. Clean git state. Run git status. If there are uncommitted changes, ask the developer to commit or stash them before proceeding. The migration must start from a clean working tree so that git history accurately reflects migration work.

2. Baseline type check. Run the project's type-check command (typically npx tsc --noEmit or pnpm typecheck). Record whether it passes or fails, and how many errors exist. This baseline is critical: during verification, only errors that are NEW compared to this baseline are attributed to the migration. Pre-existing errors are ignored.

3. Baseline test run. Run the project's test command. Record pass/fail counts. Same rationale: pre-existing failures are not migration failures.

4. Manifest pre-checks. After loading each manifest (step 2a), if it contains a pre_checks array, execute each check before applying any changes for that version. If any check with severity: blocker fails, stop and help the developer resolve it before proceeding.

---

Step 1: DETECT

Determine the current state of the downstream project and calculate the migration path.

1. Read the downstream project's package.json to find the currently installed versions of @frachtwerk/essencium-lib and @frachtwerk/essencium-types. These tell you the current essencium version the project is based on.

2. Determine the target version. If the developer passed a target version as $ARGUMENTS, use that. Otherwise, default to the latest (highest) version available from the manifest listing.

3. List all available manifest files by fetching the GitHub API:

   https://api.github.com/repos/Frachtwerk/essencium-frontend/contents/packages/app/manifests
   

   Parse the version number from each filename in the response (e.g., 9.4.5.yaml means version 9.4.5). Sort them in ascending semver order.

4. Calculate the migration path. Starting from the current version, collect every manifest version that is greater than the current version and less than or equal to the target version. These are the steps to execute, in ascending order. Each manifest's from field tells you which version it migrates from -- use this to verify the chain is valid.

   Not all versions have manifests. Manifests are only created for releases that contain app-level changes relevant to downstream projects. Patch releases that only touch library internals or docs will not have a manifest. This is by design — the migration path only includes versions with actual migration steps.

   • Only include versions that have a corresponding manifest YAML file.
   • If the downstream project's current version has no manifest (e.g., downstream is at 9.4.2 but the nearest manifests are 9.4.0 and 9.4.4), find the next available manifest whose version is greater than the current version. Apply it as the first step. The from field in that manifest indicates the intended baseline, not a hard requirement — patch versions between manifests typically don't introduce breaking changes that would invalidate the manifest.
   • If the downstream project's current version is older than the oldest available manifest, warn the developer that migration manifests only cover versions from 6.0.0 onward.

5. Present the migration path to the developer and ask for confirmation before proceeding:

   Current: @frachtwerk/[email protected]
   Target: 9.5.0
   Migration path: 9.4.4 -> 9.4.5 -> 9.5.0
   (Only versions with migration manifests are shown. Your version 9.4.2 has no manifest — starting from the next available: 9.4.4)
   
   Proceed? (y/n)
   

6. If the developer declines, stop. If they confirm, proceed to step 2.

---

Step 2: Execute migration steps (version by version)

For each version in the migration path, execute these sub-steps in order. Do NOT skip ahead to the next version until the current one passes verification.

Step 2a: LOAD manifest

1. Fetch the manifest YAML file for this version step from GitHub:

   https://raw.githubusercontent.com/Frachtwerk/essencium-frontend/main/packages/app/manifests/<version>.yaml
   

2. Parse the manifest and group the changes by their type field. The 7 types are:
   • dependency_migration
   • infrastructure
   • file_removal
   • new_file
   • file_tracking
   • translation
   • env_variable
3. Read the ./references/categories.md file to understand the handling instructions for each category.

Step 2b: PLAN

For each change entry in the manifest, assess its impact on the downstream project:

1. For dependency_migration entries:

   • Check if the dependency exists in the downstream package.json.
   • If scope: project_wide: use Grep to scan the entire downstream project for imports and usage of the affected package. Note how many files use it and whether the usage matches patterns that would need updating.
   • If scope: package: note that this is a simple version bump.

2. For file_tracking entries:

   • Check if the file exists in the downstream project.
   • If the file exists, detect whether the downstream project customized it:
     • Fetch the file from the essencium-frontend GitHub repo at the from version tag using WebFetch:

       https://raw.githubusercontent.com/Frachtwerk/essencium-frontend/essencium-app-v<from-version>/packages/app/<path>
       

     • Compare the fetched upstream baseline with the downstream file content.
     • If they are identical, the file is untouched (can be auto-applied).
     • If they differ, the file is customized (requires interactive merge).
   • If the file does not exist, note that the downstream project deleted it.

3. For new_file entries:

   • Check if the downstream project already has a file at that path.
   • Search for files with similar names or functionality elsewhere in the downstream project.

4. For file_removal entries:

   • Check if the file exists in the downstream project.
   • If it exists, use Grep to search for imports and references to this file across the project.

5. For translation entries:

   • Check if the locale files exist in the downstream project.
   • Note which keys are added, changed, or removed.

6. For env_variable entries:

   • Check all .env* files in the downstream project root for existing variables.

7. For infrastructure entries:

   • Check if the config files exist in the downstream project.
   • Check for unexpected customizations.

Present a summary of the plan to the developer:

Version 9.4.5 migration plan:
- [dependency] axios 1.8.2 -> 1.12.0: package bump only
- [dependency] vite 6.2.7 -> 6.3.6: package bump only
- [file_tracking] src/app/.../RightsView.tsx: customized (2 extra functions) -- INTERACTIVE
- [translation] 1 key to add to de/en locale files -- AUTO

Ask the developer to confirm the plan before applying changes.

Step 2c: APPLY

Before applying, read ./references/categories.md for the detailed handling procedures. Follow those instructions precisely.

Process changes in this exact order (dependencies first, then structural, then content):

0. Bump essencium packages

Before processing other changes, update @frachtwerk/essencium-lib and @frachtwerk/essencium-types in the downstream project's package.json to match this version step's target version. Run the package manager install command to fetch the updated packages. This ensures the downstream project has the correct lib/types for this version before applying other changes.

1. dependency_migration

• scope: package: Auto-apply. Update the version in the downstream package.json.
• scope: project_wide: Interactive.
  1. Bump the version in package.json.
  2. Fetch the reference URL from the manifest entry using WebFetch (if available). Otherwise, rely on your knowledge of that library's migration guide.
  3. Use Grep to scan the entire downstream project for usage patterns of the old API.
  4. Process ALL matches in a single pass. Do NOT split work across parallel sub-agents — sequential processing of a single grep result set ensures no files are overlooked. If there are more than 50 files to transform, generate a codemod script instead of editing files individually (see "Batch operations" below).
  5. For each file with old usage, read the file, transform the code to the new API, and present the change to the developer for review before applying.
  6. After all transformations, run the package manager install command.
  7. Test infrastructure. After transforming application code, scan the test infrastructure for references to the old dependency:
     • Check test setup files (setupTests.*, vitest.setup.*, jest.setup.*, or equivalent) for global mocks or configuration of the migrated library.
     • Scan test files (**/*.test.*, **/*.spec.*) for local mocks of the migrated package (e.g., vi.mock('<old-package>'), jest.mock('<old-package>')).
     • Transform these files using the same migration guide.
     • If the manifest entry includes a test_infrastructure field, use its files and patterns as the starting point for this scan.
     • Test infrastructure is NOT optional. Stale test mocks after a dependency migration cause cascading test failures that are difficult to diagnose.
  8. Verification checkpoint. Run the project's type-check command. Compare against the Step 0 baseline — only new errors are relevant. If new type errors appear, they indicate missed files; fix them before proceeding to the next change category. This checkpoint is mandatory for all scope: project_wide migrations.

2. infrastructure

• Read the downstream config files.
• Fetch the upstream diff via the PR link using WebFetch if a pr field is provided.
• Apply changes directly with a summary. If unexpected customizations are detected, flag for developer review instead.

3. file_removal

• For each file to be removed:
  • If the file does not exist: skip.
  • If it exists and has no references (confirmed via Grep): confirm deletion with the developer.
  • If it exists and has references: list all referencing files and flag for review. Help the developer resolve references before removing.
• Always confirm with the developer before deleting any file.

4. new_file

• For each new file:
  • If no file exists at that path: fetch the file content from the essencium-frontend repo at the target version tag:

    https://raw.githubusercontent.com/Frachtwerk/essencium-frontend/essencium-app-v<target-version>/packages/app/<path>
    

    Create it in the downstream project. Auto-apply.
  • If a file or equivalent already exists: flag for review and show a diff.

5. file_tracking

• For each tracked file change:
  • If the file does not exist in the downstream project: Flag it. Ask the developer whether the upstream change is relevant. Do not silently skip.
  • If the file exists and is untouched (matches the upstream baseline at the from version): auto-apply the upstream diff.
  • If the file exists and is customized (differs from upstream baseline): interactive merge. Show the developer what the upstream changed and how it interacts with their customizations. Let them decide how to merge.
  • If the change was already applied (e.g., by a dependency migration in step 1): skip and note it.
  • For file renames (entries with both an added and a removed path):
    • If the old file exists: rename it to the new path, then apply any content changes.
    • If the old file does not exist: create the new file as if it were a new_file entry.

6. translation

• For each locale:
  • Read the downstream locale JSON file (typically public/locales/<locale>/common.json).
  • keys_added: Add each key if it does not already exist. Fetch values from the essencium-frontend repo at the target version tag. Preserve all existing custom keys. Auto-apply.
  • keys_changed: Check if the downstream value matches the old upstream value. If so, update automatically. If the downstream has a custom value, flag for review.
  • keys_removed: Always flag for developer review. The downstream project may still use these keys.
  • Write the updated JSON, preserving key ordering and formatting.

7. env_variable

• For each variable:
  • Check all .env* files in the downstream project root.
  • If the variable already exists in any .env* file: skip.
  • If missing: add it to the primary .env file (or .env.local if that matches the project's pattern). Use the default value if specified in the manifest, otherwise add with a # TODO: set value comment.
  • Auto-apply with a summary.

Step 2d: VERIFY

After applying all changes for this version step:

1. Run the build command. Detect from the downstream package.json scripts -- typically npm run build or pnpm build. If using a monorepo, identify the correct workspace command.

2. Run the linter if available (npm run lint or pnpm lint).

3. Run tests if available (npm test or pnpm test).

4. If any command fails:

   • Stop and help the developer diagnose and fix the issue.
   • Re-run verification after fixes are applied.
   • Do NOT proceed to the next version step until all checks pass.

5. If all pass:

   • Ask the developer for confirmation before committing.
   • Commit the migration for this version step:
     • Run git status to review all changes
     • Stage only the files that were modified during this migration step. Do NOT use git add -A as it may stage sensitive files (.env.local, credentials) or unrelated work-in-progress
     • Confirm the staged files with the developer before committing
   • Only commit after the developer confirms.

Step 2e: Repeat

Move to the next version in the migration path and go back to step 2a. Continue until all versions have been migrated.

---

Step 3: COMPLETE

After all version steps have been successfully migrated:

1. Present a summary of everything that was done:

   • List each version step that was applied.
   • Summarize key changes per version (dependencies bumped, files modified, new files added, files removed, etc.).
   • Note any interactive decisions the developer made.

2. Remind the developer to take the following final actions:

   • Run a final build and test to confirm everything works end-to-end.
   • Review any # TODO comments that were added during the migration.

---

Edge cases and important notes

PR link handling

When a manifest entry includes a pr field (a GitHub PR URL), use WebFetch to fetch the PR diff page to understand what changed upstream. If WebFetch is unavailable or fails, fall back to the manifest entry's description and notes fields to understand the change.

Downstream deleted an upstream file

If a file_tracking entry references a file that does not exist in the downstream project, do NOT silently skip it. Flag it and ask the developer whether the upstream change is relevant to their project.

Downstream already applied a fix

If the change described in a manifest entry is already present in the downstream file (the code already matches the target state), skip it and note that it was already applied. Do not re-apply or flag as a conflict.

Dependency migration + file tracking overlap

When a dependency migration (step 2c.1) affects files that also appear in file_tracking entries (step 2c.5), the dependency migration scan may have already transformed those files. During file_tracking processing, check whether the relevant change was already applied before attempting to apply it again.

File renames

Some file_tracking entries contain both an added and a removed file path. This represents a rename. Handle by moving/renaming the old file to the new path, then applying any content changes from the upstream diff.

Batch operations (codemod-style)

When a dependency migration or file tracking change requires the same mechanical transformation across many files (more than 20), do NOT edit files one by one. Instead:

1. Identify the exact search pattern and its replacement.
2. Write a codemod script (Node.js or shell) that performs the transformation.
3. Present the script to the developer for review before running it.
4. Execute it once across all matching files.
5. Run the type-check command to verify.
6. Show a summary of files changed.

If the manifest entry includes a batch_hint field, use its pattern, replacement, and file_glob to generate the codemod script.

Prohibited operations during migration

• No git stash or git reset --hard. These risk losing all migration changes accumulated so far. To determine whether a failure is pre-existing, consult the baseline recorded in Step 0 rather than stashing or resetting.
• No sleep commands. Run commands synchronously. If a command is asynchronous by nature, use a proper wait mechanism, not a timed sleep.
• No git checkout -- <file> or git restore on migrated files. If a change needs to be undone, edit the file back explicitly so the developer can see exactly what was reversed.

Code generation guidelines

When generating or modifying code during the migration:

• Respect the module system. Before writing imports or exports, check what module system the target file uses — look at the file extension (.mjs, .cjs, .ts), the "type" field in the nearest package.json, and whether the project uses a bundler. Do not use require() in ESM files or import in CommonJS files.
• Preserve downstream conventions. Do not blindly copy upstream code into the downstream project. Check whether the downstream has local type overrides, its own utility functions, or different import paths for the same concepts, and preserve them.
• Check the Node.js version. Before using newer Node.js APIs (e.g., import.meta.dirname, available since Node 21.2.0), verify the Node.js version the downstream project targets. Use older equivalents (e.g., path.dirname(fileURLToPath(import.meta.url))) when compatibility requires it.

This is a collaborative process

This migration skill is designed to be interactive and patient. Always explain what you are about to do. Always wait for developer confirmation before making ambiguous or destructive changes. Present clear summaries and diffs. If the developer wants to skip a change or handle it differently, respect their decision and note it for the summary.