feat(config): add explicit configuration schema migrations

[ajulaybeeb]

Summary

• Implement structured, versioned schema migrations for StarForge configuration files (~/.starforge/config.toml)
• Replace ad-hoc string matching with a step-based migration registry (ConfigMigrationStep and MIGRATION_STEPS) that applies sequential schema upgrades in ascending order
• Introduce structured error handling (ConfigMigrationError) and execution auditing (MigrationReport)
• Enforce pre-migration timestamped backups (config.backup.v<version>.<timestamp>.toml) that abort safely prior to applying migration steps if backup writing fails
• Create integration test suite (tests/config_migrations.rs) and update README.md and DEVELOPER_GUIDE.md with schema migration documentation

Why

Issue #660 requires older configuration files to be upgraded predictably with automatic backups and actionable error messages. Previously, migrate_config performed flat match logic on string versions without a formal step registry, structured error types, execution reports, or comprehensive automated tests for edge cases (such as future config versions written by newer binaries or corrupted version strings).

Implementation

src/utils/config.rs

• CURRENT_CONFIG_VERSION: Const ("1") specifying the latest supported schema version
• ConfigMigrationError: Enum providing actionable error variants:
  • FromFuture { found, latest }: Instructs user to upgrade starforge when attempting to load a config from a newer binary
  • UnknownVersion { found }: Reports unrecognised/corrupted schema version strings
  • StepFailed { from, to, reason }: Reports failures during step execution
  • BackupFailed { version, reason }: Reports backup file I/O failures
• MigrationReport: Struct recording from_version, to_version, steps_applied list, and backup_path
• MIGRATION_STEPS: Registry of ConfigMigrationStep entries defining sequential version transforms (e.g. v0 → v1)
• run_config_migrations(): Primary entry point that validates version hierarchy, writes a pre-migration backup, executes step sequences in order, and returns (Config, MigrationReport)
• migrate_config(): Preserved as a backward-compatible wrapper returning Result<Config>

tests/config_migrations.rs (new, 8 tests)

• test_migration_from_empty_version_to_v1: Primary flow verifying v0 → v1 migration step execution
• test_migration_from_explicit_v0_to_v1: Normalizing explicit "0" version string
• test_migration_already_current_is_noop: Verifying already-current config executes no steps and writes no backup
• test_migrate_config_convenience_wrapper: Exercising high-level migrate_config helper
• test_migration_backup_path_encodes_source_version: Validating backup path naming structure
• test_migration_from_future_version_errors: Failure path confirming FromFuture error with upgrade instructions
• test_migration_unknown_version_errors: Failure path confirming UnknownVersion error for invalid version strings
• test_migration_non_numeric_version_not_silently_upgraded: Failure path ensuring non-numeric string versions are rejected

Documentation

• README.md: Added Configuration schema migrations section detailing migration pipeline, timestamped backups, recovery steps, error resolution matrix, and developer instructions for adding schema versions
• DEVELOPER_GUIDE.md: Added architecture overview, backup policy, step addition workflow, and test execution instructions

Testing

Ran automated integration suite:

cargo test --test config_migrations
running 8 tests
test test_migration_already_current_is_noop ... ok
test test_migration_backup_path_encodes_source_version ... ok
test test_migration_from_future_version_errors ... ok
test test_migration_from_explicit_v0_to_v1 ... ok
test test_migration_from_empty_version_to_v1 ... ok
test test_migration_non_numeric_version_not_silently_upgraded ... ok
test test_migrate_config_convenience_wrapper ... ok
test test_migration_unknown_version_errors ... ok
test result: ok. 8 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.01s
Scope / Risk
Risk: Low — configuration schema migrations are opt-in when loading non-current configs; pre-migration backups prevent data loss if any failure occurs
Breaking change: None — migrate_config() signature and behaviour remain fully backward-compatible with existing callers
Affected area: src/utils/config.rs, tests/config_migrations.rs, README.md, DEVELOPER_GUIDE.md
Issue
Closes #660

[drips-wave]

@ajulaybeeb Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[Manuelshub]

@ajulaybeeb Please make sure to fix CI issues, very important!!!