diff --git a/AGENTS-TASKS.md b/AGENTS-TASKS.md index 073af85..d8743cf 100644 --- a/AGENTS-TASKS.md +++ b/AGENTS-TASKS.md @@ -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. diff --git a/README.md b/README.md index 4925a97..48df28e 100644 --- a/README.md +++ b/README.md @@ -1,138 +1,101 @@ -# 📦 Epoch Forge (`epoch_forge`) – *early alpha* -![code coverage](badges/coverage.svg) ![version](badges/version.svg) ![code coverage](badges/test.svg) +# Epoch Forge -![📚 Online Documentation](https://books.dandaedre.com/rust_doc/efo/bin_efo/index.html) +![coverage](badges/coverage.svg) ![version](badges/version.svg) ![tests](badges/test.svg) -> **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 --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`
`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 `` (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 ``. | -| **`show`** | `efo show` | Prints the current world state (JSON). | -| **`gen`** | `efo gen character -n 5 --short`
`efo gen town -n 2`
`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 ...`
`efo event remove ...` | Adds or removes an event. | -| **`org add` / `org remove`** | `efo org add ...`
`efo org remove ...` | Manages organisations (guilds, factions). | -| **`town add` / `town remove`** | `efo town add ...`
`efo town remove ...` | CRUD for towns. | -| **`monster add` / `monster remove`** | `efo monster add ...`
`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). diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..5501fc2 --- /dev/null +++ b/docs/README.md @@ -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). diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..0d8322b --- /dev/null +++ b/docs/architecture.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. diff --git a/docs/commands.md b/docs/commands.md new file mode 100644 index 0000000..6c7b9af --- /dev/null +++ b/docs/commands.md @@ -0,0 +1,55 @@ +# Command reference + +Epoch Forge operates on the current working directory; it does not yet search +parent directories. `efo --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 add [NAME | --rng-name] [OPTIONS] +efo edit [OPTIONS] +efo show [NAME|@UUID] +efo diff [--epoch-id ID_OR_TAG] +efo del +``` + +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 ` 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. diff --git a/docs/repository.md b/docs/repository.md new file mode 100644 index 0000000..b16584c --- /dev/null +++ b/docs/repository.md @@ -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). diff --git a/docs/roadmap.md b/docs/roadmap.md new file mode 100644 index 0000000..66df486 --- /dev/null +++ b/docs/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.