gitgym 0.1.0__py3-none-any.whl

gitgym/__init__.py

@@ -0,0 +1,6 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("gitgym")
+except PackageNotFoundError:
+    __version__ = "unknown"

gitgym/__main__.py

@@ -0,0 +1,3 @@
+from gitgym.cli import main
+
+main()

gitgym/cli.py

@@ -0,0 +1,441 @@
+import shutil
+import subprocess
+
+import click
+
+from gitgym import __version__
+from gitgym.config import GITGYM_HOME, WORKSPACE_DIR
+from gitgym.display import (
+    print_exercise_header,
+    print_exercise_list,
+    print_progress_summary,
+)
+from gitgym.exercise import Exercise, load_all_exercises
+from gitgym.progress import (
+    get_current_exercise,
+    increment_hints_used,
+    load_progress,
+    mark_completed,
+    mark_in_progress,
+    reset_all_progress,
+    reset_exercise_progress,
+)
+from gitgym.runner import run_setup, run_verify
+from gitgym.watcher import watch_and_verify
+
+
+class GitGymGroup(click.Group):
+    """Custom click.Group that checks for git before invoking any command."""
+
+    def invoke(self, ctx: click.Context) -> object:
+        if not _is_git_installed():
+            click.echo(
+                click.style(
+                    "Error: git is not installed or not found in PATH.", fg="red"
+                ),
+                err=True,
+            )
+            click.echo(
+                "Please install git before using gitgym:\n"
+                "  macOS:  brew install git\n"
+                "  Ubuntu: sudo apt install git\n"
+                "  Windows: https://git-scm.com/download/win",
+                err=True,
+            )
+            ctx.exit(1)
+        return super().invoke(ctx)
+
+
+def _is_git_installed() -> bool:
+    """Return True if git is available on PATH and responds to --version."""
+    if shutil.which("git") is None:
+        return False
+    try:
+        result = subprocess.run(
+            ["git", "--version"],
+            capture_output=True,
+            timeout=5,
+        )
+        return result.returncode == 0
+    except (OSError, subprocess.TimeoutExpired):
+        return False
+
+
+@click.group(cls=GitGymGroup)
+@click.version_option(version=__version__, prog_name="gitgym")
+def main():
+    """gitgym - Learn git through interactive exercises."""
+
+
+@main.command("list")
+def list_exercises():
+    """List all exercises grouped by topic, showing completion status."""
+    exercises = load_all_exercises()
+    progress = load_progress()
+    print_exercise_list(exercises, progress)
+
+
+def _exercise_key(exercise: Exercise) -> str:
+    """Derive the progress key (topic_dir/exercise_dir) from the exercise path."""
+    return f"{exercise.path.parent.name}/{exercise.path.name}"
+
+
+def _check_all_completed() -> None:
+    """Print a congratulations message if every exercise is now completed."""
+    exercises = load_all_exercises()
+    progress = load_progress()
+    ex_progress = progress.get("exercises", {})
+    for exercise in exercises:
+        key = _exercise_key(exercise)
+        if ex_progress.get(key, {}).get("status") != "completed":
+            return
+    click.echo()
+    click.echo(
+        click.style(
+            "You've completed all exercises! Congratulations!", fg="green", bold=True
+        )
+    )
+    click.echo("Run 'gitgym clean' to remove exercise data from your system.")
+
+
+def _find_next_incomplete(exercises: list[Exercise], progress: dict) -> Exercise | None:
+    """Return the first exercise that is not completed."""
+    ex_progress = progress.get("exercises", {})
+    for exercise in exercises:
+        key = _exercise_key(exercise)
+        status = ex_progress.get(key, {}).get("status", "not_started")
+        if status != "completed":
+            return exercise
+    return None
+
+
+def _find_by_name(exercises: list[Exercise], name: str) -> Exercise | None:
+    """Return the exercise with the given name, or None if not found."""
+    for exercise in exercises:
+        if exercise.name == name:
+            return exercise
+    return None
+
+
+@main.command("start")
+@click.argument("exercise", required=False)
+def start_exercise(exercise: str | None):
+    """Set up an exercise repo. If no name given, starts the next incomplete exercise."""
+    exercises = load_all_exercises()
+    progress = load_progress()
+
+    if exercise:
+        target = _find_by_name(exercises, exercise)
+        if target is None:
+            click.echo(
+                click.style(f"Error: No exercise named '{exercise}' found.", fg="red"),
+                err=True,
+            )
+            click.echo(
+                "Run 'gitgym list' to see exercise names (e.g. init, staging, amend).",
+                err=True,
+            )
+            raise SystemExit(1)
+    else:
+        target = _find_next_incomplete(exercises, progress)
+        if target is None:
+            click.echo(
+                click.style("All exercises are completed! Great work.", fg="green")
+            )
+            return
+
+    success = run_setup(target)
+    if not success:
+        raise SystemExit(1)
+
+    key = _exercise_key(target)
+    mark_in_progress(key)
+
+    workspace_path = WORKSPACE_DIR / target.path.parent.name / target.path.name
+    click.echo(click.style(f"Exercise directory: {workspace_path}", fg="cyan"))
+    click.echo(f"  cd {workspace_path}\n")
+    print_exercise_header(target)
+
+
+@main.command("next")
+@click.pass_context
+def next_exercise(ctx: click.Context):
+    """Alias for 'gitgym start' with no argument (starts the next incomplete exercise)."""
+    ctx.invoke(start_exercise)
+
+
+@main.command("describe")
+def describe_exercise():
+    """Print the current exercise's description and goal."""
+    current_key = get_current_exercise()
+    if current_key is None:
+        click.echo(
+            click.style("No exercise is currently in progress.", fg="yellow"),
+            err=True,
+        )
+        click.echo(
+            "Run 'gitgym start' or 'gitgym list' to begin an exercise.", err=True
+        )
+        raise SystemExit(1)
+
+    exercises = load_all_exercises()
+    target = None
+    for exercise in exercises:
+        if _exercise_key(exercise) == current_key:
+            target = exercise
+            break
+
+    if target is None:
+        click.echo(
+            click.style(
+                f"Error: Exercise '{current_key}' not found in exercise definitions.",
+                fg="red",
+            ),
+            err=True,
+        )
+        raise SystemExit(1)
+
+    print_exercise_header(target)
+
+
+@main.command("verify")
+def verify_exercise():
+    """Check if the current exercise's goal state is met."""
+    current_key = get_current_exercise()
+    if current_key is None:
+        click.echo(
+            click.style("No exercise is currently in progress.", fg="yellow"),
+            err=True,
+        )
+        click.echo(
+            "Run 'gitgym start' or 'gitgym list' to begin an exercise.", err=True
+        )
+        raise SystemExit(1)
+
+    exercises = load_all_exercises()
+    target = None
+    for exercise in exercises:
+        if _exercise_key(exercise) == current_key:
+            target = exercise
+            break
+
+    if target is None:
+        click.echo(
+            click.style(
+                f"Error: Exercise '{current_key}' not found in exercise definitions.",
+                fg="red",
+            ),
+            err=True,
+        )
+        raise SystemExit(1)
+
+    success, output, is_script_error = run_verify(target)
+
+    if output:
+        click.echo(output)
+
+    if success:
+        click.echo(click.style("Exercise complete! Great work.", fg="green"))
+        mark_completed(current_key)
+        _check_all_completed()
+    elif is_script_error:
+        click.echo(
+            click.style(
+                "The verify script encountered an unexpected error.\n"
+                "Try 'gitgym reset' to restore the exercise.",
+                fg="red",
+            ),
+            err=True,
+        )
+        raise SystemExit(1)
+    else:
+        click.echo(
+            click.style("Not quite right yet. Keep trying!", fg="yellow"), err=True
+        )
+        raise SystemExit(1)
+
+
+@main.command("hint")
+def hint_exercise():
+    """Show the next progressive hint for the current exercise."""
+    current_key = get_current_exercise()
+    if current_key is None:
+        click.echo(
+            click.style("No exercise is currently in progress.", fg="yellow"),
+            err=True,
+        )
+        click.echo(
+            "Run 'gitgym start' or 'gitgym list' to begin an exercise.", err=True
+        )
+        raise SystemExit(1)
+
+    exercises = load_all_exercises()
+    target = None
+    for exercise in exercises:
+        if _exercise_key(exercise) == current_key:
+            target = exercise
+            break
+
+    if target is None:
+        click.echo(
+            click.style(
+                f"Error: Exercise '{current_key}' not found in exercise definitions.",
+                fg="red",
+            ),
+            err=True,
+        )
+        raise SystemExit(1)
+
+    progress = load_progress()
+    hints_used = progress.get("exercises", {}).get(current_key, {}).get("hints_used", 0)
+    total_hints = len(target.hints)
+
+    if hints_used >= total_hints:
+        click.echo(click.style("No more hints available.", fg="yellow"))
+        return
+
+    hint_text = target.hints[hints_used]
+    click.echo(f"Hint {hints_used + 1}/{total_hints}: {hint_text}")
+
+    if hints_used + 1 >= total_hints:
+        click.echo("(No more hints available.)")
+
+    increment_hints_used(current_key)
+
+
+@main.command("reset")
+@click.argument("exercise", required=False)
+@click.option(
+    "--all",
+    "reset_all",
+    is_flag=True,
+    default=False,
+    help="Reset all exercises and clear progress.",
+)
+def reset_exercise(exercise: str | None, reset_all: bool):
+    """Reset an exercise to its initial state.
+
+    If --all is given, deletes the workspace and clears all progress.
+    If EXERCISE is given, resets that exercise.
+    If neither is given, resets the current in-progress exercise.
+    """
+    if reset_all:
+        # Delete workspace directory and progress file
+        if WORKSPACE_DIR.exists():
+            shutil.rmtree(WORKSPACE_DIR)
+        reset_all_progress()
+        click.echo(click.style("All exercises reset. Progress cleared.", fg="green"))
+        return
+
+    exercises = load_all_exercises()
+
+    if exercise:
+        target = _find_by_name(exercises, exercise)
+        if target is None:
+            click.echo(
+                click.style(f"Error: No exercise named '{exercise}' found.", fg="red"),
+                err=True,
+            )
+            click.echo(
+                "Run 'gitgym list' to see exercise names (e.g. init, staging, amend).",
+                err=True,
+            )
+            raise SystemExit(1)
+    else:
+        current_key = get_current_exercise()
+        if current_key is None:
+            click.echo(
+                click.style("No exercise is currently in progress.", fg="yellow"),
+                err=True,
+            )
+            click.echo(
+                "Run 'gitgym start' or 'gitgym list' to begin an exercise.", err=True
+            )
+            raise SystemExit(1)
+
+        target = None
+        for ex in exercises:
+            if _exercise_key(ex) == current_key:
+                target = ex
+                break
+
+        if target is None:
+            click.echo(
+                click.style(
+                    f"Error: Exercise '{current_key}' not found in exercise definitions.",
+                    fg="red",
+                ),
+                err=True,
+            )
+            raise SystemExit(1)
+
+    success = run_setup(target)
+    if not success:
+        raise SystemExit(1)
+
+    key = _exercise_key(target)
+    reset_exercise_progress(key)
+    click.echo(click.style(f"Exercise '{target.name}' has been reset.", fg="green"))
+
+
+@main.command("watch")
+def watch_exercise():
+    """Watch mode: automatically re-verify on repo changes."""
+    current_key = get_current_exercise()
+    if current_key is None:
+        click.echo(
+            click.style("No exercise is currently in progress.", fg="yellow"),
+            err=True,
+        )
+        click.echo(
+            "Run 'gitgym start' or 'gitgym list' to begin an exercise.", err=True
+        )
+        raise SystemExit(1)
+
+    exercises = load_all_exercises()
+    target = None
+    for exercise in exercises:
+        if _exercise_key(exercise) == current_key:
+            target = exercise
+            break
+
+    if target is None:
+        click.echo(
+            click.style(
+                f"Error: Exercise '{current_key}' not found in exercise definitions.",
+                fg="red",
+            ),
+            err=True,
+        )
+        raise SystemExit(1)
+
+    def _on_completed():
+        mark_completed(current_key)
+        _check_all_completed()
+
+    watch_and_verify(target, on_completed=_on_completed)
+
+
+@main.command("progress")
+def show_progress():
+    """Show overall progress summary."""
+    exercises = load_all_exercises()
+    progress = load_progress()
+    print_progress_summary(exercises, progress)
+
+
+@main.command("clean")
+def clean():
+    """Remove all gitgym data (exercises, progress) from your system."""
+    if not GITGYM_HOME.exists():
+        click.echo("Nothing to clean up — no gitgym data found.")
+        return
+
+    click.echo(f"This will delete all gitgym data at {GITGYM_HOME}")
+    click.echo("  (exercise repos, progress, and all local state)")
+    if not click.confirm("Are you sure?"):
+        click.echo("Cancelled.")
+        return
+
+    shutil.rmtree(GITGYM_HOME)
+    click.echo(click.style("All cleaned up. Happy gitting!", fg="green"))

