gitquest 0.1.0__tar.gz → 0.2.0__tar.gz

{gitquest-0.1.0 → gitquest-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitquest
-Version: 0.1.0
+Version: 0.2.0
 Summary: Turn your git commit history into a playable ASCII dungeon roguelike.
 Author-email: jithin-jz <jithinjzx@gmail.com>
 License-Expression: MIT
@@ -126,13 +126,30 @@ pip install .
 
 ## 🎮 Play
 
-Run it inside any git repository — no arguments needed:
+Two commands — works on any machine, even with no repo around:
 
 ```bash
+pip install gitquest
 gitquest
 ```
 
-`python -m gitquest` works too.
+If you run `gitquest` **inside a git repository**, it builds the dungeon from
+*your* commit history. If you run it anywhere else, it automatically launches a
+built-in **demo dungeon** so you can play right away.
+
+`python -m gitquest` works too. Want your own repo? `cd` into it first, or pass
+`--path`:
+
+```bash
+cd path/to/your/repo && gitquest
+gitquest --path ../some-other-repo
+gitquest --demo            # force the built-in demo dungeon
+```
+
+### Combat controls
+
+During a fight, type one key + Enter: `a` attack · `d` defend · `i` item ·
+`r` run.
 
 ### Flags
 
@@ -140,6 +157,7 @@ gitquest
 | ---------------- | --------------------------------------------------------- |
 | `--path <repo>`  | Play on another repository (default: current directory).  |
 | `--seed <n>`     | Force a specific dungeon seed (default: derived from repo).|
+| `--demo`         | Play the built-in demo dungeon (no git repo required).    |
 | `--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).         |

{gitquest-0.1.0 → gitquest-0.2.0}/README.md

@@ -98,13 +98,30 @@ pip install .
 
 ## 🎮 Play
 
-Run it inside any git repository — no arguments needed:
+Two commands — works on any machine, even with no repo around:
 
 ```bash
+pip install gitquest
 gitquest
 ```
 
-`python -m gitquest` works too.
+If you run `gitquest` **inside a git repository**, it builds the dungeon from
+*your* commit history. If you run it anywhere else, it automatically launches a
+built-in **demo dungeon** so you can play right away.
+
+`python -m gitquest` works too. Want your own repo? `cd` into it first, or pass
+`--path`:
+
+```bash
+cd path/to/your/repo && gitquest
+gitquest --path ../some-other-repo
+gitquest --demo            # force the built-in demo dungeon
+```
+
+### Combat controls
+
+During a fight, type one key + Enter: `a` attack · `d` defend · `i` item ·
+`r` run.
 
 ### Flags
 
@@ -112,6 +129,7 @@ gitquest
 | ---------------- | --------------------------------------------------------- |
 | `--path <repo>`  | Play on another repository (default: current directory).  |
 | `--seed <n>`     | Force a specific dungeon seed (default: derived from repo).|
+| `--demo`         | Play the built-in demo dungeon (no git repo required).    |
 | `--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).         |

{gitquest-0.1.0 → gitquest-0.2.0}/gitquest/__init__.py

