gh-space-shooter 0.0.4__tar.gz → 1.0.0__tar.gz

{gh_space_shooter-0.0.4 → gh_space_shooter-1.0.0}/.github/workflows/publish.yml

@@ -14,7 +14,7 @@ on:
         - patch
 
 env:
-  PYTHON_LATEST: 3.13
+  PYTHON_LATEST: 3.12
 
 jobs:
   build:
@@ -45,11 +45,12 @@ jobs:
     - name: Publish
       run: uv publish --token ${{ secrets.PYPI_API_TOKEN }}
 
-    - name: GitHub Release v${{ steps.bump.outputs.current-version }}
+    - name: GitHub Release PIP v${{ steps.bump.outputs.current-version }}
       uses: ncipollo/release-action@v1
       with:
-        name: gh-space-shooter v${{ steps.bump.outputs.current-version }}
+        name: gh-space-shooter pypi v${{ steps.bump.outputs.current-version }}
         tag: v${{ steps.bump.outputs.current-version }}
-        body: "Automated release of version v${{ steps.bump.outputs.current-version }}"
+        body: "Automated release of pypi version v${{ steps.bump.outputs.current-version }}"
         artifacts: dist/*
-        token: ${{ secrets.GH_TOKEN }}
+        token: ${{ secrets.GH_TOKEN }}
+        generateReleaseNotes: true

{gh_space_shooter-0.0.4 → gh_space_shooter-1.0.0}/.github/workflows/test.yml

@@ -7,7 +7,7 @@ on:
     types: [opened, synchronize, reopened]
 
 env:
-  PYTHON_LATEST: 3.13
+  PYTHON_LATEST: 3.12
 
 jobs:
   test:
@@ -15,7 +15,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.13"]
+        python-version: ["3.12"]
 
     steps:
     - name: Checkout code

{gh_space_shooter-0.0.4 → gh_space_shooter-1.0.0}/.gitignore

@@ -19,4 +19,5 @@ wheels/
 .env.*
 
 # Test output
-my-contributions.json
+my-contributions.json
+.vercel

gh_space_shooter-1.0.0/.python-version

@@ -0,0 +1 @@
+3.12

gh_space_shooter-1.0.0/CLAUDE.md

@@ -0,0 +1,90 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build and Development Commands
+
+```bash
+# Install dependencies (uses uv package manager)
+uv sync
+
+# Install with dev dependencies
+uv sync --extra dev
+
+# Run the CLI
+uv run gh-space-shooter <username>
+
+# Run tests
+uv run pytest tests/ -v
+
+# Run a single test file
+uv run pytest tests/test_strategies.py -v
+
+# Run a specific test
+uv run pytest tests/test_strategies.py::test_column_strategy -v
+
+# Run the web app (from app/ directory)
+uv run --project gh-space-shooter-app uvicorn main:app
+```
+
+## Environment Setup
+
+Requires a GitHub Personal Access Token with `read:user` scope:
+```bash
+export GH_TOKEN=your_token_here
+# Or create a .env file with GH_TOKEN=your_token
+```
+
+## Project Context
+
+**Current main usage**: GitHub Action that automatically updates a game GIF in user repositories daily (see `.github/workflows/` for the action definition).
+
+**Web App**: A FastAPI-based web application is available in the `app/` directory for on-demand GIF generation. See `app/README.md` for details.
+
+## Architecture Overview
+
+This is a CLI tool that transforms GitHub contribution graphs into animated space shooter GIFs using Pillow.
+
+### Core Flow
+
+1. **CLI (`cli.py`)** - Typer-based entry point that orchestrates the pipeline
+2. **GitHubClient (`github_client.py`)** - Fetches contribution data via GitHub GraphQL API, returns typed `ContributionData` dict
+3. **Animator (`game/animator.py`)** - Main game loop that coordinates strategy execution and frame generation
+4. **GameState (`game/game_state.py`)** - Central state container holding ship, enemies, bullets, explosions
+5. **Renderer (`game/renderer.py`)** - Converts GameState to PIL Images each frame
+
+### Strategy Pattern
+
+Strategies (`game/strategies/`) define how the ship clears enemies:
+- `BaseStrategy` - Abstract base defining `generate_actions(game_state) -> Iterator[Action]`
+- `ColumnStrategy` - Clears enemies column by column (left to right)
+- `RowStrategy` - Clears enemies row by row (top to bottom)
+- `RandomStrategy` - Targets enemies in random order
+
+Strategies yield `Action(x, shoot)` objects. The Animator processes these: moving the ship to position `x`, waiting for movement/cooldown to complete, then shooting if `shoot=True`.
+
+### Drawable System
+
+All game objects inherit from `Drawable` (`game/drawables/drawable.py`):
+- `animate(delta_time)` - Update state (position, cooldowns, particles)
+- `draw(draw, context)` - Render to PIL ImageDraw
+
+Drawables: `Ship`, `Enemy`, `Bullet`, `Explosion`, `Starfield`
+
+The `RenderContext` (`game/render_context.py`) holds theming (colors, cell sizes, padding) and coordinate conversion helpers.
+
+### Animation Loop
+
+In `Animator._generate_frames()`:
+1. Strategy yields next action
+2. Ship moves to target x position (animate frames until arrived)
+3. Ship shoots if action.shoot (animate frames for bullet travel + explosions)
+4. Repeat until all enemies destroyed
+
+Frame rate is configurable (default 40 FPS). All speeds use delta_time for frame-rate independence.
+
+### Key Constants (`constants.py`)
+
+- `NUM_WEEKS = 52` - Contribution graph width
+- `NUM_DAYS = 7` - Contribution graph height
+- Speeds are in cells/second, durations in seconds

{gh_space_shooter-0.0.4 → gh_space_shooter-1.0.0}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: gh-space-shooter
-Version: 0.0.4
+Version: 1.0.0
 Summary: A CLI tool that visualizes GitHub contribution graphs as gamified GIFs
 Author-email: zane <czl970721@gmail.com>
 License-File: LICENSE
-Requires-Python: >=3.13
+Requires-Python: >=3.12
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: pillow>=10.1.0
 Requires-Dist: python-dotenv>=1.0.0
@@ -22,6 +22,10 @@ Transform your GitHub contribution graph into an epic space shooter game!
 
 ## Usage
 
+### Onetime Generation
+
+A [web interface](https://gh-space-shooter.kiyo-n-zane.com) is available for on-demand GIF generation without installing anything locally. 
+
 ### GitHub Action
 
 Automatically update your game GIF daily using GitHub Actions! Add this workflow to your repository at `.github/workflows/update-game.yml`:
@@ -122,14 +126,15 @@ gh-space-shooter torvalds --output my-epic-game.gif
 gh-space-shooter torvalds -o my-game.gif
 
 # Choose enemy attack strategy
-gh-space-shooter torvalds --strategy column   # Enemies attack in columns
 gh-space-shooter torvalds --strategy row      # Enemies attack in rows
 gh-space-shooter torvalds -s random           # Random chaos (default)
 
 # Adjust animation frame rate
-gh-space-shooter torvalds --fps 25            # Slower, smaller file size
-gh-space-shooter torvalds --fps 40            # Default frame rate
-gh-space-shooter torvalds --fps 50            # Smoother animation
+gh-space-shooter torvalds --fps 25            # Lower Frame rate, Smaller file size
+gh-space-shooter torvalds --fps 40            # Default Frame rate, Larger file size
+
+# Stop the animation earlier
+gh-space-shooter torvalds --max-frame 200     # Stop after 200 frames
 ```
 
 This creates an animated GIF showing:

{gh_space_shooter-0.0.4 → gh_space_shooter-1.0.0}/README.md

@@ -6,6 +6,10 @@ Transform your GitHub contribution graph into an epic space shooter game!
 
 ## Usage
 
+### Onetime Generation
+
+A [web interface](https://gh-space-shooter.kiyo-n-zane.com) is available for on-demand GIF generation without installing anything locally. 
+
 ### GitHub Action
 
 Automatically update your game GIF daily using GitHub Actions! Add this workflow to your repository at `.github/workflows/update-game.yml`:
@@ -106,14 +110,15 @@ gh-space-shooter torvalds --output my-epic-game.gif
 gh-space-shooter torvalds -o my-game.gif
 
 # Choose enemy attack strategy
-gh-space-shooter torvalds --strategy column   # Enemies attack in columns
 gh-space-shooter torvalds --strategy row      # Enemies attack in rows
 gh-space-shooter torvalds -s random           # Random chaos (default)
 
 # Adjust animation frame rate
-gh-space-shooter torvalds --fps 25            # Slower, smaller file size
-gh-space-shooter torvalds --fps 40            # Default frame rate
-gh-space-shooter torvalds --fps 50            # Smoother animation
+gh-space-shooter torvalds --fps 25            # Lower Frame rate, Smaller file size
+gh-space-shooter torvalds --fps 40            # Default Frame rate, Larger file size
+
+# Stop the animation earlier
+gh-space-shooter torvalds --max-frame 200     # Stop after 200 frames
 ```
 
 This creates an animated GIF showing:

{gh_space_shooter-0.0.4 → gh_space_shooter-1.0.0}/action.yml

@@ -42,7 +42,7 @@ runs:
     - name: Set up Python
       uses: actions/setup-python@v5
       with:
-        python-version: '3.13'
+        python-version: '3.12'
 
     - name: Install gh-space-shooter
       shell: bash

gh_space_shooter-1.0.0/app/README.md

@@ -0,0 +1,53 @@
+# gh-space-shooter Web App
+
+A FastAPI web application that provides on-demand GitHub Space Shooter GIF generation through a browser interface.
+
+## Features
+
+- Web UI for generating GIFs without CLI installation
+- Select GitHub username and animation strategy (random, column, row)
+- Download generated GIFs directly
+- Share functionality for supported browsers
+
+## Setup
+
+1. Install dependencies:
+   ```bash
+   cd app
+   uv sync
+   ```
+
+2. Set up environment:
+   ```bash
+   export GH_TOKEN=your_github_token
+   # Or create a .env file with GH_TOKEN=your_token
+   ```
+
+## Running Locally
+
+```bash
+uv run --project gh-space-shooter-app uvicorn main:app
+```
+
+The app will be available at `http://localhost:8000`.
+
+## API Endpoints
+
+- `GET /` - Web UI for generating GIFs
+- `GET /api/generate?username=<username>&strategy=<strategy>` - Generate and return a GIF
+  - `username` (required): GitHub username
+  - `strategy` (optional): Animation strategy - `random`, `column`, or `row` (default: `random`)
+
+## Project Structure
+
+```
+app/
+├── src/
+│   ├── main.py           # FastAPI application
+│   └── templates/
+│       └── index.html    # Web UI template
+├── public/
+│   └── favicon.ico
+├── pyproject.toml
+└── README.md
+```

gh_space_shooter-1.0.0/app/pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "gh-space-shooter-app"
+version = "0.1.0"
+description = "Web app wrapper for gh-space-shooter GIF generation"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "gh-space-shooter",
+    "fastapi[standard]",
+    "uvicorn[standard]",
+    "jinja2",
+]
+
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project.scripts]
+app = "main:app"

gh_space_shooter-1.0.0/app/src/main.py

@@ -0,0 +1,78 @@
+"""FastAPI web app for gh-space-shooter GIF generation."""
+
+import os
+from io import BytesIO
+from pathlib import Path
+
+from dotenv import load_dotenv
+from fastapi import FastAPI, HTTPException, Query
+from fastapi.requests import Request
+from fastapi.responses import HTMLResponse, Response
+# from fastapi.staticfiles import StaticFiles
+from fastapi.templating import Jinja2Templates
+
+from gh_space_shooter.game import Animator, ColumnStrategy, RandomStrategy, RowStrategy, BaseStrategy
+from gh_space_shooter.github_client import GitHubAPIError, GitHubClient
+
+load_dotenv()
+
+app = FastAPI(title="GitHub Space Shooter")
+
+templates = Jinja2Templates(directory=Path(__file__).parent / "templates")
+# app.mount("/public", StaticFiles(directory=Path(__file__).parent / "public"), name="public")
+
+
+STRATEGY_MAP: dict[str, type[BaseStrategy]] = {
+    "column": ColumnStrategy,
+    "row": RowStrategy,
+    "random": RandomStrategy,
+}
+
+
+def generate_gif(username: str, strategy: str, token: str) -> BytesIO:
+    """Generate a space shooter GIF for a GitHub user."""
+    with GitHubClient(token) as client:
+        data = client.get_contribution_graph(username)
+
+    strategy_class: type[BaseStrategy] = STRATEGY_MAP.get(strategy, RandomStrategy)
+    strat = strategy_class()
+
+    animator = Animator(data, strat, fps=20, watermark=True)
+    return animator.generate_gif(maxFrame=250)
+
+@app.get("/", response_class=HTMLResponse)
+async def index(request: Request):
+    """Serve the main page."""
+    return templates.TemplateResponse(request, "index.html")
+
+
+@app.get("/api/generate")
+async def generate(
+    username: str = Query(..., min_length=1, description="GitHub username"),
+    strategy: str = Query("random", description="Animation strategy"),
+):
+    """Generate and return a space shooter GIF."""
+    token = os.getenv("GH_TOKEN")
+    if not token:
+        raise HTTPException(status_code=500, detail="GitHub token not configured")
+
+    if strategy not in STRATEGY_MAP:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Invalid strategy. Choose from: {', '.join(STRATEGY_MAP.keys())}",
+        )
+
+    try:
+        gif_buffer = generate_gif(username, strategy, token)
+        return Response(
+            content=gif_buffer.getvalue(),
+            media_type="image/gif",
+            headers={
+                "Response-Type": "blob",
+                "Content-Disposition": f"inline; filename={username}-space-shooter.gif"
+            },
+        )
+    except GitHubAPIError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Failed to generate GIF: {e}")