Metadata-Version: 2.4
Name: gitquest
Version: 0.1.0
Summary: Turn your git commit history into a playable ASCII dungeon roguelike.
Author-email: jithin-jz <jithinjzx@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/jithin-jz/gitquest
Project-URL: Repository, https://github.com/jithin-jz/gitquest
Project-URL: Issues, https://github.com/jithin-jz/gitquest/issues
Keywords: git,game,roguelike,cli,ascii,terminal,rich
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=13.0.0
Requires-Dist: GitPython>=3.1.30
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Dynamic: license-file

# gitquest 🗡️

> **Your commits. Your dungeon. Your legend.**
> Turn any git repository's history into a procedurally generated, playable
> ASCII dungeon roguelike — right in your terminal.

`gitquest` reads your repo's real commit history and deterministically builds a
dungeon from it. Each commit becomes a room. Bug-fix commits spawn bugs. Merge
commits become mini-bosses. The languages you've coded fill your skill tree.
Clear every room from the repo's first commit to `HEAD`, then flex your career
on a shareable stats card.

**Same repo + same seed = the same dungeon, every time.** Reproducible and
shareable.

---

## ✨ Demo

<!--
  📽️  ANIMATED GIF PLACEHOLDER
  Drop a terminal recording here (e.g. via `asciinema` + `agg`, or a screen GIF).
  Recommended: a ~20s clip of a fight + the final flex card.
  ![gitquest demo](docs/demo.gif)
-->

```text
   ____ _ _    ___                  _
  / ___(_) |_ / _ \ _   _  ___  ___| |_
 | |  _| | __| | | | | | |/ _ \/ __| __|
 | |_| | | |_| |_| | |_| |  __/\__ \ |_
  \____|_|\__|\__\_\\__,_|\___||___/\__|

      Your commits. Your dungeon. Your legend.

┌───────────────────────────────── Room 2/5 ──────────────────────────────────┐
│ fix: bug in output handling                                                  │
│ 33b27d3 · +2/-0 · a tight crawlspace of tangled diffs                        │
│ 🧙 You meet Ada Lovelace, an ally from this commit.                          │
└──────────────────────────────────────────────────────────────────────────────┘
🧠 Skill XP: +1 Python, +1 JavaScript
┌────────────────────────────── A Bug appears! ───────────────────────────────┐
│                          (>_<)                                               │
│                          Off-by-One                                          │
│                          HP 11  ·  ATK 4  ·  DEF 0                           │
└──────────────────────────────────────────────────────────────────────────────┘
Attack  Defend  Item(0)  Run
Your move (a): » Hero hits Off-by-One for 6 damage.
✔ Off-by-One defeated! (+10 XP, +6 gold)
```

And the grand finale — the shareable **flex card**:

```text
┌───────────────────────────────── flex card ─────────────────────────────────┐
│                    ⚔  GITQUEST CAREER CARD  ⚔                                │
│                    my-repo   seed 17391773614721965407                       │
│                                                                              │
│     RANK: Senior Crusader                                                    │
│     SCORE: 2310                                                              │
│     STATUS: VICTORIOUS                                                        │
│                                                                              │
│     CAREER STATS                                                             │
│       Level   11              Gold   642                                     │
│       Kills   148           Bosses   12                                      │
│     SKILL TREE                                                               │
│   Python      ██████████████████ 220                                         │
│   TypeScript  ███████████░░░░░░░ 130                                         │
│     Specialization: Python  ·  6 skill paths explored                        │
└──────────────────────────────────────────────────────────────────────────────┘
```

---

## 🚀 Install

The zero-friction way (isolated, recommended):

```bash
pipx install gitquest
```

Or with pip:

```bash
pip install gitquest
```

From source:

```bash
git clone https://github.com/jithin-jz/gitquest
cd gitquest
pip install .
```

---

## 🎮 Play

Run it inside any git repository — no arguments needed:

```bash
gitquest
```

`python -m gitquest` works too.

### Flags

| Flag             | Description                                               |
| ---------------- | --------------------------------------------------------- |
| `--path <repo>`  | Play on another repository (default: current directory).  |
| `--seed <n>`     | Force a specific dungeon seed (default: derived from repo).|
| `--fast`         | Skip animations and "press Enter" pauses.                 |
| `--stats-only`   | Skip gameplay and print just the flex card.               |
| `--max-commits`  | Cap/sample commits for huge repos (default: 300).         |
| `--version`      | Print the version.                                        |

Examples:

```bash
gitquest --path ../some-other-repo
gitquest --seed 42 --fast
gitquest --stats-only        # instant career card, no fighting
```

---

## 🧠 How it works

`gitquest` maps real repository data onto game mechanics:

| Git data                              | Becomes…                                        |
| ------------------------------------- | ----------------------------------------------- |
| **Commit**                            | A room in the dungeon                           |
| **Lines added/removed**               | Room size + monster difficulty                  |
| **Merge commit**                      | A mini-boss room                                |
| **Files changed**                     | Loot/items in the room                          |
| **Commit author**                     | An ally/NPC you meet                            |
| **Languages (by file extension)**     | Your skill tree / XP categories                 |
| **Message keywords**                  | Enemy types (`fix` → Bug, `feat` → Feature…)    |
| **Total repo stats**                  | Your final rank (e.g. *Senior Crusader*)        |

### Determinism

The dungeon seed is derived from the SHA of the repository's **first commit**
(unless you pass `--seed`). All procedural generation — monster names, stats,
loot rolls, room sizes — flows from that single seed via a `random.Random`
instance with a fixed call order. The result: identical, reproducible dungeons
that you and a teammate can compare.

### Architecture

```
gitquest/
  cli.py          # entry point + argument parsing (argparse)
  git_parser.py   # extract & normalize commit data (GitPython + git CLI fallback)
  generator.py    # commit data -> dungeon/rooms/monsters (seeded)
  engine.py       # game loop, state, turn handling
  combat.py       # combat math (pure, rng-driven, testable)
  entities.py     # Player, Monster, Room, Item, Dungeon dataclasses
  renderer.py     # all rich-based rendering
  flexcard.py     # final shareable stats card + ranking
  data/           # monster/item name lists, ranks, ascii art
tests/            # pytest: parser, generator determinism, combat
```

Everything runs **locally and offline** — no network calls, ever.

---

## 🛠️ Development

```bash
pip install -e ".[dev]"
pytest
```

Tests cover history parsing, generator **determinism**, and combat logic.

### Edge cases handled

- Not a git repository → friendly error, no traceback.
- Empty history / no commits → friendly nudge to commit first.
- Huge repos → evenly down-sampled to `--max-commits` (still deterministic).
- Missing `GitPython` → automatic fallback to the `git` CLI.

---

## 🤝 Contributing

Issues and PRs welcome! Ideas: more monster archetypes, a `textual` dungeon map,
achievements, or exporting the flex card as an image.

## 📄 License

MIT — see [`LICENSE`](LICENSE).
