assgen 0.3.0__tar.gz

assgen-0.3.0/.dockerignore

@@ -0,0 +1,26 @@
+# ── build/cache artifacts ────────────────────────────────────────────────────
+.git
+.venv
+.venv/
+__pycache__
+*.pyc
+*.pyo
+.pytest_cache
+.ruff_cache
+
+# ── generated / built ────────────────────────────────────────────────────────
+dist/
+site/
+*.egg-info
+*.egg-info/
+
+# ── docs source (not needed in image) ────────────────────────────────────────
+docs/
+mkdocs.yml
+
+# ── dev / CI files ───────────────────────────────────────────────────────────
+.github/
+tests/
+*.md
+!README.md
+docker/

assgen-0.3.0/.github/copilot-instructions.md

@@ -0,0 +1,8 @@
+
+## Documentation
+
+When creating documentation files:
+
+- Place them in the `docs/` directory or a subdirectory. Typical subdirectories include `docs/design/` and `docs/research/`.
+- Prepend a UTC timestamp to the `.md` filename in the format `YYYYMMDD_HHMMSS_UTC_` so files sort chronologically (e.g., `docs/design/20260329_150800_UTC_architecture_overview.md`).
+

assgen-0.3.0/.github/hooks/hooks.json

@@ -0,0 +1,29 @@
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [
+      {
+        "type": "command",
+        "bash": "bash ~/.claude/hooks/peon-ping/adapters/copilot.sh sessionStart"
+      }
+    ],
+    "userPromptSubmitted": [
+      {
+        "type": "command",
+        "bash": "bash ~/.claude/hooks/peon-ping/adapters/copilot.sh userPromptSubmitted"
+      }
+    ],
+    "postToolUse": [
+      {
+        "type": "command",
+        "bash": "bash ~/.claude/hooks/peon-ping/adapters/copilot.sh postToolUse"
+      }
+    ],
+    "errorOccurred": [
+      {
+        "type": "command",
+        "bash": "bash ~/.claude/hooks/peon-ping/adapters/copilot.sh errorOccurred"
+      }
+    ]
+  }
+}

assgen-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,92 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  lint-and-test:
+    name: Lint & Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install dev dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: ruff check src/ tests/
+
+      - name: Check OpenAPI spec is up to date
+        run: python scripts/export_openapi.py --check
+
+      - name: Run tests
+        run: pytest -v --tb=short -q -m "not integration"
+
+  hf-integration:
+    name: HuggingFace Integration Tests
+    runs-on: ubuntu-latest
+    # Only run on pushes to main (not every PR) to avoid hammering HF API
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: lint-and-test
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install dev dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run HuggingFace integration tests
+        run: pytest -v --tb=short -m integration tests/test_hf_integration.py
+
+  docker-build:
+    name: Docker Build (smoke test)
+    runs-on: ubuntu-latest
+    needs: lint-and-test
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build server image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: docker/Dockerfile.server
+          push: false
+          build-args: VERSION=0.0.0.dev0
+          tags: assgen-server:ci
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: Build client image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: docker/Dockerfile.client
+          push: false
+          build-args: VERSION=0.0.0.dev0
+          tags: assgen-client:ci
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

assgen-0.3.0/.github/workflows/docs.yml

@@ -0,0 +1,50 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    name: Build & Deploy Docs
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install package + docs dependencies
+        run: pip install -e ".[docs]"
+
+      - name: Build docs
+        run: mkdocs build --strict --site-dir site
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+      - name: Deploy to GitHub Pages
+        id: deploy
+        uses: actions/deploy-pages@v4

