Implement faction relationship overview and admin commands #237

New issue

Open

opened 2026-03-16 01:40:20 +00:00 by freemo · 0 comments

freemo commented

2026-03-16 01:40:20 +00:00

Owner

Metadata

Field	Value
Epic	#204 — Reputation UI & Commands
Legendary	#199 — Reputation & Social Standing
Type	Feature
Priority	Medium
Points	5
MoSCoW	Should Have
Branch	`feature/m4-faction-admin-commands`
Commit Message	`Implement faction relationship overview and admin commands (#237)`

Background and Context

Administrators need tools to manage the faction relationship graph that drives the reputation propagation system. The afaction admin command provides both a visualization of the current faction relationships and CRUD operations for managing those relationships.

The faction relationship graph is stored in conf/factions.yaml and loaded at runtime. Admin commands modify this file and reload the relationships in memory. This allows server operators to add new factions, define ally/rival/neutral relationships, and restructure the faction hierarchy without restarting the server.

This command is essential for world builders who need to tune the reputation propagation behavior and for debugging reputation issues.

Expected Behavior

afaction (no arguments):

Displays the full faction relationship graph as a formatted list:

=== Faction Relationships ===

Merchant Guild:
  Allies: Oakvale, Royal Court
  Rivals: Thieves Guild
  Parent Region: Central Kingdom
  Sub-regions: Oakvale Market District

Thieves Guild:
  Allies: Smuggler's Cove
  Rivals: Merchant Guild, Royal Guard
  Parent Region: None
  Sub-regions: None

afaction set <faction1> <faction2> <relationship>:
- Sets the relationship between two factions.
- relationship is one of: ally, rival, neutral.
- Setting neutral removes any existing ally/rival relationship.
- Updates conf/factions.yaml and reloads in-memory relationships.
- Displays confirmation: "Set Merchant Guild and Thieves Guild as rivals."
afaction list: Alias for afaction with no arguments.
afaction info <faction>: Shows detailed info about one faction including all relationships and current player reputation distribution.
All afaction commands require admin privileges.

Acceptance Criteria

afaction displays the complete faction relationship graph.
afaction set <f1> <f2> <rel> correctly updates ally/rival/neutral relationships.
Setting neutral removes existing relationships.
Changes are persisted to conf/factions.yaml.
In-memory faction relationships are reloaded after changes.
afaction list works as alias for no-argument form.
afaction info <faction> shows detailed faction information.
All commands require admin privileges and reject non-admin users.
Error messages for invalid faction names or relationship types.

Subtasks

Create lib/aethyr/core/commands/admin/afaction.rb with the afaction command handler.
Implement faction graph display formatting.
Implement set subcommand with relationship validation.
Implement conf/factions.yaml write-back on relationship changes.
Implement in-memory faction relationship reload.
Implement list alias.
Implement info subcommand with detailed faction view.
Add admin privilege check.
Register command in admin command parser.
Implement error handling for invalid factions and relationship types.
Docs: Update YARD comments on affected classes and methods. Update relevant Docusaurus documentation pages if applicable.
Tests (Cucumber): Add tests/unit/afaction_commands.feature covering graph display, set ally/rival/neutral, persistence, reload, info view, admin check, and error cases.
Tests (Cucumber Integration): Add integration feature in tests/integration/ for admin faction management including setting relationships and verifying propagation changes.
Tests (Profiling): Run bundle exec rake unit_profile and verify no performance regressions.
Quality: Verify coverage >=97% via bundle exec rake unit. If coverage is <97% then review the current unit test coverage report at build/tests/unit/coverage/ and use it to write new Cucumber based unit tests to improve code coverage. Specifically, write Cucumber/Gherkin style unit tests that are descriptively named and specifically improve coverage on whichever file has the most uncovered lines by writing tests that will target the uncovered lines in the report. Once that is done rerun bundle exec rake unit to verify all tests pass and coverage is above >=97%. Only mark this as complete once coverage is >=97%, if not repeat this task as many times as is needed until coverage reaches >=97%.
Quality: Run bundle exec rake (default task: unit tests with coverage) and bundle exec rake integration, fix any errors if needed ensuring both pass across entire code base, do not ignore any failure even if it seems unrelated to this commit, fix it.

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation.
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.

