docs: align guides with current CLI behavior
This commit is contained in:
parent
d9b656f74c
commit
94b3d75b2b
|
|
@ -9,23 +9,23 @@ work belongs here before implementation.
|
|||
- [x] Inventory workspace crates, commands, persistence files, CI, and tests.
|
||||
- [x] Run the untouched baseline test suite (58 library tests; 0 binary tests).
|
||||
- [x] Record product and engineering conventions in `AGENTS.md`.
|
||||
- [ ] Capture baseline `--help` output and exercise a complete temporary-repo
|
||||
- [x] Capture baseline `--help` output and exercise a complete temporary-repo
|
||||
workflow; record every command that panics, lies, or mutates unexpectedly.
|
||||
- [ ] Run formatting and strict Clippy; classify all warnings.
|
||||
- [ ] Map the current `.epochconfig` / epoch-directory format and its recovery
|
||||
- [x] Map the current `.epochconfig` / epoch-directory format and its recovery
|
||||
properties before changing persistence.
|
||||
|
||||
## Phase 1 — honest documentation and CLI contract
|
||||
|
||||
- [ ] Replace the README's advertised-but-missing commands with a concise,
|
||||
- [x] Replace the README's advertised-but-missing commands with a concise,
|
||||
verified capability summary and working quick start.
|
||||
- [ ] Add `docs/README.md` as the documentation index.
|
||||
- [ ] Add a command reference generated from verified `--help` behavior.
|
||||
- [ ] Document the repository layout, identifiers, epochs, persistence, and
|
||||
- [x] Add `docs/README.md` as the documentation index.
|
||||
- [x] Add a command reference based on verified `--help` behavior.
|
||||
- [x] Document the repository layout, identifiers, epochs, persistence, and
|
||||
manual backup/recovery procedure.
|
||||
- [ ] Add an architecture guide covering crate boundaries and data flow.
|
||||
- [ ] Add a compatibility policy for stored data and CLI scripts.
|
||||
- [ ] Add a roadmap that distinguishes implemented, current-release, planned,
|
||||
- [x] Add an architecture guide covering crate boundaries and data flow.
|
||||
- [x] Add a compatibility policy for stored data and CLI scripts.
|
||||
- [x] Add a roadmap that distinguishes implemented, current-release, planned,
|
||||
and stretch work.
|
||||
- [ ] Correct typos, stale rustdoc examples, and misleading comments.
|
||||
|
||||
|
|
@ -113,6 +113,11 @@ These require user approval and are not part of the current implementation:
|
|||
- `show` currently prints a randomly generated entity repeatedly and does not
|
||||
inspect repository data.
|
||||
- `init` exposes `--force`, but the handler does not use it.
|
||||
- `epoch diff` and `epoch fsck` panic through `unimplemented!()`.
|
||||
- `epoch switch --force` is parsed but ignored.
|
||||
- Entity rendering emits ANSI escapes when stdout is redirected and relies on
|
||||
several optional Nerd Font glyphs for labels.
|
||||
- Name generation creates `naming.json` in the process working directory.
|
||||
- The binary crate currently has no tests; most coverage is parsing/model-level.
|
||||
- Existing library tests passed on 2026-09-20. Tarpaulin was intentionally not
|
||||
run because badges are release-only by project policy.
|
||||
|
|
|
|||
179
README.md
179
README.md
|
|
@ -1,138 +1,101 @@
|
|||
# 📦 Epoch Forge (`epoch_forge`) – *early alpha*
|
||||
  
|
||||
# Epoch Forge
|
||||
|
||||

|
||||
  