@@ -5,5 +5,5 @@ commits, fight keyword-spawned monsters, gain language XP, and finish with a
 shareable career flex card.
 """
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 __all__ = ["__version__"]

{gitquest-0.1.0 → gitquest-0.2.0}/gitquest/cli.py

@@ -68,6 +68,11 @@ def build_parser() -> argparse.ArgumentParser:
         metavar="N",
         help="cap/sample commits for very large repos (default: 300)",
     )
+    parser.add_argument(
+        "--demo",
+        action="store_true",
+        help="play a built-in demo dungeon (no git repo required)",
+    )
     parser.add_argument(
         "--version",
         action="version",
@@ -103,29 +108,51 @@ def main(argv: list[str] | None = None) -> int:
 
     console = Console()
 
-    # --- Parse the repository --------------------------------------------- #
-    try:
-        repo = parse_repo(args.path, max_commits=args.max_commits)
-    except NotAGitRepoError:
-        console.print(
-            f"[bold red]✗ {os.path.abspath(args.path)} is not a git repository.[/bold red]\n"
-            "[grey62]Run gitquest from inside a repo, or pass --path <repo>.[/grey62]"
-        )
-        return 2
-    except EmptyHistoryError:
+    # --- Parse the repository (or fall back to the built-in demo) --------- #
+    demo_notice = False
+    if args.demo:
+        from .demo import build_demo_repo
+
+        repo = build_demo_repo()
+        demo_notice = True
+    else:
+        try:
+            repo = parse_repo(args.path, max_commits=args.max_commits)
+        except (NotAGitRepoError, EmptyHistoryError):
+            # Zero-friction: if there's no repo to read, play the demo dungeon
+            # so `pip install gitquest && gitquest` always works anywhere.
+            from .demo import build_demo_repo
+
+            repo = build_demo_repo()
+            demo_notice = True
+        except Exception as exc:  # pragma: no cover - defensive
+            console.print(f"[bold red]✗ Failed to read repository:[/bold red] {exc}")
+            return 1
+
+    if demo_notice and not args.stats_only:
         console.print(
-            "[bold red]✗ This repository has no commits yet.[/bold red]\n"
-            "[grey62]Make a commit and try again — every legend starts somewhere.[/grey62]"
+            "[yellow]ℹ No git repository here — launching the built-in demo "
+            "dungeon.[/yellow]\n"
+            "[grey62]  To play your own commits, run gitquest inside a git repo "
+            "(or pass --path <repo>).[/grey62]\n"
         )
-        return 2
-    except Exception as exc:  # pragma: no cover - defensive
-        console.print(f"[bold red]✗ Failed to read repository:[/bold red] {exc}")
-        return 1
 
     # --- Generate the dungeon --------------------------------------------- #
     dungeon = generate_dungeon(repo, user_seed=args.seed)
     player = Player(name=repo.head.author_name or "Hero")
 
+    # Every hero starts with a healing draught so the first room is survivable.
+    from .entities import Item, ItemKind
+
+    player.inventory.append(
+        Item(
+            name="Starter Health Draught",
+            kind=ItemKind.POTION,
+            value=15,
+            description="Restores 15 HP.",
+        )
+    )
+
     # --- Stats-only: silent auto run, then just the flex card ------------- #
     if args.stats_only:
         engine = GameEngine(dungeon, player, interactive=False)

gitquest-0.2.0/gitquest/demo.py

@@ -0,0 +1,79 @@
+"""A built-in demo repository so gitquest is playable anywhere.
+
+When ``gitquest`` is run outside a git repository (e.g. right after
+``pip install gitquest`` on a fresh machine), the CLI falls back to this
+fictional commit history so there's always a dungeon to play. It is fully
+deterministic, so the demo dungeon is identical on every device.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+
+from .git_parser import CommitInfo, RepoData
+
+_BASE = datetime(2024, 1, 1, 9, 0, 0, tzinfo=timezone.utc)
+
+# (author, summary, insertions, deletions, files, is_merge)
+_SCRIPT: list[tuple[str, str, int, int, list[str], bool]] = [
+    ("Ada Lovelace", "feat: scaffold the Dragon-Slayer API", 180, 0,
+     ["app.py", "server.py", "requirements.txt"], False),
+    ("Ada Lovelace", "feat: add /quests endpoint", 96, 4,
+     ["app.py", "routes/quests.py"], False),
+    ("Grace Hopper", "fix: null pointer when quest list is empty", 12, 8,
+     ["routes/quests.py"], False),
+    ("Grace Hopper", "test: add coverage for quest routes", 140, 2,
+     ["tests/test_quests.py"], False),
+    ("Linus T.", "refactor: extract quest service layer", 210, 160,
+     ["routes/quests.py", "services/quest_service.py"], False),
+    ("Margaret H.", "feat: shiny new front-end dashboard", 320, 10,
+     ["web/index.html", "web/app.js", "web/styles.css"], False),
+    ("Margaret H.", "fix: race condition in websocket handler", 24, 18,
+     ["web/app.js"], False),
+    ("Linus T.", "docs: write the README and API guide", 90, 1,
+     ["README.md", "docs/api.md"], False),
+    ("Grace Hopper", "Merge branch 'feature/realtime'", 6, 0,
+     ["web/app.js"], True),
+    ("Dennis R.", "feat: add authentication middleware", 150, 12,
+     ["middleware/auth.py", "app.py"], False),
+    ("Dennis R.", "fix: hotfix expired token crash", 30, 22,
+     ["middleware/auth.py"], False),
+    ("Ada Lovelace", "refactor: tidy config and add type hints", 88, 96,
+     ["config.py", "app.py"], False),
+    ("Barbara L.", "build: bump deps and dockerize", 64, 9,
+     ["Dockerfile", "requirements.txt", "docker-compose.yml"], False),
+    ("Grace Hopper", "Merge pull request #42 from feature/auth", 8, 0,
+     ["app.py"], True),
+]
+
+
+def build_demo_repo() -> RepoData:
+    """Return a deterministic, fictional :class:`RepoData` for demo play."""
+    commits: list[CommitInfo] = []
+    for i, (author, summary, ins, dels, files, is_merge) in enumerate(_SCRIPT):
+        sha = f"{i:02d}" + "d" * 38  # stable, fake-but-valid-looking 40-char sha
+        email = author.lower().replace(" ", ".").replace(".", "") + "@gitquest.dev"
+        commits.append(
+            CommitInfo(
+                sha=sha,
+                short_sha=sha[:7],
+                author_name=author,
+                author_email=email,
+                timestamp=_BASE + timedelta(days=i, hours=i % 5),
+                summary=summary,
+                message=summary,
+                insertions=ins,
+                deletions=dels,
+                files=list(files),
+                is_merge=is_merge,
+                parent_count=2 if is_merge else 1,
+            )
+        )
+
+    return RepoData(
+        name="dragon-slayer-api (demo)",
+        path="<built-in demo>",
+        commits=commits,
+        sampled=False,
+        total_commits=len(commits),
+    )

