# Omarchy upstream migration

The fuzzy launcher is a maintained fork of Omarchy's built-in `omarchy.menu`
plugin. Menu data and theme tokens are read from the installed Omarchy files at
runtime, so new commands, colors, fonts, and spacing tokens normally arrive
without a code migration. This workflow covers changes to the built-in plugin
implementation itself.

## Check after an Omarchy update

```bash
npm run upstream:check
```

The checker compares every file under
`/usr/share/omarchy/shell/plugins/menu/` with the hashes in
`upstream/upstream-lock.json`. It reports added, changed, and removed files and
does not modify anything.

## Migrate into the project

Start from a clean Git worktree, then run:

```bash
npm run upstream:migrate
```

For each upstream-owned file, the migrator uses:

- the pristine source saved in `upstream/omarchy-menu/` as the common base;
- the project file as our customized version;
- the currently installed Omarchy file as the new upstream version.

It builds the result in a temporary directory and runs the unit tests, search
benchmark, `qmllint`, and `omarchy plugin validate` there. The project and live
plugin are changed only after every check passes. A successful migration also
advances the pristine baseline and lock hashes, leaving a normal Git diff for
review and commit.

If edits overlap, the project and live plugin remain untouched. Conflict-marked
candidates and a report are written below `.upstream-migration/`, which is
ignored by Git.

## Migrate and activate

After checking that the live plugin still matches this project, the complete
validated workflow can deploy and restart the shell:

```bash
npm run upstream:migrate:live
```

The deploy variant refuses to overwrite a live plugin that has diverged from
the clean project. It validates the live copy before restarting the Omarchy
shell. If a migration needs manual conflict resolution, use the non-live
command, resolve and validate the project, then synchronize deliberately.

The same live command is available as **Update → Fuzzy Launcher** in the
launcher. A checkmark means the installed Omarchy menu matches the tracked
baseline. Selecting the entry opens a themed terminal so migration output or
conflict instructions remain visible.

## Safety properties

- `/usr/share/omarchy/` is always read-only.
- A dirty project worktree blocks migration.
- The tracked baseline is verified against its hashes before use.
- New and deleted upstream plugin files are detected, not just known files.
- Conflicts and validation failures never replace the working plugin.
- Live deployment is optional and occurs only after validation.
- Git remains the rollback mechanism for every accepted migration.