diff --git a/AGENTS-TASKS.md b/AGENTS-TASKS.md index 15d1aa5..86370d9 100644 --- a/AGENTS-TASKS.md +++ b/AGENTS-TASKS.md @@ -64,12 +64,12 @@ acceptance gates on 2026-09-20. Phase 3 is the next active milestone. - [x] Resolve naming inconsistencies (`chr`, calamity mapped to monster, missing organisation surface) with aliases/deprecation where compatibility warrants it. -- [ ] Improve all command help with examples and valid-value guidance. +- [x] Improve all command help with examples and valid-value guidance. - [x] Replace ambiguous success output and Nerd-Font-only semantics with clear, attractive Unicode output that degrades safely without colour. -- [ ] Ensure entity editing validates type-specific fields and reports useful +- [x] Ensure entity editing validates type-specific fields and reports useful recovery advice. -- [ ] Ensure every existing mutation has a documented and tested reversal via +- [x] Ensure every existing mutation has a documented and tested reversal via epoch switching/reset/restore or an explicit backup workflow. ## Phase 4 — Git-like reversible workflow diff --git a/README.md b/README.md index 06319e6..188e50e 100644 --- a/README.md +++ b/README.md @@ -81,6 +81,7 @@ Run `efo --help`, `efo --help`, or see the - [Documentation index](docs/README.md) - [Commands](docs/commands.md) - [Repository, persistence, and recovery](docs/repository.md) +- [Reversing changes](docs/recovery.md) - [Architecture and development](docs/architecture.md) - [Roadmap and proposed stretch goals](docs/roadmap.md) - [Contributor/agent rules](AGENTS.md) and [working task list](AGENTS-TASKS.md) diff --git a/bin_efo/src/commands/entity_generic.rs b/bin_efo/src/commands/entity_generic.rs index b46cd57..462317e 100644 --- a/bin_efo/src/commands/entity_generic.rs +++ b/bin_efo/src/commands/entity_generic.rs @@ -141,6 +141,9 @@ pub(crate) struct ShowArgs { /// Common arguments used for *add* and *edit* operations. #[derive(Args, Debug)] +#[command( + after_long_help = "EXAMPLES:\n efo chr add Aria --stats strength:12 food:8\n efo town add Durn --position 12,5\n efo org add \"Iron Council\" --capital Durn --governor Aria\n\nSTATS: demographics, population, growthrate, crime, happiness, economy, food, industry, science, trade, military, army, strength, fortification, threat, infrastructure, bureaucracy, transportation, sprawl, health" +)] pub struct AddArgs { /// The desired name of the new entity. If omitted a random /// name will be generated unless `--rng-name` is set. @@ -163,6 +166,9 @@ pub struct AddArgs { } #[derive(Args, Debug)] +#[command( + after_long_help = "EXAMPLES:\n efo chr edit Aria --stats strength:14\n efo chr edit Aria --delta --stats strength:2\n efo org edit \"Iron Council\" --capital Durn --governor Aria\n\nCreate an epoch with `efo epoch next` before risky edits so the previous snapshot remains available." +)] /// Arguments for modifying an existing entity. pub struct EditArgs { /// Identifier (name or `@tag`) of the entity to edit @@ -238,35 +244,39 @@ pub struct CommonArgs { pub no_capital: bool, /// Change the prestige - #[arg(long, group = "capital_group")] + #[arg(long, conflicts_with = "prestige_add")] pub prestige: Option, /// Change the prestige by a delta - #[arg(long, group = "capital_group", allow_negative_numbers = true)] + #[arg(long, conflicts_with = "prestige", allow_negative_numbers = true)] pub prestige_add: Option, } impl CommonArgs { /// Validate the parser usage fn validate(&self, e_type: &stats::EntityType) -> Result<(), EpochError> { - if (self.capital.is_some() || self.no_capital) && !matches!(e_type, stats::EntityType::Town) + if (self.capital.is_some() || self.no_capital) + && !matches!(e_type, stats::EntityType::Organization) { Err(EpochError::IncorrectArgumentCombinaison { category: "Capital", e_type: *e_type, advice: Some( - "Capitals are reserved to town, maybe you used the wrong subcommand?" + "Only organisations can own a capital. Use `efo org edit ... --capital `." .to_string(), ), }) } else if (self.governor.is_some() || self.no_governor) - && !matches!(e_type, stats::EntityType::Town) + && !matches!( + e_type, + stats::EntityType::Town | stats::EntityType::Organization + ) { Err(EpochError::IncorrectArgumentCombinaison { category: "Governor", e_type: *e_type, advice: Some( - "Governors are reserved to towns, maybe you used the wrong subcommand?" + "Governors can lead towns or organisations. Use the `town` or `org` command." .to_owned(), ), }) diff --git a/bin_efo/src/commands/epoch/cli_epoch.rs b/bin_efo/src/commands/epoch/cli_epoch.rs index 033f034..b4a1ab9 100644 --- a/bin_efo/src/commands/epoch/cli_epoch.rs +++ b/bin_efo/src/commands/epoch/cli_epoch.rs @@ -33,7 +33,7 @@ pub enum EpochCmd { /// Compute the next epoch from the current one Next(Next), - /// Delete *all* future events after the current epoch + /// Delete all future epochs after the current epoch (irreversible) Reset(Reset), /// Show the differences between two epochs @@ -82,8 +82,11 @@ pub struct Switch { #[derive(Args, Debug)] pub struct Next; -/// Deletes all future events after the current epoch. +/// Deletes all future epochs after the current epoch. #[derive(Args, Debug)] +#[command( + after_long_help = "WARNING: This permanently removes later epoch directories.\n\nRECOVERY WORKFLOW:\n efo epoch switch \n efo status\n # Back up the repository, then:\n efo epoch reset" +)] pub struct Reset; /// Shows the differences between two epochs. diff --git a/bin_efo/src/main.rs b/bin_efo/src/main.rs index 842b6ad..b5d796b 100644 --- a/bin_efo/src/main.rs +++ b/bin_efo/src/main.rs @@ -46,6 +46,9 @@ mod success; #[command(version = env!("EFO_SHORT_VERSION"))] #[command(name = "efo")] #[command(about = "Epoch Forge - manage organisations over time")] +#[command( + after_long_help = "EXAMPLES:\n efo init\n efo org add \"Iron Council\"\n efo chr add Aria --stats strength:12\n efo epoch next\n efo status\n\nRun `efo --help` for command-specific examples." +)] struct Cli { // /// The level of verbosity // #[arg(short, long, action = ArgAction::Count, global = true)] diff --git a/bin_efo/tests/cli_workflows.rs b/bin_efo/tests/cli_workflows.rs index 10741a9..1e7e34b 100644 --- a/bin_efo/tests/cli_workflows.rs +++ b/bin_efo/tests/cli_workflows.rs @@ -251,6 +251,63 @@ fn epoch_annotation_switch_and_reset_workflow_is_reversible_until_reset() { assert_success(&efo(&repo, &["epoch", "next"])); } +#[test] +fn organisation_relationships_are_validated_by_entity_type() { + let repo = TestRepo::new(); + assert_success(&efo(&repo, &["init"])); + assert_success(&efo(&repo, &["chr", "add", "Aria"])); + assert_success(&efo(&repo, &["town", "add", "Durn"])); + assert_success(&efo(&repo, &["org", "add", "Iron Council"])); + assert_success(&efo( + &repo, + &[ + "org", + "edit", + "Iron Council", + "--capital", + "Durn", + "--governor", + "Aria", + ], + )); + + let invalid = efo(&repo, &["chr", "edit", "Aria", "--capital", "Durn"]); + assert!(!invalid.status.success()); + assert!(stderr(&invalid).contains("Only organisations can own a capital")); + assert!(!stderr(&invalid).contains("panicked")); +} + +#[test] +fn checkpoint_switch_and_reset_recover_from_entity_edits() { + let repo = TestRepo::new(); + assert_success(&efo(&repo, &["init"])); + assert_success(&efo(&repo, &["chr", "add", "Aria"])); + assert_success(&efo(&repo, &["epoch", "tag", "safe"])); + assert_success(&efo(&repo, &["epoch", "next"])); + assert_success(&efo( + &repo, + &["chr", "edit", "Aria", "--new-name", "Aria Changed"], + )); + + assert_success(&efo(&repo, &["epoch", "switch", "safe"])); + let old_state = efo(&repo, &["chr", "show"]); + assert_success(&old_state); + assert!(stdout(&old_state).contains("Aria")); + assert!(!stdout(&old_state).contains("Aria Changed")); + + assert_success(&efo(&repo, &["epoch", "switch", "1"])); + let changed_state = efo(&repo, &["chr", "show"]); + assert_success(&changed_state); + assert!(stdout(&changed_state).contains("Aria Changed")); + + assert_success(&efo(&repo, &["epoch", "switch", "safe"])); + assert_success(&efo(&repo, &["epoch", "reset"])); + assert!(!repo.path().join("epoch/1").exists()); + let recovered = efo(&repo, &["chr", "show"]); + assert_success(&recovered); + assert!(!stdout(&recovered).contains("Aria Changed")); +} + #[test] fn fsck_reports_a_snapshot_with_the_wrong_id_without_panicking() { let repo = TestRepo::new(); diff --git a/docs/README.md b/docs/README.md index 5501fc2..97fc290 100644 --- a/docs/README.md +++ b/docs/README.md @@ -5,6 +5,7 @@ behavior clearly. - [Commands](commands.md): verified CLI surface and examples. - [Repository format](repository.md): files, epochs, compatibility, backup, and recovery. +- [Reversing changes](recovery.md): checkpoints and recovery for every mutation. - [Architecture](architecture.md): crate responsibilities, data flow, and quality gates. - [Roadmap](roadmap.md): current work and stretch proposals. diff --git a/docs/recovery.md b/docs/recovery.md new file mode 100644 index 0000000..59480b7 --- /dev/null +++ b/docs/recovery.md @@ -0,0 +1,43 @@ +# Reversing changes + +Epoch Forge edits the checked-out epoch immediately; there is no staging area +yet. The reliable workflow is therefore to create a checkpoint before a risky +session: + +```bash +efo status +efo epoch next +# Make edits in the new epoch. +``` + +The former state remains in the prior epoch. Inspect it without destroying the +new work with `efo epoch switch `. Switch back if the changes are +good. To abandon them, remain on the older epoch, make an external backup, then +run `efo epoch reset`. + +## Recovery matrix + +| Mutation | Recovery before `epoch reset` | Recovery after destructive removal | +|---|---|---| +| Entity `add`, `edit`, `del` | Switch to the checkpoint epoch | Restore `.epoch` and `epoch/` from Git/backup | +| `epoch summary`, `epoch tag` | Switch to the checkpoint epoch | Restore from Git/backup | +| `epoch next` | Switch to the prior epoch; the new epoch remains available | Not applicable | +| `epoch switch` | Switch back to the previous ID/tag | Not applicable | +| `epoch reset` | No built-in undo | Restore deleted epoch directories and `.epoch` from Git/backup | +| `init` | Remove only the newly-created `.epoch` and `epoch/` after verifying their contents | Restore the containing directory from backup | + +Before `epoch reset`, preserve the complete repository—not only the current +snapshot: + +```bash +git add .epoch epoch/ +git commit -m "checkpoint before abandoning future epochs" +efo epoch reset +``` + +Never reconstruct UUIDs or tag maps manually when a known-good backup exists. +`efo epoch fsck` is read-only and can identify damage, but deliberately does not +guess repairs. + +Native `restore`, `revert`, and pseudo-staging commands belong to the next +repository-format milestone and are specified in the roadmap.