gitgym/config.py

@@ -0,0 +1,9 @@
+from pathlib import Path
+
+# User's home directory for workspace and progress file
+GITGYM_HOME = Path.home() / ".gitgym"
+WORKSPACE_DIR = GITGYM_HOME / "exercises"
+PROGRESS_FILE = GITGYM_HOME / "progress.json"
+
+# Package-relative exercises directory (shipped with the package)
+EXERCISES_DIR = Path(__file__).parent / "exercises"

gitgym/display.py

@@ -0,0 +1,95 @@
+import click
+
+from gitgym.exercise import Exercise
+
+
+def print_success(msg: str) -> None:
+    """Print a success message in green."""
+    click.echo(click.style(msg, fg="green"))
+
+
+def print_error(msg: str) -> None:
+    """Print an error message in red."""
+    click.echo(click.style(msg, fg="red"), err=True)
+
+
+def print_info(msg: str) -> None:
+    """Print an informational message in cyan."""
+    click.echo(click.style(msg, fg="cyan"))
+
+
+def print_exercise_header(exercise: Exercise) -> None:
+    """Print a formatted header for an exercise."""
+    click.echo(click.style(f"── {exercise.topic} ──", fg="yellow"))
+    click.echo(click.style(f"{exercise.title}", fg="bright_white", bold=True))
+    click.echo(f"\n{exercise.description.strip()}\n")
+    click.echo(click.style(f"Goal: {exercise.goal_summary}", fg="yellow"))
+
+
+def _exercise_key(exercise: Exercise) -> str:
+    """Derive the progress key (topic_dir/exercise_dir) from the exercise path."""
+    return f"{exercise.path.parent.name}/{exercise.path.name}"
+
+
+def print_exercise_list(exercises: list[Exercise], progress: dict) -> None:
+    """Print all exercises grouped by topic with completion status indicators."""
+    ex_progress = progress.get("exercises", {})
+    current_topic = None
+    for exercise in exercises:
+        if exercise.topic != current_topic:
+            current_topic = exercise.topic
+            click.echo(click.style(f"\n{exercise.topic}", fg="yellow", bold=True))
+        key = _exercise_key(exercise)
+        status = ex_progress.get(key, {}).get("status", "not_started")
+        if status == "completed":
+            indicator = click.style("✓", fg="green")
+        elif status == "in_progress":
+            indicator = click.style("→", fg="cyan")
+        else:
+            indicator = click.style("○", fg="white")
+        click.echo(f"  {indicator} {exercise.name:<20} {exercise.title}")
+
+
+def print_progress_summary(exercises: list[Exercise], progress: dict) -> None:
+    """Print overall progress stats: completed/total and per-topic breakdown."""
+    ex_progress = progress.get("exercises", {})
+
+    total = len(exercises)
+    completed_total = sum(
+        1
+        for ex in exercises
+        if ex_progress.get(_exercise_key(ex), {}).get("status") == "completed"
+    )
+
+    click.echo(
+        click.style(
+            f"Progress: {completed_total}/{total} exercises completed", bold=True
+        )
+    )
+
+    # Group by topic
+    topics: dict[str, list[Exercise]] = {}
+    for ex in exercises:
+        topics.setdefault(ex.topic, []).append(ex)
+
+    for topic, topic_exercises in topics.items():
+        completed = sum(
+            1
+            for ex in topic_exercises
+            if ex_progress.get(_exercise_key(ex), {}).get("status") == "completed"
+        )
+        total_in_topic = len(topic_exercises)
+        bar_filled = int(completed / total_in_topic * 10) if total_in_topic else 0
+        bar = "█" * bar_filled + "░" * (10 - bar_filled)
+        click.echo(f"  {topic:<20} [{bar}] {completed}/{total_in_topic}")
+
+    if completed_total == total:
+        click.echo()
+        click.echo(
+            click.style(
+                "You've completed all exercises! Congratulations!",
+                fg="green",
+                bold=True,
+            )
+        )
+        click.echo("Run 'gitgym clean' to remove exercise data from your system.")

gitgym/exercise.py

@@ -0,0 +1,45 @@
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+from gitgym.config import EXERCISES_DIR
+
+
+@dataclass
+class Exercise:
+    name: str
+    topic: str
+    title: str
+    description: str
+    goal_summary: str
+    hints: list[str]
+    path: Path
+
+
+def load_exercise(exercise_dir: Path) -> "Exercise":
+    toml_path = exercise_dir / "exercise.toml"
+    with open(toml_path, "rb") as f:
+        data = tomllib.load(f)
+    ex = data["exercise"]
+    hints = [h["text"] for h in data.get("hints", [])]
+    return Exercise(
+        name=ex["name"],
+        topic=ex["topic"],
+        title=ex["title"],
+        description=ex["description"],
+        goal_summary=data["goal"]["summary"],
+        hints=hints,
+        path=exercise_dir,
+    )
+
+
+def load_all_exercises() -> list[Exercise]:
+    """Discover all NN_topic/NN_exercise/ directories under EXERCISES_DIR and return them sorted."""
+    exercise_dirs = sorted(
+        d
+        for topic_dir in sorted(EXERCISES_DIR.iterdir())
+        if topic_dir.is_dir()
+        for d in sorted(topic_dir.iterdir())
+        if d.is_dir()
+    )
+    return [load_exercise(d) for d in exercise_dirs]

