feat: document and validate reversible daily workflows

This commit is contained in:
Dandaedre 2026-09-20 22:02:22 +02:00
parent cff2cd0dcf
commit cd09677471
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
8 changed files with 129 additions and 11 deletions

View File

@ -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

View File

@ -81,6 +81,7 @@ Run `efo --help`, `efo <command> --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)

View File

@ -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<GenericStat>,
/// 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<GenericStat>,
}
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 <town>`."
.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(),
),
})

View File

@ -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 <older-epoch>\n efo status\n # Back up the repository, then:\n efo epoch reset"
)]
pub struct Reset;
/// Shows the differences between two epochs.

View File

@ -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 <command> --help` for command-specific examples."
)]
struct Cli {
// /// The level of verbosity
// #[arg(short, long, action = ArgAction::Count, global = true)]

View File

@ -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();

View File

@ -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.

43
docs/recovery.md Normal file
View File

@ -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 <old-id-or-tag>`. 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.