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

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

@@ -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.5/CLAUDE.md

@@ -0,0 +1,87 @@
+# 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
+```
+
+## 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).
+
+**Planned**: Wrap this into a Python webapp for on-demand GIF generation.
+
+## 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-0.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gh-space-shooter
-Version: 0.0.4
+Version: 0.0.5
 Summary: A CLI tool that visualizes GitHub contribution graphs as gamified GIFs
 Author-email: zane <czl970721@gmail.com>
 License-File: LICENSE
@@ -122,14 +122,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-0.0.5}/README.md

@@ -106,14 +106,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-0.0.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "gh-space-shooter"
-version = "0.0.4"
+version = "0.0.5"
 description = "A CLI tool that visualizes GitHub contribution graphs as gamified GIFs"
 readme = "README.md"
 authors = [
@@ -29,7 +29,7 @@ build-backend = "hatchling.build"
 
 
 [tool.bumpversion]
-current_version = "0.0.4"
+current_version = "0.0.5"
 parse = """(?x)
   (?P<major>0|[1-9]\\d*)\\.
   (?P<minor>0|[1-9]\\d*)\\.

{gh_space_shooter-0.0.4 → gh_space_shooter-0.0.5}/src/gh_space_shooter/cli.py

@@ -60,6 +60,16 @@ def main(
         "--fps",
         help="Frames per second for the animation",
     ),
+    maxFrame: int | None = typer.Option(
+        None,
+        "--max-frame",
+        help="Maximum number of frames to generate",
+    ),
+    watermark: bool = typer.Option(
+        False,
+        "--watermark",
+        help="Add watermark to the GIF",
+    ),
 ) -> None:
     """
     Fetch or load GitHub contribution graph data and display it.
@@ -95,7 +105,7 @@ def main(
             _save_data_to_file(data, raw_output)
 
         # Generate GIF if requested
-        _generate_gif(data, out, strategy, fps)
+        _generate_gif(data, out, strategy, fps, watermark, maxFrame)
 
     except CLIError as e:
         err_console.print(f"[bold red]Error:[/bold red] {e}")
@@ -151,7 +161,14 @@ def _save_data_to_file(data: ContributionData, file_path: str) -> None:
         raise CLIError(f"Failed to save file '{file_path}': {e}")
 
 
-def _generate_gif(data: ContributionData, file_path: str, strategy_name: str, fps: int) -> None:
+def _generate_gif(
+    data: ContributionData, 
+    file_path: str, 
+    strategy_name: str, 
+    fps: int, 
+    watermark: bool, 
+    maxFrame: int | None
+) -> None:
     """Generate animated GIF visualization."""
     # GIF format limitation: delays below 20ms (>50 FPS) are clamped by most browsers
     if fps > 50:
@@ -174,8 +191,12 @@ def _generate_gif(data: ContributionData, file_path: str, strategy_name: str, fp
 
     # Create animator and generate GIF
     try:
-        animator = Animator(data, strategy, fps=fps)
-        animator.generate_gif(file_path)
+        animator = Animator(data, strategy, fps=fps, watermark=watermark)
+        buffer = animator.generate_gif(maxFrame=maxFrame)
+        console.print("[bold blue]Saving GIF animation...[/bold blue]")
+        with open(file_path, "wb") as f:
+            f.write(buffer.getvalue())
+
         console.print(f"[green]✓[/green] GIF saved to {file_path}")
     except Exception as e:
         raise CLIError(f"Failed to generate GIF: {e}")

{gh_space_shooter-0.0.4 → gh_space_shooter-0.0.5}/src/gh_space_shooter/game/animator.py

@@ -1,10 +1,10 @@
 """Animator for generating GIF animations from game strategies."""
 
+from io import BytesIO
 from typing import Iterator
 
 from PIL import Image
 
-
 from ..github_client import ContributionData
 from .game_state import GameState
 from .renderer import Renderer
@@ -20,6 +20,7 @@ class Animator:
         contribution_data: ContributionData,
         strategy: BaseStrategy,
         fps: int,
+        watermark: bool = False,
     ):
         """
         Initialize animator.
@@ -28,16 +29,18 @@ class Animator:
             contribution_data: The GitHub contribution data
             strategy: The strategy to use for clearing enemies
             fps: Frames per second for the animation
+            watermark: Whether to add watermark to the GIF
         """
         self.contribution_data = contribution_data
         self.strategy = strategy
         self.fps = fps
+        self.watermark = watermark
         self.frame_duration = 1000 // fps
         # Delta time in seconds per frame
         # Used to scale all speeds (cells/second) to per-frame movement
         self.delta_time = 1.0 / fps
 
-    def generate_gif(self, output_path: str) -> None:
+    def generate_gif(self, maxFrame: int | None) -> BytesIO:
         """
         Generate animated GIF and save to file.
 
@@ -46,20 +49,27 @@ class Animator:
         """
         # Initialize game state
         game_state = GameState(self.contribution_data)
-        renderer = Renderer(game_state, RenderContext.darkmode())
+        renderer = Renderer(game_state, RenderContext.darkmode(), watermark=self.watermark)
 
-        frames = self._generate_frames(game_state, renderer)
+        frames: list[Image.Image] = []
+        for frame in self._generate_frames(game_state, renderer):
+            frames.append(frame)
+            if maxFrame is not None and len(frames) >= maxFrame:
+                break
 
-        # Save as GIF
+        gif_buffer = BytesIO()
         if frames:
-            next(frames).save(
-                output_path,
+            frames[0].save(
+                gif_buffer,
+                format="gif",
                 save_all=True,
-                append_images=list(frames),
+                append_images=frames[1:],
                 duration=self.frame_duration,
                 loop=0,  # Loop forever
                 optimize=False,
             )
+        
+        return gif_buffer
 
     def _generate_frames(
         self, game_state: GameState, renderer: Renderer

{gh_space_shooter-0.0.4 → gh_space_shooter-0.0.5}/src/gh_space_shooter/game/renderer.py

@@ -1,24 +1,28 @@
 """Renderer for drawing game frames using Pillow."""
 
-from PIL import Image, ImageDraw
+from PIL import Image, ImageDraw, ImageFont
 
 from ..constants import NUM_WEEKS, SHIP_POSITION_Y
 from .game_state import GameState
 from .render_context import RenderContext
 
+WATERMARK_TEXT = "by czl9707/gh-space-shooter"
+
+
 class Renderer:
     """Renders game state as PIL Images."""
-    def __init__(self, game_state: GameState, render_context: RenderContext):
+    def __init__(self, game_state: GameState, render_context: RenderContext, watermark: bool = False):
         """
         Initialize renderer.
 
         Args:
             game_state: The game state to render
             render_context: Rendering configuration and theming
+            watermark: Whether to add watermark to frames
         """
         self.game_state = game_state
-
         self.context = render_context
+        self.watermark = watermark
 
         self.grid_width = NUM_WEEKS * (self.context.cell_size + self.context.cell_spacing)
         self.grid_height = SHIP_POSITION_Y * (self.context.cell_size + self.context.cell_spacing)
@@ -34,11 +38,33 @@ class Renderer:
         """
         # Create image with background color
         img = Image.new("RGB", (self.width, self.height), self.context.background_color)
-        
+
         # Draw game state
         overlay = Image.new("RGBA", (self.width, self.height), (0, 0, 0, 0))
         draw = ImageDraw.Draw(overlay, "RGBA")
         self.game_state.draw(draw, self.context)
+
+        # Draw watermark if enabled
+        if self.watermark:
+            self._draw_watermark(draw)
+
         combined = Image.alpha_composite(img.convert("RGBA"), overlay)
-        
+
         return combined.convert("RGB").convert("P", palette=Image.Palette.ADAPTIVE)
+
+    def _draw_watermark(self, draw: ImageDraw.ImageDraw) -> None:
+        """Draw watermark text in the bottom-right corner."""
+        font = ImageFont.load_default()
+        color = (100, 100, 100, 128)  # Semi-transparent gray
+        margin = 5
+
+        # Get text bounding box
+        bbox = draw.textbbox((0, 0), WATERMARK_TEXT, font=font)
+        text_width = bbox[2] - bbox[0]
+        text_height = bbox[3] - bbox[1]
+
+        # Position in bottom-right corner
+        x = self.width - text_width - margin
+        y = self.height - text_height - margin
+
+        draw.text((x, y), WATERMARK_TEXT, font=font, fill=color)

{gh_space_shooter-0.0.4 → gh_space_shooter-0.0.5}/uv.lock

@@ -46,7 +46,7 @@ wheels = [
 
 [[package]]
 name = "gh-space-shooter"
-version = "0.0.3"
+version = "0.0.4"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },