feat: document and validate reversible daily workflows
This commit is contained in:
parent
cff2cd0dcf
commit
cd09677471
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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(),
|
||||
),
|
||||
})
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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)]
|
||||
|
|
|
|||
|
|
@ -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();
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
Loading…
Reference in New Issue