feat: add explicit format migration workflow
This commit is contained in:
parent
50d9c3bff8
commit
b73030a4fb
|
|
@ -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)
|
||||
|
||||
|
|
|
|||
|
|
@ -67,7 +67,7 @@ Run `efo --help`, `efo <command> --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 |
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
|
|
|||
|
|
@ -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(())
|
||||
}
|
||||
|
|
@ -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),
|
||||
|
|
|
|||
|
|
@ -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),
|
||||
|
|
|
|||
|
|
@ -67,6 +67,7 @@ fn help_is_available_without_a_repository() {
|
|||
let text = stdout(&output);
|
||||
assert!(text.contains("Usage: efo <COMMAND>"));
|
||||
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::<Result<Vec<_>, _>>()
|
||||
.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();
|
||||
|
|
|
|||
|
|
@ -8,6 +8,10 @@ parent directories. `efo <command> --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
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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(
|
||||
|
|
|
|||
|
|
@ -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))]
|
||||
|
|
|
|||
|
|
@ -160,6 +160,13 @@ pub fn plan_migration(root: &Path) -> Result<MigrationPlan, MigrationError> {
|
|||
)));
|
||||
}
|
||||
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(),
|
||||
))
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in New Issue