|
||||
|
||||
> **A Rust-powered CLI for managing fantasy organisations across time.**
|
||||
> *Think of it as a living, breathing world-state engine that lets you “rewind”, “fast-forward”, and **alter** the history of guilds, towns, wars, and characters.*
|
||||
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.
|
||||
|
||||
> **Epoch Forge** is a Rust‑powered command‑line tool that lets you build and manipulate a living fantasy world.
|
||||
> It is **in early alpha** – the API is subject to change, some features are missing, and stability is **not guaranteed**.
|
||||
The current release manages characters, towns, events, calamities, and blockers
|
||||
with statistics and relationships. Organisation-agnostic custom fields,
|
||||
pseudo-staging, complete restore/revert workflows, and a TUI are planned—not
|
||||
implemented. There is no GUI or web interface.
|
||||
|
||||
> **Stats & analytics are not yet implemented** – most commands operate only on the raw data model.
|
||||
> 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).
|
||||
|
||||
## ✨ Quick start
|
||||
## Install
|
||||
|
||||
The project currently requires Rust 1.92 or newer:
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://proxy.dandaedre.com/gitea/idle-org/epoch_forge.git
|
||||
cd epoch_forge
|
||||
|
||||
# Build & install the binary
|
||||
cargo install --locked --path bin_efo
|
||||
```
|
||||
|
||||
# Initialise an empty world (epoch 0)
|
||||
## 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
|
||||
|
||||
# Add an organisation
|
||||
efo org add "The Iron Horde"
|
||||
efo chr add "Aria" --stats strength:12 food:8
|
||||
efo town add "Durn" --position 12,5
|
||||
efo status
|
||||
efo chr show Aria
|
||||
|
||||
# Add a town
|
||||
efo town add "Durn" --stat pop:32
|
||||
|
||||
# Inspect the current world state
|
||||
efo show > world.json
|
||||
cat world.json
|
||||
|
||||
# Show the epoch timeline
|
||||
efo epoch log
|
||||
|
||||
# Create the next scheduled epoch
|
||||
# Snapshot the current state as the next epoch.
|
||||
efo epoch summary "The expedition begins"
|
||||
efo epoch tag beginning
|
||||
efo epoch next
|
||||
|
||||
# Switch back to epoch 5 (if it exists)
|
||||
efo epoch switch 5
|
||||
|
||||
# Tag the current epoch
|
||||
efo epoch tag milestone1
|
||||
|
||||
# Add a short-lived event
|
||||
efo event add "Storm" \
|
||||
--duration Duration(1) \
|
||||
--effect permanent-effect-to-apply \
|
||||
--stats damage=20
|
||||
# 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
|
||||
```
|
||||
|
||||
> **Tip:** The `show` command can print JSON, which you can pipe to `jq` or any other tooling.
|
||||
Run `efo --help`, `efo <command> --help`, or see the
|
||||
[command reference](docs/commands.md) for the complete current interface.
|
||||
|
||||
## 🏆 Project Highlights
|
||||
## Capabilities
|
||||
|
||||
| Feature | Description | Where to find it |
|
||||
|---------|-------------|-----------------|
|
||||
| **Epoch management** | Switch, advance, or rewind the global timeline | `core::epoch` |
|
||||
| **Persistence** | JSON/YAML stores, pluggable back-ends | `core::epoch` |
|
||||
| **Event handling** | Add/remove world-shaping events (storms, festivals, wars) | `core::entities` |
|
||||
| **Organisation CRUD** | Guilds, factions, corporations | `core::entities` |
|
||||
| **Character CRUD** | Heroes, villains, NPCs | `core::entities` |
|
||||
| **Town CRUD** | Villages, cities, trade hubs | `core::entities` |
|
||||
| **Link network** | Alliances, wars, roads, trade routes | `core::link` |
|
||||
| **CLI** | `efo` binary with sub-commands | `efo` crate |
|
||||
| Area | Available now | Not available yet |
|
||||
|---|---|---|
|
||||
| Repository | Initialise in the current directory; inspect status | Discovery from child directories; locking; migrations |
|
||||
| Timeline | Advance, switch, log, tag, summarise, delete future epochs | World diff; integrity repair; branching; atomic restore/revert |
|
||||
| Entities | Add, edit, list, inspect, diff, and delete five built-in types | Organisations; custom types and custom fields; bulk operations |
|
||||
| Generation | Generate character, town, event, calamity, blocker, and exotic names | Deterministic seed controls and template packs |
|
||||
| Interfaces | CLI | TUI (possible stretch goal); GUI/web (out of scope) |
|
||||
|
||||
> *Statistics, analytics, and the `act` feature are still a work in progress.*
|
||||
Some commands in the 0.1.0 parser are known incomplete. `epoch diff`,
|
||||
`epoch fsck`, and the top-level `show` command are being repaired and should not
|
||||
be relied upon until their roadmap items are checked. The per-type commands,
|
||||
such as `efo chr show`, are the supported way to inspect entities.
|
||||
|
||||
## Unimplemented / WIP
|
||||
## Documentation
|
||||
|
||||
| Feature | Status | Where it lives |
|
||||
|---------|--------|----------------|
|
||||
| **Act** | Planned, not yet implemented | `core::act` |
|
||||
| **Stats** | Missing – no aggregated data | – |
|
||||
- [Documentation index](docs/README.md)
|
||||
- [Commands](docs/commands.md)
|
||||
- [Repository, persistence, and recovery](docs/repository.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)
|
||||
|
||||
## Quick reference table
|
||||
|
||||
| Sub‑command | Usage example | What it changes |
|
||||
|-------------|---------------|-----------------|
|
||||
| **`init`** | `efo init`<br>`efo init --force` | Creates an empty epoch repository (epoch 0) in the current directory. |
|
||||
| **`epoch log`** | `efo epoch log --limit 20` | Prints a chronological list of epochs up to the current one. |
|
||||
| **`epoch switch`** | `efo epoch switch 5` | Sets the current epoch to the specified `<id>` (must already exist). |
|
||||
| **`epoch next`** | `efo epoch next` | Generates the next scheduled epoch and inserts it. |
|
||||
| **`epoch reset`** | `efo epoch reset` | Deletes all epochs with an identifier greater than the current one. |
|
||||
| **`epoch diff`** | `efo epoch diff 2 4` | *Unimplemented* – placeholder for future diffing logic. |
|
||||
| **`epoch tag`** | `efo epoch tag milestone1` | Adds a unique tag to the current epoch, updating the global tag map. |
|
||||
| **`epoch fsck`** | `efo epoch fsck` | *Unimplemented* – intended to run a consistency check. |
|
||||
| **`epoch summary`** | `efo epoch summary "Reached the new frontier"` | Replaces the `summary` field of the current epoch with `<text>`. |
|
||||
| **`show`** | `efo show` | Prints the current world state (JSON). |
|
||||
| **`gen`** | `efo gen character -n 5 --short`<br>`efo gen town -n 2`<br>`efo gen event -n 3 --name` | Prints generated names/ideas; useful for scripting. |
|
||||
| **`chr add`** | `efo chr add "Aria" --pos 5,12 --stats strength=12 agility=9` | Creates a new entity (character, town, event, etc.) and writes the epoch. |
|
||||
| **`chr del`** | `efo chr del "Aria"` | Removes the matching entity from the epoch. |
|
||||
| **`chr edit`** | `efo chr edit "Storm" --duration Duration(2)` | Modifies an existing entity’s stats, position, duration, etc. |
|
||||
| **`chr find`** | `efo chr find "Aria"` | Prints full details of a single entity. |
|
||||
| **`chr show`** | `efo chr show` | Lists all entities, or `efo chr show "Aria"` shows one in full detail. |
|
||||
| **`chr diff`** | `efo chr diff "Aria"` | Prints the difference between the current and previous epoch for that entity. |
|
||||
| **`event add` / `event remove`** | `efo event add ...`<br>`efo event remove ...` | Adds or removes an event. |
|
||||
| **`org add` / `org remove`** | `efo org add ...`<br>`efo org remove ...` | Manages organisations (guilds, factions). |
|
||||
| **`town add` / `town remove`** | `efo town add ...`<br>`efo town remove ...` | CRUD for towns. |
|
||||
| **`monster add` / `monster remove`** | `efo monster add ...`<br>`efo monster remove ...` | CRUD for monsters. |
|
||||
| **`act`** | *Not yet implemented* | Planned for future action handling. |
|
||||
|
||||
> All changes are persisted immediately to the epoch file after the command finishes.
|
||||
|
||||
## Contributions & Feedback
|
||||
|
||||
Because the project is in early alpha, any feedback, bug reports, or pull requests are welcome.
|
||||
Please remember that **stability is not guaranteed**, so use it in a versionned environnement.
|
||||
|
||||
Happy forging! ✨
|
||||
|
||||
|
||||
## Binary releases
|
||||
|
||||
The CLI package is `efo`, in the `bin_efo` workspace member. Release tags follow
|
||||
its Cargo version (for example, `v0.1.0`). The publisher is invoked from its own
|
||||
checkout with:
|
||||
## Development
|
||||
|
||||
```bash
|
||||
./release.sh /path/to/epoch_forge --package efo --tag v0.1.0
|
||||
cargo fmt --all -- --check
|
||||
cargo test --workspace --all-targets --all-features --locked
|
||||
cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
|
||||
```
|
||||
|
||||
The workspace lockfile is tracked. `Cross.toml` selects the tested cross images
|
||||
for x86-64 musl Linux, AArch64 musl Linux, and x86-64 GNU Windows. The build scripts
|
||||
work with rustc alone inside cross containers; rustup is not required there.
|
||||
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.
|
||||
|
||||
Release archives use `efo-{target}-v{version}.tgz` and contain the matching root
|
||||
directory with `efo` (or `efo.exe`). `SHA256SUMS` accompanies the archives. The
|
||||
selected package manifest carries cargo-binstall metadata for the Gitea URLs.
|
||||
After the matching release has been published, install from the local manifest:
|
||||
## Release archives
|
||||
|
||||
```bash
|
||||
cargo binstall efo --manifest-path bin_efo/Cargo.toml
|
||||
```
|
||||
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).
|
||||
|
|
|
|||
|
|
@ -0,0 +1,12 @@
|
|||
# Epoch Forge documentation
|
||||
|
||||
This documentation describes current executable behavior and labels planned
|
||||
behavior clearly.
|
||||
|
||||
- [Commands](commands.md): verified CLI surface and examples.
|
||||
- [Repository format](repository.md): files, epochs, compatibility, backup, and recovery.
|
||||
- [Architecture](architecture.md): crate responsibilities, data flow, and quality gates.
|
||||
- [Roadmap](roadmap.md): current work and stretch proposals.
|
||||
|
||||
Start with the project [README](../README.md). Contributors should also read
|
||||
[AGENTS.md](../AGENTS.md) and maintain [AGENTS-TASKS.md](../AGENTS-TASKS.md).
|
||||
|
|
@ -0,0 +1,26 @@
|
|||
# Architecture and development
|
||||
|
||||
```text
|
||||
CLI parsing and rendering (`bin_efo`)
|
||||
│
|
||||
▼
|
||||
domain and persistence (`lib_efo`)
|
||||
│
|
||||
▼
|
||||
`.epoch` and `epoch/*`
|
||||
```
|
||||
|
||||
`bin_efo` defines the Clap command tree and presentation. `lib_efo` owns
|
||||
entities, statistics, identifiers, epochs, naming, and JSON persistence. New
|
||||
behavior should be a testable library operation with a thin CLI handler.
|
||||
|
||||
The design direction is to make repository paths explicit; replace truncating
|
||||
writes with temporary-file plus rename; add locking; remove unsafe cache
|
||||
accessors; separate styling from semantic output; and retain unknown custom
|
||||
metadata as the model becomes organisation-agnostic.
|
||||
|
||||
Library tests currently cover parsing, statistics, display snapshots, and parts
|
||||
of entity/epoch behavior. CLI integration coverage is the main gap. Routine CI
|
||||
should run formatting, all-target workspace tests, strict Clippy, and a release
|
||||
build. Tarpaulin and `rust_autobadges` remain local significant-release-only
|
||||
tools. See [AGENTS.md](../AGENTS.md) for contributor rules.
|
||||
|
|
@ -0,0 +1,55 @@
|
|||
# Command reference
|
||||
|
||||
Epoch Forge operates on the current working directory; it does not yet search
|
||||
parent directories. `efo <command> --help` is the authoritative syntax.
|
||||
|
||||
## Repository and timeline
|
||||
|
||||
- `efo init [--force]` creates `.epoch` and `epoch/0/epochinfo.json`. Although
|
||||
`--force` is accepted in 0.1.0, it currently has no effect and will not allow
|
||||
a non-empty directory.
|
||||
- `efo status [EPOCH_ID]` shows an epoch summary, tags, and entity counts.
|
||||
- `efo epoch log [-c N]` shows epochs around the current epoch.
|
||||
- `efo epoch next` creates and checks out the next snapshot. It refuses while
|
||||
later snapshots exist.
|
||||
- `efo epoch switch ID_OR_TAG` checks out an existing snapshot without deleting
|
||||
later ones. Its currently accepted `--force` flag has no effect.
|
||||
- `efo epoch summary TEXT` and `efo epoch tag TAG` annotate the current epoch.
|
||||
- `efo epoch reset` permanently deletes every epoch after the current one.
|
||||
|
||||
`epoch diff` and `epoch fsck` are exposed in 0.1.0 but incomplete and currently
|
||||
panic. They are current-release defects, not usable capabilities.
|
||||
|
||||
## Entities
|
||||
|
||||
The built-in nouns are `chr`, `town`, `event`, `calamity`, and `blocker`:
|
||||
|
||||
```text
|
||||
efo <noun> add [NAME | --rng-name] [OPTIONS]
|
||||
efo <noun> edit <NAME|@UUID> [OPTIONS]
|
||||
efo <noun> show [NAME|@UUID]
|
||||
efo <noun> diff <NAME|@UUID> [--epoch-id ID_OR_TAG]
|
||||
efo <noun> del <NAME|@UUID>
|
||||
```
|
||||
|
||||
Names match by prefix. `@UUID` is the stable form printed in detailed output;
|
||||
short UUID prefixes are accepted. Avoid ambiguous prefixes.
|
||||
|
||||
Common add/edit options include `--stats key:value ...`, `--position x,y`,
|
||||
`--duration`, `--bounds`, `--effect`, faction/reach/description/relationship
|
||||
options, and prestige controls. `edit --delta` adds supplied stats rather than
|
||||
replacing them. See nested help (for example `efo chr add --help`) for exact
|
||||
syntax and values. Mutations write the current epoch immediately; staging does
|
||||
not exist yet.
|
||||
|
||||
The top-level `show` command is currently demo output. Use `<noun> show`.
|
||||
|
||||
## Generation and output
|
||||
|
||||
`efo gen character|town|event|exotic|calamity|blocker` prints generated content.
|
||||
The first naming operation may unexpectedly create `naming.json` in the current
|
||||
directory; removal of this side effect is planned.
|
||||
|
||||
Output is human-readable Unicode. Some 0.1.0 renderers emit ANSI colour when
|
||||
redirected and use optional Nerd Font glyphs; these are known accessibility
|
||||
issues. Stable JSON output is planned. A panic is always a bug.
|
||||
|
|
@ -0,0 +1,50 @@
|
|||
# Repository, persistence, and recovery
|
||||
|
||||
## Layout
|
||||
|
||||
```text
|
||||
.
|
||||
├── .epoch current epoch, build version, global tag map
|
||||
└── epoch/
|
||||
├── 0/epochinfo.json complete epoch-0 world snapshot
|
||||
├── 1/epochinfo.json complete epoch-1 world snapshot
|
||||
└── …
|
||||
```
|
||||
|
||||
`.epoch` is JSON despite having no extension. Each snapshot stores its ID,
|
||||
random seed, tags, summary, and arrays of events, characters, towns, calamities,
|
||||
and blockers. The full world is duplicated per epoch.
|
||||
|
||||
Entity commands edit the current snapshot directly. `epoch next` creates a new
|
||||
snapshot; `epoch switch` only changes the current pointer. `epoch reset` deletes
|
||||
later directories. This is not yet Git-equivalent: there is no working
|
||||
tree/index separation, reflog, locking, atomic multi-file transaction, or
|
||||
built-in undelete.
|
||||
|
||||
## Safety and recovery
|
||||
|
||||
Keep the directory in Git or copy it before important changes:
|
||||
|
||||
```bash
|
||||
git init
|
||||
git add .epoch epoch/
|
||||
git commit -m "backup Epoch Forge world"
|
||||
```
|
||||
|
||||
To revisit prior data without deleting the future:
|
||||
|
||||
```bash
|
||||
efo epoch log
|
||||
efo epoch switch 0
|
||||
efo status
|
||||
```
|
||||
|
||||
Back up before `epoch reset`; Epoch Forge cannot recover its deleted folders.
|
||||
For corruption, stop mutating, copy the complete directory, and restore from a
|
||||
known-good backup. `epoch fsck` is not usable in 0.1.0.
|
||||
|
||||
The config records a writer version, but automatic migrations and unknown-field
|
||||
retention are not implemented. The intended compatibility policy is that newer
|
||||
supported binaries migrate without data loss, format changes provide preview
|
||||
and backup, and future custom fields survive round trips. Current work is
|
||||
tracked in [the roadmap](roadmap.md).
|
||||
|
|
@ -0,0 +1,36 @@
|
|||
# Roadmap
|
||||
|
||||
The detailed backlog is [AGENTS-TASKS.md](../AGENTS-TASKS.md).
|
||||
|
||||
## Implemented foundation
|
||||
|
||||
- Local CLI repository with full-world epoch snapshots.
|
||||
- Five entity collections with add/edit/show/diff/delete operations.
|
||||
- Statistics, positions, duration/effects, selected relationships, and random
|
||||
generation.
|
||||
- Timeline advance, switch, log, tags, summaries, and explicit future deletion.
|
||||
|
||||
## Current release target
|
||||
|
||||
The immediate release prioritises trust: truthful help/docs, no user-triggerable
|
||||
panics, safe initialisation, real `show`, useful read-only `fsck`, world diff,
|
||||
atomic persistence, CLI workflow tests, accessible output, and clear recovery.
|
||||
|
||||
Next comes a reviewed Git-like model for working changes, pseudo-staging,
|
||||
committed epochs, restore, and revert. Organisation-agnostic custom fields and
|
||||
types follow, with migrations and unknown-field retention designed first.
|
||||
|
||||
## Proposed stretch goals
|
||||
|
||||
1. Shell completions and generated man pages.
|
||||
2. Stable JSON/JSONL output and query/filter expressions.
|
||||
3. A keyboard-driven TUI over the same domain API (no GUI).
|
||||
4. Named timeline branches with merge/conflict handling.
|
||||
5. Setting templates for empires, companies, guilds, and nations.
|
||||
6. Validation/simulation hooks before committing an epoch.
|
||||
7. Optional signed snapshots and append-only audit records.
|
||||
8. Deterministic seeded generation/simulation.
|
||||
9. A scripting/plugin boundary after persistence is stable.
|
||||
|
||||
Completions and structured output are the best first stretch investments. A TUI
|
||||
and branching should wait until staging, revert, and locking are reliable.
|
||||
Loading…
Reference in New Issue