# Epoch Forge ![coverage](badges/coverage.svg) ![version](badges/version.svg) ![tests](badges/test.svg) Epoch Forge (`efo`) is an early-alpha command-line tool for managing a game's world or organisation across a sequence of snapshots called **epochs**. It is designed for people who are comfortable with Git-like concepts: inspect the current state, advance it, compare it with history, and deliberately discard a future timeline when needed. The current release manages organisations, characters, towns, events, calamities, and blockers with statistics and relationships. Repository format 1.0 provides worktree/index staging, immutable commits, restore, conflict-safe revert, switching, and recoverable future pruning from initialisation. A separate TUI searches entities across HEAD, staged, and working state, and offers previewed entity creation/editing with one-step undo. Custom fields and TUI staging/commit workflows remain planned. There is no GUI or web interface. > Epoch Forge is not yet suitable as the only copy of important campaign data. > Keep the repository in Git or make a directory backup before destructive > operations. See [Safety and recovery](docs/repository.md#safety-and-recovery). ## Install The project currently requires Rust 1.92 or newer: ```bash git clone https://proxy.dandaedre.com/gitea/idle-org/epoch_forge.git cd epoch_forge cargo install --locked --path bin_efo cargo install --locked --path tui_efo ``` Nerd Font icons are enabled by default. Build a portable-Unicode variant for terminals without a Nerd Font with: ```bash cargo install --locked --path bin_efo --no-default-features ``` ## Quick start Start in an empty directory. Epoch Forge stores `.epoch` and `epoch/` in the current working directory. ```bash mkdir my-world cd my-world efo init efo chr add "Aria" --stats strength:12 food:8 efo town add "Durn" --position 12,5 efo status efo chr show Aria # Snapshot the current state as the next epoch. efo epoch summary "The expedition begins" efo epoch tag beginning efo epoch next # Compare an entity after editing it in epoch 1. efo chr edit Aria --prestige-add 2 efo chr diff Aria --epoch-id beginning efo epoch log ``` Run `efo --help`, `efo --help`, or see the [command reference](docs/commands.md) for the complete current interface. ## Capabilities | Area | Available now | Not available yet | |---|---|---| | Repository | Initialise format 1.0; inspect; lock and recover transactional writes | Future 1.x migration tooling; discovery from child directories; integrity repair | | Timeline | Commit, advance, switch, log, tag, summarise, diff, reviewable/committed revert, backed-up pruning, and explicit hard reset | Branching and merging | | Entities | Add, edit, list, inspect, diff, and delete six built-in types | Custom types and custom fields; bulk operations | | Generation and simulation | Generate deterministic seeded worlds; roads, travel, event diffusion/arrival resolution; record external rolls and adjudications; run multi-side fights and wars | Setting template packs and interpolated in-transit positions | | Interfaces | Complete CLI; `efo-tui` browser and entity editor | TUI staging/commits; GUI/web (out of scope) | `efo show all` gives a world overview; per-type commands such as `efo chr show Aria` provide targeted or detailed inspection. Run `efo-tui` in a repository root (or use `--repository PATH`). Press `/` to search, `1`/`2`/`3` to browse HEAD/index/worktree, and `v` to toggle formatted details and raw JSON. Use `a` to add to the current collection, `e` to edit, `Ctrl-S` to preview, and `y` to save to the worktree. Press `u` to preview undo of the last TUI save. Narrow terminals show one focused panel; Tab cycles panels. Use `--no-color` for monochrome output and `?` for the scrollable keyboard reference. No Nerd Font is required. ## Documentation - [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) - [TUI scope and keyboard guide](docs/tui-design.md) - [Roadmap and proposed stretch goals](docs/roadmap.md) - [Ready-to-use DraƤn example world](examples/ravenous-draan/README.md) - [Contributor/agent rules](AGENTS.md) and [working task list](AGENTS-TASKS.md) ## Development ### Library example `lib_efo` exposes repository initialization and the complete HEAD/index/worktree model without going through the CLI. To create a repository in an existing empty directory and inspect its initial epoch: ```bash mkdir /tmp/epoch-forge-example cargo run -p lib_efo --example repository -- /tmp/epoch-forge-example ``` See [`lib_efo/examples/repository.rs`](lib_efo/examples/repository.rs) for the complete program. Mutations should use `Workspace` methods so they retain the same transactional guarantees as `efo`. ```bash cargo fmt --all -- --check cargo test --workspace --all-targets --all-features --locked cargo clippy --workspace --all-targets --all-features --locked -- -D warnings ``` Tarpaulin and `rust_autobadges` are intentionally release-only. They do not run in routine CI because of their cost; badge files are refreshed for significant releases. The Tarpaulin configuration excludes the thin CLI adapters because their subprocess integration tests cannot be attributed reliably by its ptrace backend; library and TUI code remain directly measured. ## Release archives The CLI package is `efo` in `bin_efo`. Release tags follow the Cargo version (for example `v0.1.0`). Cross-built archives are named `efo-{target}-v{version}.tgz` and are accompanied by `SHA256SUMS`. Epoch Forge is licensed under the terms in [LICENSE](LICENSE).