assgen-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,429 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"        # strict semver: v1.2.3
+      - "v[0-9]+.[0-9]+.[0-9]+-*"      # pre-releases: v1.2.3-rc.1, v1.2.3-beta.1
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+  packages: write   # needed to push Docker images to ghcr.io
+
+# ---------------------------------------------------------------------------
+# Validate the tag is proper semver before we do any real work.
+# A typo like "v0.1" will abort here rather than produce a broken release.
+# ---------------------------------------------------------------------------
+jobs:
+  validate-tag:
+    name: Validate semver tag
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check tag format
+        run: |
+          TAG="${GITHUB_REF_NAME}"
+          if ! echo "$TAG" | grep -qE '^v[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$'; then
+            echo "ERROR: Tag '$TAG' is not valid semver (expected vMAJOR.MINOR.PATCH[-prerelease])"
+            exit 1
+          fi
+          echo "Tag '$TAG' is valid semver ✓"
+
+  # ---------------------------------------------------------------------------
+  # Build wheel + sdist, run tests, build and attach docs
+  # ---------------------------------------------------------------------------
+  release:
+    name: Build & Publish Release
+    runs-on: ubuntu-latest
+    needs: validate-tag
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0   # needed so hatch-vcs can read all tags
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install dev + build + docs dependencies
+        run: pip install -e ".[dev,docs]" hatch
+
+      - name: Lint with ruff
+        run: ruff check src/ tests/
+
+      - name: Run tests
+        run: pytest -v --tb=short -m "not integration"
+
+      - name: Build distribution packages
+        run: hatch build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          # Uses Trusted Publishing (OIDC) — no API token needed.
+          # One-time setup: pypi.org → your project → Publishing → add GitHub publisher:
+          #   Owner: aallbrig   Repo: assgen   Workflow: release.yml   Environment: (blank)
+          skip-existing: true
+
+      - name: Build docs site
+        run: mkdocs build --strict
+
+      - name: Zip docs
+        run: |
+          VERSION="${{ github.ref_name }}"
+          zip -r "assgen-docs-${VERSION}.zip" site/
+
+      - name: Upload to GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            dist/*
+            assgen-docs-*.zip
+          generate_release_notes: true
+          body: |
+            ## assgen ${{ github.ref_name }}
+
+            ### Install via pip
+            ```bash
+            pip install assgen==${{ github.ref_name }}
+            ```
+
+            Or use the upgrade command if you already have assgen installed:
+            ```bash
+            assgen upgrade
+            ```
+
+            ### Standalone binaries
+            Grab the pre-built binary for your platform from the assets below —
+            no Python installation required.
+
+            | Platform | File |
+            |---|---|
+            | Windows (x64) | `assgen-${{ github.ref_name }}-windows-x64.exe` |
+            | Linux (x64)   | `assgen-${{ github.ref_name }}-linux-x64` |
+            | macOS (x64)   | `assgen-${{ github.ref_name }}-macos-x64` |
+
+            ### Install via Homebrew (macOS / Linux)
+            ```bash
+            brew install aallbrig/tap/assgen
+            ```
+
+            ### Install via Chocolatey (Windows)
+            ```powershell
+            choco install assgen
+            ```
+
+            ### Docker (server)
+            ```bash
+            docker pull ghcr.io/${{ github.repository_owner }}/assgen-server:${{ github.ref_name }}
+            ```
+
+            See the [README](https://github.com/${{ github.repository }}/blob/main/README.md)
+            for full usage documentation.  Offline docs are attached as
+            `assgen-docs-${{ github.ref_name }}.zip`.
+
+  # ---------------------------------------------------------------------------
+  # Build standalone client binaries with PyInstaller
+  # ---------------------------------------------------------------------------
+  binaries:
+    name: Build binary (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    needs: validate-tag
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            artifact_name: assgen
+            asset_suffix: linux-x64
+          - os: windows-latest
+            artifact_name: assgen.exe
+            asset_suffix: windows-x64
+          - os: macos-latest
+            artifact_name: assgen
+            asset_suffix: macos-x64
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install package + PyInstaller
+        run: pip install -e "." pyinstaller
+
+      - name: Build standalone binary
+        run: pyinstaller pyinstaller/assgen-client.spec
+
+      - name: Rename artifact with platform suffix
+        shell: bash
+        run: |
+          VERSION="${{ github.ref_name }}"
+          mv dist/${{ matrix.artifact_name }} \
+             dist/assgen-${VERSION}-${{ matrix.asset_suffix }}${{ matrix.os == 'windows-latest' && '.exe' || '' }}
+
+      - name: Upload binary to GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/assgen-${{ github.ref_name }}-${{ matrix.asset_suffix }}${{ matrix.os == 'windows-latest' && '.exe' || '' }}
+
+  # ---------------------------------------------------------------------------
+  # Build & push Docker images with full semver tags
+  # ---------------------------------------------------------------------------
+  docker:
+    name: Build & Push Docker Images
+    runs-on: ubuntu-latest
+    needs: release
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract version (strip leading v)
+        id: ver
+        run: echo "version=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
+
+      # docker/metadata-action generates all semver tag variants automatically:
+      #   v1.2.3  → :1.2.3, :1.2, :1, :latest  (stable)
+      #   v1.2.3-rc.1 → :1.2.3-rc.1             (pre-release, no :latest)
+      - name: Generate Docker metadata — server
+        id: meta-server
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository_owner }}/assgen-server
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}},enable=${{ !startsWith(github.ref, 'refs/tags/v0.') }}
+            type=raw,value=latest,enable=${{ !contains(github.ref_name, '-') }}
+
+      - name: Generate Docker metadata — client
+        id: meta-client
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository_owner }}/assgen-client
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}},enable=${{ !startsWith(github.ref, 'refs/tags/v0.') }}
+            type=raw,value=latest,enable=${{ !contains(github.ref_name, '-') }}
+
+      - name: Build and push server image (CPU)
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: docker/Dockerfile.server
+          push: true
+          build-args: VERSION=${{ steps.ver.outputs.version }}
+          tags: ${{ steps.meta-server.outputs.tags }}
+          labels: ${{ steps.meta-server.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: Build and push client image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: docker/Dockerfile.client
+          push: true
+          build-args: VERSION=${{ steps.ver.outputs.version }}
+          tags: ${{ steps.meta-client.outputs.tags }}
+          labels: ${{ steps.meta-client.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+  # ---------------------------------------------------------------------------
+  # Update Homebrew tap formula with new release binaries
+  # ---------------------------------------------------------------------------
+  homebrew:
+    name: Update Homebrew Tap
+    runs-on: ubuntu-latest
+    needs: binaries
+    if: ${{ !contains(github.ref_name, '-') }}   # skip pre-releases
+
+    steps:
+      - name: Extract version (strip leading v)
+        id: ver
+        run: echo "version=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
+
+      - name: Download release binaries and compute SHA256
+        id: sha
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          VERSION="${{ github.ref_name }}"
+
+          gh release download "$VERSION" \
+            --repo "${{ github.repository }}" \
+            --pattern "assgen-${VERSION}-macos-x64" \
+            --pattern "assgen-${VERSION}-linux-x64" \
+            --dir .
+
+          echo "macos_x64=$(sha256sum "assgen-${VERSION}-macos-x64" | cut -d' ' -f1)" >> "$GITHUB_OUTPUT"
+          echo "linux_x64=$(sha256sum "assgen-${VERSION}-linux-x64" | cut -d' ' -f1)" >> "$GITHUB_OUTPUT"
+
+      - name: Checkout homebrew-tap
+        uses: actions/checkout@v4
+        with:
+          repository: aallbrig/homebrew-tap
+          token: ${{ secrets.HOMEBREW_TAP_TOKEN }}
+          path: homebrew-tap
+
+      - name: Write formula
+        run: |
+          VERSION="${{ steps.ver.outputs.version }}"
+          TAG="${{ github.ref_name }}"
+
+          cat > homebrew-tap/Formula/assgen.rb <<'RUBY'
+          class Assgen < Formula
+            desc "AI-driven game asset generation CLI"
+            homepage "https://github.com/aallbrig/assgen"
+            version "VERSION_PLACEHOLDER"
+            license "MIT"
+
+            on_macos do
+              on_intel do
+                url "https://github.com/aallbrig/assgen/releases/download/TAG_PLACEHOLDER/assgen-TAG_PLACEHOLDER-macos-x64"
+                sha256 "MACOS_X64_SHA_PLACEHOLDER"
+              end
+            end
+
+            on_linux do
+              on_intel do
+                url "https://github.com/aallbrig/assgen/releases/download/TAG_PLACEHOLDER/assgen-TAG_PLACEHOLDER-linux-x64"
+                sha256 "LINUX_X64_SHA_PLACEHOLDER"
+              end
+            end
+
+            def install
+              binary = Dir["assgen-*"].first || "assgen"
+              bin.install binary => "assgen"
+            end
+
+            test do
+              assert_match version.to_s, shell_output("#{bin}/assgen --version")
+            end
+          end
+          RUBY
+
+          # Strip leading whitespace from heredoc (GitHub Actions indentation)
+          sed -i 's/^          //' homebrew-tap/Formula/assgen.rb
+
+          # Replace placeholders
+          sed -i "s|VERSION_PLACEHOLDER|${VERSION}|g" homebrew-tap/Formula/assgen.rb
+          sed -i "s|TAG_PLACEHOLDER|${TAG}|g" homebrew-tap/Formula/assgen.rb
+          sed -i "s|MACOS_X64_SHA_PLACEHOLDER|${{ steps.sha.outputs.macos_x64 }}|g" homebrew-tap/Formula/assgen.rb
+          sed -i "s|LINUX_X64_SHA_PLACEHOLDER|${{ steps.sha.outputs.linux_x64 }}|g" homebrew-tap/Formula/assgen.rb
+
+      - name: Commit and push formula
+        working-directory: homebrew-tap
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add Formula/assgen.rb
+          git commit -m "assgen ${{ github.ref_name }}"
+          git push
+
+  # ---------------------------------------------------------------------------
+  # Publish Chocolatey package for Windows
+  # ---------------------------------------------------------------------------
+  chocolatey:
+    name: Publish Chocolatey Package
+    runs-on: windows-latest
+    needs: binaries
+    if: ${{ !contains(github.ref_name, '-') }}   # skip pre-releases
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          sparse-checkout: choco
+
+      - name: Extract version (strip leading v)
+        id: ver
+        shell: bash
+        run: echo "version=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
+
+      - name: Download Windows binary and compute checksum
+        id: sha
+        shell: bash
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          VERSION="${{ github.ref_name }}"
+          gh release download "$VERSION" \
+            --repo "${{ github.repository }}" \
+            --pattern "assgen-${VERSION}-windows-x64.exe" \
+            --dir .
+          echo "win_x64=$(sha256sum "assgen-${VERSION}-windows-x64.exe" | cut -d' ' -f1)" >> "$GITHUB_OUTPUT"
+
+      - name: Stamp nuspec and install script
+        shell: bash
+        run: |
+          VERSION="${{ steps.ver.outputs.version }}"
+          TAG="${{ github.ref_name }}"
+          SHA="${{ steps.sha.outputs.win_x64 }}"
+
+          sed -i "s|{{VERSION}}|${VERSION}|g" choco/assgen.nuspec
+          sed -i "s|{{TAG}}|${TAG}|g"         choco/tools/chocolateyinstall.ps1
+          sed -i "s|{{CHECKSUM}}|${SHA}|g"    choco/tools/chocolateyinstall.ps1
+
+      - name: Pack and push
+        shell: powershell
+        run: |
+          choco pack choco/assgen.nuspec --output-directory .
+          choco push assgen.${{ steps.ver.outputs.version }}.nupkg `
+            --source https://push.chocolatey.org/ `
+            --api-key ${{ secrets.CHOCOLATEY_API_KEY }}
+
+
+
+  # ---------------------------------------------------------------------------
+  # Sync HuggingFace Spaces on stable releases (not pre-releases)
+  # ---------------------------------------------------------------------------
+  spaces-sync:
+    name: Sync HuggingFace Spaces
+    runs-on: ubuntu-latest
+    needs: release          # wait for PyPI publish to complete first
+    if: ${{ !contains(github.ref_name, '-') }}   # skip pre-releases
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install HF CLI
+        run: pip install "huggingface_hub[cli]>=0.23"
+
+      - name: Authenticate HF CLI
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: hf login --token "$HF_TOKEN"
+
+      - name: Sync all Spaces
+        env:
+          VERSION: ${{ github.ref_name }}
+        run: python scripts/sync_spaces.py --version "$VERSION"

assgen-0.3.0/.gitignore

@@ -0,0 +1,57 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# hatch / build
+.hatch/
+*.dist-info/
+
+# Version file — generated by hatch-vcs at build/install time
+src/assgen/_version.py
+
+# IDE
+.vscode/
+# Ignore all of .idea except run configurations, which are checked in for developer convenience
+.idea/*
+!.idea/runConfigurations/
+.idea/runConfigurations/*
+!.idea/runConfigurations/*.xml
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Ruff
+.ruff_cache/
+
+# Local dev overrides
+*.local.yaml
+*.local.toml
+
+# VHS demo segments (intermediate recordings)
+demos/segments/
+
+# MkDocs built site
+site/
+heightmap*.png