{gitquest-0.1.0 → gitquest-0.2.0}/gitquest/generator.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 
 import hashlib
 import json
+import math
 import random
 from functools import lru_cache
 from importlib import resources
@@ -110,19 +111,23 @@ def _make_monster(
     name = rng.choice(spec["names"])
     art = spec.get("art", "(o_o)")
 
+    # Compress churn with sqrt so a huge initial commit isn't 10x a small one,
+    # and apply an early-game ramp so the first rooms are gentle (the player
+    # has no levels or loot yet). Difficulty reaches full strength by ~room 10.
     capped = min(churn, 600)
-    depth_bonus = depth * 0.9
-    jitter = rng.uniform(0.85, 1.2)
+    cf = math.sqrt(capped)
+    ramp = min(1.0, 0.45 + depth * 0.06)
+    jitter = rng.uniform(0.9, 1.15)
 
-    hp = int((8 + capped / 10 + depth_bonus) * jitter) + 1
-    attack = int((3 + capped / 45 + depth * 0.30) * jitter) + 1
-    defense = int(capped / 150 + depth * 0.12)
-    xp_reward = int(9 + capped / 9 + depth * 1.6)
-    gold_reward = int(rng.randint(2, 8) + capped / 25 + depth * 0.5)
+    hp = int((7 + cf * 0.9 + depth * 0.7) * ramp * jitter) + 1
+    attack = int((2 + cf * 0.22 + depth * 0.25) * ramp * jitter) + 1
+    defense = int((cf * 0.06 + depth * 0.10) * ramp)
+    xp_reward = int(9 + cf * 1.1 + depth * 1.6)
+    gold_reward = int(rng.randint(2, 8) + cf * 0.4 + depth * 0.5)
 
     if is_boss:
-        hp = int(hp * 2.3) + 12
-        attack = int(attack * 1.4) + 2
+        hp = int(hp * 2.2) + 10
+        attack = int(attack * 1.35) + 2
         defense = int(defense * 1.3) + 1
         xp_reward = int(xp_reward * 3)
         gold_reward = int(gold_reward * 3) + 10
@@ -214,7 +219,7 @@ def _build_room(
         monsters.append(_make_monster(rng, "Boss", churn, index, depth_total, True))
     else:
         monsters.append(_make_monster(rng, archetype, churn, index, depth_total, False))
-        if churn >= 150 and rng.random() < 0.5:
+        if churn >= 200 and index > 3 and rng.random() < 0.45:
             monsters.append(
                 _make_monster(rng, archetype, churn // 2, index, depth_total, False)
             )

{gitquest-0.1.0 → gitquest-0.2.0}/gitquest.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitquest
-Version: 0.1.0
+Version: 0.2.0
 Summary: Turn your git commit history into a playable ASCII dungeon roguelike.
 Author-email: jithin-jz <jithinjzx@gmail.com>
 License-Expression: MIT
@@ -126,13 +126,30 @@ pip install .
 
 ## 🎮 Play
 
-Run it inside any git repository — no arguments needed:
+Two commands — works on any machine, even with no repo around:
 
 ```bash
+pip install gitquest
 gitquest
 ```
 
-`python -m gitquest` works too.
+If you run `gitquest` **inside a git repository**, it builds the dungeon from
+*your* commit history. If you run it anywhere else, it automatically launches a
+built-in **demo dungeon** so you can play right away.
+
+`python -m gitquest` works too. Want your own repo? `cd` into it first, or pass
+`--path`:
+
+```bash
+cd path/to/your/repo && gitquest
+gitquest --path ../some-other-repo
+gitquest --demo            # force the built-in demo dungeon
+```
+
+### Combat controls
+
+During a fight, type one key + Enter: `a` attack · `d` defend · `i` item ·
+`r` run.
 
 ### Flags
 
@@ -140,6 +157,7 @@ gitquest
 | ---------------- | --------------------------------------------------------- |
 | `--path <repo>`  | Play on another repository (default: current directory).  |
 | `--seed <n>`     | Force a specific dungeon seed (default: derived from repo).|
+| `--demo`         | Play the built-in demo dungeon (no git repo required).    |
 | `--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).         |

{gitquest-0.1.0 → gitquest-0.2.0}/gitquest.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ gitquest/__init__.py
 gitquest/__main__.py
 gitquest/cli.py
 gitquest/combat.py
+gitquest/demo.py
 gitquest/engine.py
 gitquest/entities.py
 gitquest/flexcard.py
@@ -21,5 +22,6 @@ gitquest/data/items.json
 gitquest/data/monsters.json
 gitquest/data/ranks.json
 tests/test_combat.py
+tests/test_demo.py
 tests/test_generator.py
 tests/test_git_parser.py

{gitquest-0.1.0 → gitquest-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gitquest"
-version = "0.1.0"
+version = "0.2.0"
 description = "Turn your git commit history into a playable ASCII dungeon roguelike."
 readme = "README.md"
 requires-python = ">=3.10"

gitquest-0.2.0/tests/test_demo.py

@@ -0,0 +1,51 @@
+"""Tests for the built-in demo repo and a full auto playthrough."""
+
+from __future__ import annotations
+
+import random
+
+from gitquest.demo import build_demo_repo
+from gitquest.engine import GameEngine
+from gitquest.entities import Item, ItemKind, Player
+from gitquest.generator import generate_dungeon
+
+
+def test_demo_repo_is_valid():
+    repo = build_demo_repo()
+    assert len(repo.commits) >= 10
+    assert repo.merge_count >= 1
+    assert repo.head.is_merge  # last demo commit is a merge -> boss finale
+    assert "Python" in repo.language_totals
+
+
+def test_demo_is_deterministic():
+    d1 = generate_dungeon(build_demo_repo())
+    d2 = generate_dungeon(build_demo_repo())
+    assert d1 == d2
+
+
+def test_auto_playthrough_completes_and_is_winnable():
+    """The demo should be beatable by the auto strategy (with a starter potion)."""
+    dungeon = generate_dungeon(build_demo_repo())
+    player = Player(name="Hero")
+    player.inventory.append(
+        Item("Starter Health Draught", ItemKind.POTION, 15, description="Restores 15 HP.")
+    )
+    engine = GameEngine(
+        dungeon, player, rng=random.Random(dungeon.seed ^ 0x5EED), interactive=False
+    )
+    engine.run()
+
+    assert player.is_alive, "auto playthrough should survive the demo dungeon"
+    assert player.rooms_cleared == dungeon.size
+    assert player.bosses_slain >= 1
+    assert player.level > 1
+
+
+def test_first_room_is_survivable():
+    """Early rooms must be gentle: the first monster should be weaker than the hero."""
+    dungeon = generate_dungeon(build_demo_repo())
+    first_monster = dungeon.rooms[0].monsters[0]
+    fresh = Player(name="Hero")
+    # The opening monster shouldn't out-stat a level-1 hero on both axes.
+    assert not (first_monster.hp > fresh.max_hp and first_monster.attack > fresh.attack)