Support reversible migrations: target schema, missing-down error, docs and tests

[mcmatan]

Motivation

• Enable safe rollbacks when switching app versions by allowing migrations to downgrade the DB schema instead of only failing when stored schema is newer.
• Surface a clear error when a required down handler is missing so startup does not hang or silently corrupt data.
• Ensure team guidance and automated coverage exist so future migrations always include a down and behavior is verified.

Description

• Added a targetVersion parameter to runMigrations and implemented downgrade logic that applies down handlers in reverse order when storedVersion > targetVersion, updating the stored version after each rollback (apps/desktop/src/main/store/migrations/index.ts).
• Introduced MissingDownMigrationError to represent missing down handlers and re-exported it from the migrations module (apps/desktop/src/main/store/migrations/errors.ts).
• Added a down implementation for the initial migration (v001) to provide a rollback path for legacy installs (apps/desktop/src/main/store/migrations/v001-initial.ts).
• Surface the new error to users by catching MissingDownMigrationError in the Electron bootstrap and showing a user-facing dialog titled Downgrade Not Supported before quitting (apps/desktop/src/main/index.ts).
• Updated contributor guidance (CLAUDE.md) to mandate down handlers in new migration templates and call out adding down handlers for legacy migrations when enabling downgrade support.
• Added unit tests with a fake DB harness that exercise forward migration, downgrade, and re-upgrade flows, and detection of unknown/newer schemas (apps/desktop/__tests__/unit/main/store/migrations.unit.test.ts).

Testing

• Ran the targeted unit tests: pnpm -F @accomplish/desktop test:unit -- __tests__/unit/main/store/migrations.unit.test.ts, which exercised forward upgrade, downgrade, re-upgrade, and the unknown-schema (FutureSchemaError) case; these tests passed.
• Ran the desktop unit suite during iteration; unit tests completed successfully (all unit tests passed in the run observed).

---

Codex Task

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e4f956b329

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Keep schema_meta until version is written

When downgrading to a pre-v001 target (e.g., targetVersion = 0), runMigrations always executes migration.down and then calls setStoredVersion inside the same transaction. Dropping schema_meta here means the subsequent setStoredVersion insert fails, causing the rollback to throw MigrationError and leaving the database half-torn-down. This only occurs during v001 rollbacks, but it makes the new downgrade path unusable for that case. Consider deferring the schema_meta drop or skipping setStoredVersion when rolling back to 0.

Useful? React with 👍 / 👎.