## Metadata | Field | Value | |-------|-------| | **Epic** | #204 — Reputation UI & Commands | | **Legendary** | #199 — Reputation & Social Standing | | **Type** | Feature | | **Priority** | Medium | | **Points** | 5 | | **MoSCoW** | Should Have | | **Branch** | `feature/m4-faction-admin-commands` | | **Commit Message** | `Implement faction relationship overview and admin commands (#237)` | ## Background and Context Administrators need tools to manage the faction relationship graph that drives the reputation propagation system. The `afaction` admin command provides both a visualization of the current faction relationships and CRUD operations for managing those relationships. The faction relationship graph is stored in `conf/factions.yaml` and loaded at runtime. Admin commands modify this file and reload the relationships in memory. This allows server operators to add new factions, define ally/rival/neutral relationships, and restructure the faction hierarchy without restarting the server. This command is essential for world builders who need to tune the reputation propagation behavior and for debugging reputation issues. ## Expected Behavior 1. **`afaction`** (no arguments): - Displays the full faction relationship graph as a formatted list: ``` === Faction Relationships === Merchant Guild: Allies: Oakvale, Royal Court Rivals: Thieves Guild Parent Region: Central Kingdom Sub-regions: Oakvale Market District Thieves Guild: Allies: Smuggler's Cove Rivals: Merchant Guild, Royal Guard Parent Region: None Sub-regions: None ``` 2. **`afaction set <faction1> <faction2> <relationship>`**: - Sets the relationship between two factions. - `relationship` is one of: `ally`, `rival`, `neutral`. - Setting `neutral` removes any existing ally/rival relationship. - Updates `conf/factions.yaml` and reloads in-memory relationships. - Displays confirmation: "Set Merchant Guild and Thieves Guild as rivals." 3. **`afaction list`**: Alias for `afaction` with no arguments. 4. **`afaction info <faction>`**: Shows detailed info about one faction including all relationships and current player reputation distribution. 5. All `afaction` commands require admin privileges. ## Acceptance Criteria - [ ] `afaction` displays the complete faction relationship graph. - [ ] `afaction set <f1> <f2> <rel>` correctly updates ally/rival/neutral relationships. - [ ] Setting neutral removes existing relationships. - [ ] Changes are persisted to `conf/factions.yaml`. - [ ] In-memory faction relationships are reloaded after changes. - [ ] `afaction list` works as alias for no-argument form. - [ ] `afaction info <faction>` shows detailed faction information. - [ ] All commands require admin privileges and reject non-admin users. - [ ] Error messages for invalid faction names or relationship types. ## Subtasks - [ ] Create `lib/aethyr/core/commands/admin/afaction.rb` with the `afaction` command handler. - [ ] Implement faction graph display formatting. - [ ] Implement `set` subcommand with relationship validation. - [ ] Implement `conf/factions.yaml` write-back on relationship changes. - [ ] Implement in-memory faction relationship reload. - [ ] Implement `list` alias. - [ ] Implement `info` subcommand with detailed faction view. - [ ] Add admin privilege check. - [ ] Register command in admin command parser. - [ ] Implement error handling for invalid factions and relationship types. - [ ] Docs: Update YARD comments on affected classes and methods. Update relevant Docusaurus documentation pages if applicable. - [ ] Tests (Cucumber): Add `tests/unit/afaction_commands.feature` covering graph display, set ally/rival/neutral, persistence, reload, info view, admin check, and error cases. - [ ] Tests (Cucumber Integration): Add integration feature in `tests/integration/` for admin faction management including setting relationships and verifying propagation changes. - [ ] Tests (Profiling): Run `bundle exec rake unit_profile` and verify no performance regressions. - [ ] Quality: Verify coverage >=97% via `bundle exec rake unit`. If coverage is <97% then review the current unit test coverage report at `build/tests/unit/coverage/` and use it to write new Cucumber based unit tests to improve code coverage. Specifically, write Cucumber/Gherkin style unit tests that are descriptively named and specifically improve coverage on whichever file has the most uncovered lines by writing tests that will target the uncovered lines in the report. Once that is done rerun `bundle exec rake unit` to verify all tests pass and coverage is above >=97%. Only mark this as complete once coverage is >=97%, if not repeat this task as many times as is needed until coverage reaches >=97%. - [ ] Quality: Run `bundle exec rake` (default task: unit tests with coverage) and `bundle exec rake integration`, fix any errors if needed ensuring both pass across **entire** code base, do not ignore any failure even if it seems unrelated to this commit, fix it. ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done.