A Rust‑powered CLI for managing fantasy organisations across time
Go to file
Dandaedre c300fe3fb3
ci: generate and publish current badges
2026-10-04 03:03:19 +02:00
bin_efo feat: share epoch resolution across adjudication diffusion and conflicts 2026-09-24 19:27:30 +02:00
docs ci: generate and publish current badges 2026-10-04 03:03:19 +02:00
examples/ravenous-draan feat: add curated Draän example world 2026-09-21 18:44:35 +02:00
lib_efo test: harden epoch resolution compatibility and reduction boundaries 2026-09-24 19:35:42 +02:00
scripts ci: generate and publish current badges 2026-10-04 03:03:19 +02:00
tui_efo feat: add previewed TUI entity creation and editing with undo 2026-09-21 19:26:40 +02:00
.gitignore ci: generate and publish current badges 2026-10-04 03:03:19 +02:00
.ignore Adds a build, stops work 2025-12-16 20:58:14 +01:00
.run_status.toml test: raise measured coverage above 70 percent 2026-09-21 02:39:38 +02:00
.rust-toolchain.toml Investigating CI 2025-12-12 19:44:16 +01:00
AGENTS-TASKS.md ci: generate and publish current badges 2026-10-04 03:03:19 +02:00
AGENTS.md ci: generate and publish current badges 2026-10-04 03:03:19 +02:00
Cargo.lock feat: add reproducible named event random draws 2026-09-24 19:32:02 +02:00
Cargo.toml feat: add read-only repository tui 2026-09-21 01:25:25 +02:00
Cross.toml Prepare efo 0.1.0 cross-platform binary release 2026-09-13 20:15:24 +02:00
Jenkinsfile ci: generate and publish current badges 2026-10-04 03:03:19 +02:00
LICENSE
…
README.md ci: generate and publish current badges 2026-10-04 03:03:19 +02:00
tarpaulin.toml ci: generate and publish current badges 2026-10-04 03:03:19 +02:00

README.md

Epoch Forge

coverage version tests

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

Install

The project currently requires Rust 1.92 or newer:

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:

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.

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 <command> --help, or see the command reference for the complete current interface.

Capabilities

Area Available now Not available yet
Repository Initialise format 1.1; 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

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:

mkdir /tmp/epoch-forge-example
cargo run -p lib_efo --example repository -- /tmp/epoch-forge-example

See lib_efo/examples/repository.rs for the complete program. Mutations should use Workspace methods so they retain the same transactional guarantees as efo.

cargo fmt --all -- --check
cargo test --workspace --all-targets --all-features --locked
cargo clippy --workspace --all-targets --all-features --locked -- -D warnings

CI runs the pinned cargo-tarpaulin 0.37.5 release with:

cargo tarpaulin --workspace --all-features --locked --output-dir coverage

The tracked Tarpaulin configuration enforces at least 65% line coverage across all production code. CLI subprocess tests remain valuable even though Tarpaulin cannot attribute their child execution, so those adapters stay in the measured surface. The temporary machine-readable summary is coverage/tarpaulin-report.json. The authoritative version is the efo package version in bin_efo/Cargo.toml.

Jenkins archives exactly coverage/version.svg, coverage/test.svg, and coverage/coverage.svg. Default-branch builds publish them under /mnt/assets/coverage/idle-org/epoch_forge/main/; the public URLs are the three badge images directly below this README's title. The asset mount should be read-only to the public server, with directory listing disabled, a restrictive SVG content security policy, and revalidation or a short cache lifetime for these mutable URLs.

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.