Add database schema versioning and migrations

[wksantiago]

Summary

• Add METADATA_TABLE for tracking schema version
• Create migration framework with forward migration support
• Integrate migrations into vault create/unlock flow
• Add keep migrate and keep migrate status commands

Test plan

• Unit tests for migration module (5 tests)
• Integration tests for schema versioning (3 tests)
• All 82 existing tests pass

Summary by CodeRabbit

• New Features

  • Added a top-level migrate command with an optional status subcommand; supports regular and hidden-volume flows with prompts, clear messaging, migration spinner, and a migration summary.
  • CLI can show current vs. latest schema version and whether migrations are needed.

• Security Improvements

  • Argon2 parameter validation rejects out-of-range values during storage header parsing.

• Tests

  • Integration tests for schema versioning, migration status, and data persistence after reopen.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Adds a migration system in keep-core (schema versioning, migration runners, compatibility checks), surfaces migration APIs through Storage/Backend, extends error types, and adds CLI commands to run/report migrations (including hidden-volume handling) with tests and Argon2 parameter validations.

Changes

Cohort / File(s)	Summary
Migration module keep-core/src/migration.rs, keep-core/src/lib.rs	New migration subsystem: CURRENT_SCHEMA_VERSION, Migration/MigrationResult, read/write/init schema, run_migrations, check_compatibility, needs_migration, and tests.
Backend & Storage keep-core/src/backend.rs, keep-core/src/storage.rs, keep-core/src/error.rs	Extended StorageBackend trait with schema_version / needs_migration / run_migrations (defaults); RedbBackend implements and invokes initialization/compatibility/migration on open. Storage API forwards schema/migration methods; Argon2 param bounds/validation added; delete_key/delete_share now return KeyNotFound when appropriate; new KeepError::Migration(String).
CLI migrate commands keep-cli/src/commands/migrate.rs, keep-cli/src/commands/mod.rs, keep-cli/src/main.rs	New migrate CLI and Status subcommand; public cmd_migrate / cmd_migrate_status added with hidden: bool. Hidden-volume flows and messaging implemented; dispatch_migrate wired into CLI.
Integration tests / test helpers keep-core/tests/integration_tests.rs	Added tests asserting initial schema version, migration status, and data persistence after reopen; test helpers updated to import Storage.

Sequence Diagram(s)

sequenceDiagram
  participant CLI as CLI (keep-cli)
  participant Storage as Storage API
  participant Backend as RedbBackend
  participant DB as Redb Database

  CLI->>Storage: cmd_migrate(path, hidden)
  alt hidden == false
    Storage->>Backend: open(path)
    Backend->>DB: open DB / initialize_schema()
    DB-->>Backend: DB handle
    Backend->>Backend: check_compatibility()
    Backend->>Backend: needs_migration()
    alt migrations needed
      Backend->>Backend: run_migrations()
      Backend->>DB: apply migration steps
      DB-->>Backend: updated schema version
      Backend->>Storage: return MigrationResult
    else no migrations
      Backend->>Storage: return MigrationResult (no-op)
    end
    Storage->>CLI: print result/status
  else hidden == true
    CLI->>Storage: open hidden storage
    Storage->>Storage: unlock hidden volume (prompt)
    Storage->>CLI: report hidden-volume status (migrations not run)
  end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• Add StorageBackend trait abstraction #134: Modifies StorageBackend/RedbBackend and aligns with the added migration lifecycle methods and implementations.
• Add audit logging for signing operations #126: Refactors KeepError; touches the same error enum where Migration(String) was introduced.
• feat: Hidden Volume #1: Adds/changes hidden-volume handling used by the migrate CLI flows.

Poem

🐰 I nibble at schemas, hopping through lines,
I bump up versions and polish the signs.
Migrations hum gently, data stays bright,
A carrot for tests, and all runs right! 🥕✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Add database schema versioning and migrations' directly and concisely summarizes the main change: introducing schema versioning and migration infrastructure. It matches the core objectives and file changes throughout the PR.
Docstring Coverage	✅ Passed	Docstring coverage is 88.89% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@keep-cli/src/main.rs`:
- Around line 543-555: The migrate path never receives the parsed hidden flag;
update the signature of dispatch_migrate to accept a hidden: bool and thread
that flag from the caller where Commands::Migrate is matched, then update
dispatch_migrate to forward hidden into commands::migrate::cmd_migrate and
cmd_migrate_status; inside those functions change the vault-opening logic to
follow the vault.rs/audit.rs pattern: if hidden use HiddenStorage and call
get_hidden_password(), otherwise use the standard storage and get_password(),
ensuring the correct store/password are used when hidden=true.