gitgym/exercises/01_basics/01_init/exercise.toml

@@ -0,0 +1,20 @@
+[exercise]
+name = "init"
+topic = "Basics"
+title = "Initialize a Repository"
+description = """
+Every git journey starts with `git init`. In this exercise, you'll \
+initialize a new git repository in the provided directory.
+"""
+
+[goal]
+summary = "The directory should be a valid git repository."
+
+[[hints]]
+text = "Look at the `git init` command."
+
+[[hints]]
+text = "Run `git init` inside the exercise directory."
+
+[[hints]]
+text = "Just run: git init"

gitgym/exercises/01_basics/01_init/setup.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+EXERCISE_DIR="$1"
+mkdir -p "$EXERCISE_DIR"
+cd "$EXERCISE_DIR"
+
+# Remove any existing git repo so the exercise is in the expected initial state
+# (idempotent: running setup.sh a second time resets back to pre-init state)
+if [ -d ".git" ]; then
+	rm -rf .git
+fi
+
+# Create a file for the user to work with
+echo "Hello, git!" >hello.txt

gitgym/exercises/01_basics/01_init/verify.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+EXERCISE_DIR="$1"
+cd "$EXERCISE_DIR"
+
+# Check that it's a git repo
+if [ ! -d ".git" ]; then
+	echo "This directory is not a git repository yet."
+	echo "Use 'git init' to initialize it."
+	exit 1
+fi
+
+echo "Great job! You initialized a git repository."
+exit 0

gitgym/exercises/01_basics/02_staging/exercise.toml

@@ -0,0 +1,21 @@
+[exercise]
+name = "staging"
+topic = "Basics"
+title = "Stage a File"
+description = """
+Before git can track a file, you need to stage it with `git add`. \
+In this exercise, a file called `hello.txt` exists in the repo but \
+has not been staged yet. Stage it so git will include it in the next commit.
+"""
+
+[goal]
+summary = "hello.txt should be staged (in the index)."
+
+[[hints]]
+text = "Use `git status` to see the current state of the repository."
+
+[[hints]]
+text = "Look at the `git add` command."
+
+[[hints]]
+text = "Run `git add hello.txt` to stage the file."