From b73030a4fb4aeddc8ec053f0236988849853dcae Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Mon, 21 Sep 2026 00:03:04 +0200 Subject: [PATCH] feat: add explicit format migration workflow --- AGENTS-TASKS.md | 18 ++++++++++-- README.md | 2 +- bin_efo/src/commands.rs | 1 + bin_efo/src/commands/migrate.rs | 48 +++++++++++++++++++++++++++++++ bin_efo/src/error.rs | 9 +++++- bin_efo/src/main.rs | 5 +++- bin_efo/tests/cli_workflows.rs | 44 ++++++++++++++++++++++++++++ docs/commands.md | 6 +++- docs/repository.md | 31 +++++++++++++++++--- docs/roadmap.md | 13 ++++----- lib_efo/src/epoch/epoch_config.rs | 27 ++++++++++------- lib_efo/src/error.rs | 8 ++++++ lib_efo/src/migration.rs | 9 +++++- 13 files changed, 193 insertions(+), 28 deletions(-) create mode 100644 bin_efo/src/commands/migrate.rs diff --git a/AGENTS-TASKS.md b/AGENTS-TASKS.md index e8fe2d0..fed572c 100644 --- a/AGENTS-TASKS.md +++ b/AGENTS-TASKS.md @@ -11,6 +11,11 @@ acceptance gates on 2026-09-20. gates on 2026-09-20. The Phase 4 format contract was approved on 2026-09-20; implementation is now proceeding through isolated compatibility checkpoints. +**Milestone 3 — safe format transition: complete.** On 2026-09-21, format +detection, legacy fixtures, read-only migration planning, validated conversion, +durable transient snapshots, and recoverable manifest backup passed default and +portable release gates. + ## Phase 0 — audit and guardrails - [x] Inventory workspace crates, commands, persistence files, CI, and tests. @@ -89,8 +94,17 @@ implementation is now proceeding through isolated compatibility checkpoints. histories, tags, future epochs, relationships, legacy `Monster` naming, and malformed input; materialise each case through the real legacy manifest and snapshot types. -- [ ] Implement only after the design preserves current data and allows every - ordinary mistake to be reversed without manual JSON editing. +- [x] Implement explicit `migrate --to 2` planning and confirmation with + read-only validation, monotonic ID allocation, complete transient snapshots, + a byte-for-byte manifest backup, and manifest-last commit semantics. +- [ ] Add transaction journaling, exclusive writer locks, deterministic + recovery, and automatic pre-commit migration rollback. +- [ ] Implement worktree/index-aware `status`, `diff`, `stage`, and both restore + directions without changing immutable epochs. +- [ ] Implement committed epochs, `log`, conflict-safe `revert`, and backed-up + `prune-future`; retire the destructive `reset` spelling through deprecation. +- [ ] Complete Phase 4 only after every ordinary mistake is reversible without + manual JSON editing and both default and portable release gates pass. ## Phase 5 — organisation-agnostic extensibility (upcoming release) diff --git a/README.md b/README.md index 188e50e..8c3e7ba 100644 --- a/README.md +++ b/README.md @@ -67,7 +67,7 @@ Run `efo --help`, `efo --help`, or see the | Area | Available now | Not available yet | |---|---|---| -| Repository | Initialise in the current directory; inspect status | Discovery from child directories; locking; migrations | +| Repository | Initialise; inspect status; preview/apply backed-up format migration | Discovery from child directories; locking; automated migration rollback | | Timeline | Advance, switch, log, tag, summarise, diff, check integrity, delete future epochs | Integrity repair; branching; atomic restore/revert | | Entities | Add, edit, list, inspect, diff, and delete six built-in types | Custom types and custom fields; bulk operations | | Generation | Generate character, town, event, calamity, blocker, and exotic names | Deterministic seed controls and template packs | diff --git a/bin_efo/src/commands.rs b/bin_efo/src/commands.rs index 48ac93a..26c1c20 100644 --- a/bin_efo/src/commands.rs +++ b/bin_efo/src/commands.rs @@ -12,6 +12,7 @@ pub mod entity_generic; pub mod epoch; pub mod generate; pub mod init; +pub mod migrate; // pub mod roll; pub mod show; pub mod status; diff --git a/bin_efo/src/commands/migrate.rs b/bin_efo/src/commands/migrate.rs new file mode 100644 index 0000000..eb2d004 --- /dev/null +++ b/bin_efo/src/commands/migrate.rs @@ -0,0 +1,48 @@ +//! Explicit repository-format migration command. + +use std::path::Path; + +use clap::Args; +use lib_efo::migration::{execute_migration, plan_migration}; + +use crate::error::AppError; + +/// Arguments accepted by `efo migrate`. +#[derive(Args, Debug)] +#[command( + after_long_help = "EXAMPLES:\n efo migrate --to 2 # validate and preview only\n efo migrate --to 2 --yes # create backup and migrate" +)] +pub struct MigrateCmd { + /// Repository format to migrate to (currently only 2). + #[arg(long, value_parser = clap::value_parser!(u32).range(2..=2))] + to: u32, + /// Apply the displayed plan; without this flag migration is a dry-run. + #[arg(long)] + yes: bool, +} + +/// Validate, preview, and optionally execute a repository migration. +pub fn migrate(command: &MigrateCmd) -> Result<(), AppError> { + let plan = plan_migration(Path::new("."))?; + println!("Migration plan · format 1 → {}", command.to); + println!("├─ Repository {}", plan.root().display()); + println!("├─ HEAD epoch {}", plan.current_epoch()); + println!("├─ History {} snapshot(s)", plan.epoch_count()); + println!("├─ Next ID {}", plan.next_epoch_id()); + println!("├─ Tags {}", plan.tags().len()); + println!("└─ Validation passed; no source snapshot will be rewritten"); + + if !command.yes { + println!(); + println!("Dry run only — nothing changed."); + println!("Run `efo migrate --to 2 --yes` to create a backup and apply this plan."); + return Ok(()); + } + + let outcome = execute_migration(&plan)?; + println!(); + println!("✓ Repository migrated to format 2."); + println!(" Backup: {}", outcome.backup_directory.display()); + println!(" Recovery: preserve `.efo/` and this backup until the first format-2 commit."); + Ok(()) +} diff --git a/bin_efo/src/error.rs b/bin_efo/src/error.rs index dfc063f..7168d0d 100644 --- a/bin_efo/src/error.rs +++ b/bin_efo/src/error.rs @@ -5,7 +5,10 @@ #![warn(missing_docs, clippy::missing_docs_in_private_items)] -use lib_efo::error::{EpochError, StorageError}; +use lib_efo::{ + error::{EpochError, StorageError}, + migration::MigrationError, +}; use miette::Diagnostic; use thiserror::Error; @@ -31,6 +34,10 @@ pub enum AppError { #[error("Storage error: {0}")] // #[diagnostic(transparent)] Storage(#[from] StorageError), + + /// Repository-format migration failed safely. + #[error("Migration stopped: {0}")] + Migration(#[from] MigrationError), // /// Anything else we didn't anticipate. // #[error("Unknown error: {0}")] // Other(String), diff --git a/bin_efo/src/main.rs b/bin_efo/src/main.rs index b5d796b..083358d 100644 --- a/bin_efo/src/main.rs +++ b/bin_efo/src/main.rs @@ -30,7 +30,7 @@ use clap::{Parser, Subcommand}; use crate::{ commands::{ entity_generic::EntitySubCommands, epoch::cli_epoch::EpochCmd, generate::GenCmd, - init::InitCmd, show::ShowCmd, status::StatusCmd, + init::InitCmd, migrate::MigrateCmd, show::ShowCmd, status::StatusCmd, }, error::AppError, }; @@ -66,6 +66,8 @@ struct Cli { enum TopLevelCmd { /// Initialise a new epoch folder. Init(InitCmd), + /// Preview or apply a repository-format migration. + Migrate(MigrateCmd), /// Gives a very simple status. Status(StatusCmd), /// Advance or query the current epoch. @@ -145,6 +147,7 @@ fn main() -> miette::Result<()> { fn exec_dispatch(cli: Cli) -> Result<(), AppError> { match cli.command { TopLevelCmd::Init(cmd) => commands::init::init(&cmd), + TopLevelCmd::Migrate(cmd) => commands::migrate::migrate(&cmd), TopLevelCmd::Epoch(cmd) => commands::epoch::handle_cmd(&cmd), TopLevelCmd::Show(cmd) => commands::show::handle_show_cmd(&cmd), TopLevelCmd::Gen(cmd) => commands::generate::gen_handler(&cmd), diff --git a/bin_efo/tests/cli_workflows.rs b/bin_efo/tests/cli_workflows.rs index 1e7e34b..10b4262 100644 --- a/bin_efo/tests/cli_workflows.rs +++ b/bin_efo/tests/cli_workflows.rs @@ -67,6 +67,7 @@ fn help_is_available_without_a_repository() { let text = stdout(&output); assert!(text.contains("Usage: efo ")); assert!(text.contains("epoch")); + assert!(text.contains("migrate")); assert!(text.contains("status")); } @@ -77,6 +78,7 @@ fn help_version_and_invalid_invocations_follow_cli_conventions() { &["epoch", "--help"][..], &["chr", "add", "--help"][..], &["show", "--help"][..], + &["migrate", "--help"][..], &["gen", "event", "--help"][..], ] { let output = efo(&repo, args); @@ -147,6 +149,48 @@ fn init_status_diff_and_fsck_workflow() { assert!(stdout(&fsck).contains("Repository is consistent (2 epoch(s) checked)")); } +#[test] +fn migration_is_dry_run_by_default_and_backs_up_before_commit() { + let repo = TestRepo::new(); + assert_success(&efo(&repo, &["init"])); + assert_success(&efo(&repo, &["chr", "add", "Aria"])); + let legacy_manifest = fs::read(repo.path().join(".epoch")).expect("legacy manifest"); + + let preview = efo(&repo, &["migrate", "--to", "2"]); + assert_success(&preview); + let preview_text = stdout(&preview); + assert!(preview_text.contains("Migration plan · format 1 → 2")); + assert!(preview_text.contains("Dry run only — nothing changed")); + assert_eq!( + fs::read(repo.path().join(".epoch")).expect("manifest after preview"), + legacy_manifest + ); + assert!(!repo.path().join(".efo").exists()); + + let applied = efo(&repo, &["migrate", "--to", "2", "--yes"]); + assert_success(&applied); + assert!(stdout(&applied).contains("Repository migrated to format 2")); + let manifest: serde_json::Value = + serde_json::from_slice(&fs::read(repo.path().join(".epoch")).expect("migrated manifest")) + .expect("parse migrated manifest"); + assert_eq!(manifest["format_version"], 2); + assert!(repo.path().join(".efo/index.json").is_file()); + assert!(repo.path().join(".efo/worktree.json").is_file()); + let backups = fs::read_dir(repo.path().join(".efo/migrations")) + .expect("migration backups") + .collect::, _>>() + .expect("list migration backups"); + assert_eq!(backups.len(), 1); + assert_eq!( + fs::read(backups[0].path().join(".epoch")).expect("backed-up manifest"), + legacy_manifest + ); + + let protected = efo(&repo, &["status"]); + assert!(!protected.status.success()); + assert!(stderr(&protected).contains("does not yet support repository format 2")); +} + #[test] fn init_force_preserves_unrelated_files_and_never_overwrites_a_repository() { let repo = TestRepo::new(); diff --git a/docs/commands.md b/docs/commands.md index febf446..5f8d18f 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -8,6 +8,10 @@ parent directories. `efo --help` is the authoritative syntax. - `efo init [--force]` creates `.epoch` and `epoch/0/epochinfo.json`. The normal form requires an empty directory; `--force` permits unrelated existing files but never overwrites `.epoch` or epoch 0. +- `efo migrate --to 2` validates and previews migration without writing. + Add `--yes` to create a byte-for-byte manifest backup and initialise the + version-2 index/worktree. This is an opt-in Phase 4 transition: ordinary + commands deliberately refuse format 2 until the staging checkpoint lands. - `efo status [EPOCH_ID]` shows an epoch summary, tags, and entity counts. - `efo epoch log [-c N]` shows epochs around the current epoch. - `efo epoch next` creates and checks out the next snapshot. It refuses while @@ -42,7 +46,7 @@ Common add/edit options include `--stats key:value ...`, `--position x,y`, options, and prestige controls. `edit --delta` adds supplied stats rather than replacing them. See nested help (for example `efo chr add --help`) for exact syntax and values. Mutations write the current epoch immediately; staging does -not exist yet. +not exist yet in format 1. `efo show all` lists every collection in the current epoch. `show character`, `show town`, `show event`, `show calamity`, and `show blocker` select one diff --git a/docs/repository.md b/docs/repository.md index baabd90..113029f 100644 --- a/docs/repository.md +++ b/docs/repository.md @@ -46,7 +46,30 @@ read-only `efo epoch fsck`. Restore from a known-good backup; `fsck` deliberatel does not repair or discard data. The config records a writer version, but automatic migrations and unknown-field -retention are not implemented. The intended compatibility policy is that newer -supported binaries migrate without data loss, format changes provide preview -and backup, and future custom fields survive round trips. Current work is -tracked in [the roadmap](roadmap.md). +retention are not implemented. Format-2 migration is explicit and preview-only +unless confirmed: + +```bash +efo migrate --to 2 +efo migrate --to 2 --yes +``` + +Migration validates every epoch before writing, preserves epoch IDs and future +history, creates complete `.efo/index.json` and `.efo/worktree.json` snapshots, +and commits the versioned `.epoch` manifest last. The original manifest and its +FNV-1a integrity checksum are stored under `.efo/migrations/`. + +Format 2 is currently an implementation preview. Other commands refuse it so +they cannot accidentally write version-1 semantics over staged state. Until the +first format-2 commit is supported, roll back by preserving the generated +workspace and restoring the manifest: + +```bash +mv .efo .efo-format2-backup +cp .efo-format2-backup/migrations/v1-*/.epoch .epoch +efo epoch fsck +``` + +The wildcard must identify exactly one migration directory. Do not overwrite a +newer `.epoch`; copy the whole repository before manual recovery. Current work +is tracked in [the roadmap](roadmap.md). diff --git a/docs/roadmap.md b/docs/roadmap.md index 2015cec..eef5a3c 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -22,13 +22,12 @@ consistent, organisations are managed directly, help includes examples, Nerd Font output has a portable build option, relationships are type-validated, and every mutation has documented and tested recovery guidance. -The next milestone is the reviewed repository-format design for working state, -pseudo-staging, restore, and revert. Implementation begins only after those -compatibility and crash-consistency decisions in the -[Phase 4 proposal](staging-design.md) are approved. Implementation then proceeds -through migration fixtures, transactions and locking, staging, and reversible -history. Organisation-agnostic custom fields and types follow, with migrations -and unknown-field retention designed first. +The [Phase 4 format contract](staging-design.md) is approved. Versioned format +types, legacy fixtures, validation, dry-run migration, durable transient-state +creation, and byte-for-byte manifest backup are implemented. Format 2 remains +opt-in and ordinary commands refuse it until transaction locking and staging +land. Organisation-agnostic custom fields and types follow reversible history, +with unknown-field retention designed before that format change. ## Proposed stretch goals diff --git a/lib_efo/src/epoch/epoch_config.rs b/lib_efo/src/epoch/epoch_config.rs index 26c9725..a397b07 100644 --- a/lib_efo/src/epoch/epoch_config.rs +++ b/lib_efo/src/epoch/epoch_config.rs @@ -77,16 +77,23 @@ impl EpochConfig { if path.is_file() { // TODO(6): write a trait for this - let config: EpochConfig = serde_json::from_str(&io_err_with_help!( - read_to_string(path), - "Reading config from path {:?}", - path - )?) - .map_err(|e| EpochError::Serde { - source: e, - file_name: path.to_string_lossy().to_string(), - version: format!("Current version: {}", env!("EFO_SHORT_VERSION")), - })?; + let contents = + io_err_with_help!(read_to_string(path), "Reading config from path {:?}", path)?; + let value: serde_json::Value = + serde_json::from_str(&contents).map_err(|e| EpochError::Serde { + source: e, + file_name: path.to_string_lossy().to_string(), + version: format!("Current version: {}", env!("EFO_SHORT_VERSION")), + })?; + if value.get("format_version").and_then(|v| v.as_u64()) == Some(2) { + return Err(EpochError::FormatTwoCommandPending); + } + let config: EpochConfig = + serde_json::from_value(value).map_err(|e| EpochError::Serde { + source: e, + file_name: path.to_string_lossy().to_string(), + version: format!("Current version: {}", env!("EFO_SHORT_VERSION")), + })?; Ok(config.initialize()?) } else { Err(EpochError::MainFolderInvalid( diff --git a/lib_efo/src/error.rs b/lib_efo/src/error.rs index 921827a..f6421cc 100644 --- a/lib_efo/src/error.rs +++ b/lib_efo/src/error.rs @@ -54,6 +54,14 @@ pub enum StorageError { // TODO(2): Split effectively user errors to avoid the usage of advice and such #[derive(Error, Debug, Diagnostic)] pub enum EpochError { + /// A format-2 repository was opened by a legacy command path. + #[error("This command does not yet support repository format 2")] + #[diagnostic(code(EpochError::FormatTwoCommandPending))] + #[diagnostic(help( + "Your data is intact. Use `efo migrate --to 2` to inspect the repository; staging commands arrive in the next checkpoint." + ))] + FormatTwoCommandPending, + /// Problems with the `.epochconfig` file. #[error("Failed to read epoch configuration")] #[diagnostic(code(EpochError::ConfigRead))] diff --git a/lib_efo/src/migration.rs b/lib_efo/src/migration.rs index 221b14a..8c41a68 100644 --- a/lib_efo/src/migration.rs +++ b/lib_efo/src/migration.rs @@ -160,6 +160,13 @@ pub fn plan_migration(root: &Path) -> Result { ))); } validate_entities(id, &snapshot)?; + for tag in snapshot.tags.iter() { + if legacy.tags.get(tag) != Some(&id) { + return Err(MigrationError::Invalid(format!( + "tag `{tag}` in epoch {id} is inconsistent with .epoch" + ))); + } + } epoch_ids.push(id); snapshots.insert(id, snapshot); } @@ -257,7 +264,7 @@ fn prepare_workspace( repository_id, plan.legacy.epoch_id, plan.next_epoch_id, - plan.legacy.version.clone(), + env!("EFO_SHORT_VERSION").to_owned(), plan.legacy.tags.clone(), )) }