gameship 0.1.0__tar.gz

gameship-0.1.0/LICENSE

@@ -0,0 +1,110 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2026 Neuroforge
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gameship-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: gameship
+Version: 0.1.0
+Summary: Ship your Python game: one command to per-OS builds and itch.io
+License: FSL-1.1-MIT
+Project-URL: Homepage, https://github.com/Neuroforge/gameship
+Keywords: pygame,packaging,itch.io,pyinstaller,game
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Neuroforge/gameship/main/docs/logo.png" alt="gameship" width="480">
+</p>
+
+<p align="center">
+  <a href="https://github.com/Neuroforge/gameship/actions/workflows/ci.yml"><img src="https://github.com/Neuroforge/gameship/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://pypi.org/project/gameship/"><img src="https://img.shields.io/pypi/v/gameship" alt="PyPI"></a>
+  <img src="https://img.shields.io/pypi/pyversions/gameship" alt="Python versions">
+  <img src="https://img.shields.io/badge/license-FSL--1.1--MIT-blue.svg" alt="License: FSL-1.1-MIT">
+</p>
+
+**Ship your Python game.** One command from a pygame project to real
+Windows / macOS / Linux builds and an itch.io release — the workflow every
+Python gamedev currently hand-rolls from PyInstaller + GitHub Actions + butler
+blog posts, packaged.
+
+```bash
+pip install gameship pyinstaller
+
+gameship build                # freeze this OS's build   -> dist/<platform>/
+gameship push you/your-game   # publish to itch.io (butler auto-installed)
+gameship ci                   # write the 3-OS GitHub Actions workflow
+gameship web                  # browser build via pygbag (pygame-ce)
+```
+
+## Why
+
+Python gamedevs are great at game code and stuck on the last mile: a real
+double-clickable app for people who don't have Python, built for all three
+OSes, uploaded to itch.io. The tools all exist — PyInstaller can't
+cross-compile so you need per-OS builders, butler is scriptable but manual,
+the GitHub Actions matrix is a blog-post ritual. gameship glues them so you
+never think about it:
+
+- **`gameship build`** — detects your entry point (`main.py`) and `assets/`
+  folder, names the app from your `pyproject.toml` or folder, runs PyInstaller
+  windowed, outputs to `dist/<platform>/`.
+- **`gameship ci`** — drops a ready GitHub Actions workflow: every `v*` tag
+  builds Windows + macOS + Linux in parallel and uploads artifacts. Add a
+  `BUTLER_API_KEY` secret and an `ITCH_TARGET` variable and it also publishes
+  each build to the right itch.io channel.
+- **`gameship push`** — wraps [butler](https://itch.io/docs/butler/), itch.io's
+  official CLI (downloads it on first use), so local pushes are one line too.
+- **`gameship web`** — wraps [pygbag](https://pygame-web.github.io/) for a
+  browser build you can host on itch.io's HTML5 player (pygame-ce projects
+  with an async main loop).
+
+## Quick start (60 seconds, local)
+
+```bash
+cd your-game/          # has a main.py that runs your game
+pip install gameship pyinstaller
+gameship build
+open "dist/mac/YourGame.app"        # or dist/windows/, dist/linux/
+```
+
+## Full release pipeline (10 minutes, once)
+
+```bash
+gameship ci
+git add .github && git commit -m "release workflow" && git push
+# GitHub repo -> Settings -> Secrets -> Actions: BUTLER_API_KEY (from itch.io)
+# GitHub repo -> Settings -> Variables -> Actions: ITCH_TARGET=you/your-game
+git tag v1.0 && git push --tags
+```
+
+Three OS builds appear as artifacts; each pushes to `you/your-game:windows`,
+`:mac`, `:linux` on itch.io. Delta uploads, versioned channels — butler's
+whole feature set, none of its setup.
+
+## Honest limitations (v0)
+
+- PyInstaller quirks are inherited: Windows Defender sometimes flags frozen
+  Python apps (code-signing fixes it; on the roadmap), and asset paths inside
+  the bundle should be loaded relative to your script, not the cwd.
+- `gameship web` requires pygame-ce and an async-ified main loop — that's a
+  [pygbag rule](https://pygame-web.github.io/wiki/pygbag/), not ours; we warn
+  rather than rewrite your code.
+- macOS builds are unsigned/un-notarized (players right-click > Open). Signing
+  + notarization service is the roadmap item after this one.
+- Steam/Epic: not yet. itch.io first, on purpose.
+
+## Example
+
+[`example/`](example/) is a complete 60-line pygame catcher — the repo's CI
+builds it on all three OSes and smoke-runs the frozen binary headless
+(`SDL_VIDEODRIVER=dummy GAMESHIP_MAX_FRAMES=120`).
+
+## Common questions this answers
+
+**How do I turn my pygame game into an .exe?** `gameship build` on a Windows
+machine (or let the generated workflow's Windows runner do it) — PyInstaller
+under the hood, no spec file to write.
+
+**How do I make a Mac .app from a pygame game?** Same command on macOS:
+`gameship build` → `dist/mac/YourGame.app`.
+
+**How do I upload a pygame game to itch.io automatically?** `gameship push
+you/your-game` locally, or add the `BUTLER_API_KEY` secret so every tagged
+release publishes to your itch channels from CI.
+
+**How do I build my game for Windows, Mac, and Linux at once?** You can't
+cross-compile Python — nobody can — so `gameship ci` writes the GitHub
+Actions matrix that builds natively on all three, free on public repos.
+
+**Is gameship open source?** Source-available under FSL-1.1-MIT: free for
+any use except reselling gameship itself as a service, and each release
+converts to plain MIT after two years. Games built with it are entirely
+unaffected — they're yours.
+
+**Can my pygame game run in the browser?** If it's pygame-ce with an async
+main loop: `gameship web` (pygbag), then upload the build as an itch.io HTML5
+game.
+
+## Development
+
+```bash
+pip install -e . pytest
+pytest            # unit tests (pure logic, no PyInstaller needed)
+```
+
+The [CI](.github/workflows/ci.yml) dogfoods the tool: every push runs the
+tests on Python 3.11–3.13 and builds + headless-smoke-runs the example game
+on Windows, macOS, and Linux **with gameship itself**.
+
+## License
+
+**[FSL-1.1-MIT](https://github.com/Neuroforge/gameship/blob/main/LICENSE)** (Functional Source License), which in plain words means:
+
+- **Your games are yours.** Build them, sell them, ship them anywhere —
+  commercial use of gameship *for making things* is unrestricted, and nothing
+  about the license touches your game or its builds.
+- **The one thing you can't do** is offer gameship itself as a competing
+  product or service (e.g. a hosted build-your-game SaaS) — that lane funds
+  the tool's maintenance.
+- **Every release automatically becomes plain MIT two years after its
+  publication.** No takebacks, it's in the license text.
+
+Assets: none — the example uses shapes, and the logo is original.

gameship-0.1.0/README.md

@@ -0,0 +1,139 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Neuroforge/gameship/main/docs/logo.png" alt="gameship" width="480">
+</p>
+
+<p align="center">
+  <a href="https://github.com/Neuroforge/gameship/actions/workflows/ci.yml"><img src="https://github.com/Neuroforge/gameship/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://pypi.org/project/gameship/"><img src="https://img.shields.io/pypi/v/gameship" alt="PyPI"></a>
+  <img src="https://img.shields.io/pypi/pyversions/gameship" alt="Python versions">
+  <img src="https://img.shields.io/badge/license-FSL--1.1--MIT-blue.svg" alt="License: FSL-1.1-MIT">
+</p>
+
+**Ship your Python game.** One command from a pygame project to real
+Windows / macOS / Linux builds and an itch.io release — the workflow every
+Python gamedev currently hand-rolls from PyInstaller + GitHub Actions + butler
+blog posts, packaged.
+
+```bash
+pip install gameship pyinstaller
+
+gameship build                # freeze this OS's build   -> dist/<platform>/
+gameship push you/your-game   # publish to itch.io (butler auto-installed)
+gameship ci                   # write the 3-OS GitHub Actions workflow
+gameship web                  # browser build via pygbag (pygame-ce)
+```
+
+## Why
+
+Python gamedevs are great at game code and stuck on the last mile: a real
+double-clickable app for people who don't have Python, built for all three
+OSes, uploaded to itch.io. The tools all exist — PyInstaller can't
+cross-compile so you need per-OS builders, butler is scriptable but manual,
+the GitHub Actions matrix is a blog-post ritual. gameship glues them so you
+never think about it:
+
+- **`gameship build`** — detects your entry point (`main.py`) and `assets/`
+  folder, names the app from your `pyproject.toml` or folder, runs PyInstaller
+  windowed, outputs to `dist/<platform>/`.
+- **`gameship ci`** — drops a ready GitHub Actions workflow: every `v*` tag
+  builds Windows + macOS + Linux in parallel and uploads artifacts. Add a
+  `BUTLER_API_KEY` secret and an `ITCH_TARGET` variable and it also publishes
+  each build to the right itch.io channel.
+- **`gameship push`** — wraps [butler](https://itch.io/docs/butler/), itch.io's
+  official CLI (downloads it on first use), so local pushes are one line too.
+- **`gameship web`** — wraps [pygbag](https://pygame-web.github.io/) for a
+  browser build you can host on itch.io's HTML5 player (pygame-ce projects
+  with an async main loop).
+
+## Quick start (60 seconds, local)
+
+```bash
+cd your-game/          # has a main.py that runs your game
+pip install gameship pyinstaller
+gameship build
+open "dist/mac/YourGame.app"        # or dist/windows/, dist/linux/
+```
+
+## Full release pipeline (10 minutes, once)
+
+```bash
+gameship ci
+git add .github && git commit -m "release workflow" && git push
+# GitHub repo -> Settings -> Secrets -> Actions: BUTLER_API_KEY (from itch.io)
+# GitHub repo -> Settings -> Variables -> Actions: ITCH_TARGET=you/your-game
+git tag v1.0 && git push --tags
+```
+
+Three OS builds appear as artifacts; each pushes to `you/your-game:windows`,
+`:mac`, `:linux` on itch.io. Delta uploads, versioned channels — butler's
+whole feature set, none of its setup.
+
+## Honest limitations (v0)
+
+- PyInstaller quirks are inherited: Windows Defender sometimes flags frozen
+  Python apps (code-signing fixes it; on the roadmap), and asset paths inside
+  the bundle should be loaded relative to your script, not the cwd.
+- `gameship web` requires pygame-ce and an async-ified main loop — that's a
+  [pygbag rule](https://pygame-web.github.io/wiki/pygbag/), not ours; we warn
+  rather than rewrite your code.
+- macOS builds are unsigned/un-notarized (players right-click > Open). Signing
+  + notarization service is the roadmap item after this one.
+- Steam/Epic: not yet. itch.io first, on purpose.
+
+## Example
+
+[`example/`](example/) is a complete 60-line pygame catcher — the repo's CI
+builds it on all three OSes and smoke-runs the frozen binary headless
+(`SDL_VIDEODRIVER=dummy GAMESHIP_MAX_FRAMES=120`).
+
+## Common questions this answers
+
+**How do I turn my pygame game into an .exe?** `gameship build` on a Windows
+machine (or let the generated workflow's Windows runner do it) — PyInstaller
+under the hood, no spec file to write.
+
+**How do I make a Mac .app from a pygame game?** Same command on macOS:
+`gameship build` → `dist/mac/YourGame.app`.
+
+**How do I upload a pygame game to itch.io automatically?** `gameship push
+you/your-game` locally, or add the `BUTLER_API_KEY` secret so every tagged
+release publishes to your itch channels from CI.
+
+**How do I build my game for Windows, Mac, and Linux at once?** You can't
+cross-compile Python — nobody can — so `gameship ci` writes the GitHub
+Actions matrix that builds natively on all three, free on public repos.
+
+**Is gameship open source?** Source-available under FSL-1.1-MIT: free for
+any use except reselling gameship itself as a service, and each release
+converts to plain MIT after two years. Games built with it are entirely
+unaffected — they're yours.
+
+**Can my pygame game run in the browser?** If it's pygame-ce with an async
+main loop: `gameship web` (pygbag), then upload the build as an itch.io HTML5
+game.
+
+## Development
+
+```bash
+pip install -e . pytest
+pytest            # unit tests (pure logic, no PyInstaller needed)
+```
+
+The [CI](.github/workflows/ci.yml) dogfoods the tool: every push runs the
+tests on Python 3.11–3.13 and builds + headless-smoke-runs the example game
+on Windows, macOS, and Linux **with gameship itself**.
+
+## License
+
+**[FSL-1.1-MIT](https://github.com/Neuroforge/gameship/blob/main/LICENSE)** (Functional Source License), which in plain words means:
+
+- **Your games are yours.** Build them, sell them, ship them anywhere —
+  commercial use of gameship *for making things* is unrestricted, and nothing
+  about the license touches your game or its builds.
+- **The one thing you can't do** is offer gameship itself as a competing
+  product or service (e.g. a hosted build-your-game SaaS) — that lane funds
+  the tool's maintenance.
+- **Every release automatically becomes plain MIT two years after its
+  publication.** No takebacks, it's in the license text.
+
+Assets: none — the example uses shapes, and the logo is original.

gameship-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gameship"
+version = "0.1.0"
+description = "Ship your Python game: one command to per-OS builds and itch.io"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "FSL-1.1-MIT" }
+keywords = ["pygame", "packaging", "itch.io", "pyinstaller", "game"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Topic :: Games/Entertainment",
+  "Topic :: Software Development :: Build Tools",
+]
+
+[project.urls]
+Homepage = "https://github.com/Neuroforge/gameship"
+
+[project.scripts]
+gameship = "gameship:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

gameship-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

gameship-0.1.0/src/gameship/__init__.py

@@ -0,0 +1,260 @@
+"""gameship — ship your Python game.
+
+One command from a pygame/pygame-ce (or any windowed Python) project to
+per-OS distributables and an itch.io release:
+
+    gameship build              # freeze with PyInstaller -> dist/<platform>/
+    gameship push user/game     # butler push to itch.io (auto-installs butler)
+    gameship web                # pygbag -> browser build (pygame-ce only)
+    gameship ci                 # write the 3-OS GitHub Actions workflow
+
+Zero config: entry point, name, and assets are detected; flags override.
+"""
+import argparse
+import os
+import platform
+import shutil
+import subprocess
+import sys
+import urllib.request
+import zipfile
+from pathlib import Path
+
+__version__ = "0.1.0"
+
+PLATFORM = {"darwin": "mac", "win32": "windows"}.get(sys.platform, "linux")
+BUTLER_URL = (
+    "https://broth.itch.zone/butler/{os}-amd64/LATEST/archive/default".format(
+        os={"mac": "darwin", "windows": "windows"}.get(PLATFORM, "linux")
+    )
+)
+
+
+def die(msg: str) -> "None":
+    print(f"gameship: {msg}", file=sys.stderr)
+    sys.exit(1)
+
+
+def find_entry(root: Path, explicit: str | None) -> Path:
+    if explicit:
+        p = root / explicit
+        if not p.exists():
+            die(f"entry file not found: {p}")
+        return p
+    for name in ("main.py", "game.py", "run_game.py"):
+        if (root / name).exists():
+            return root / name
+    candidates = [p for p in root.glob("*.py") if not p.name.startswith("_")]
+    if len(candidates) == 1:
+        return candidates[0]
+    die(
+        f"couldn't pick an entry point in {root} — found "
+        f"{[c.name for c in candidates] or 'no .py files'}. "
+        "Name it main.py or pass --entry FILE."
+    )
+
+
+def game_name(root: Path, explicit: str | None) -> str:
+    if explicit:
+        return explicit
+    pyproject = root / "pyproject.toml"
+    if pyproject.exists():
+        import tomllib
+
+        try:
+            name = tomllib.loads(pyproject.read_text()).get("project", {}).get("name")
+            if name:
+                return name
+        except tomllib.TOMLDecodeError:
+            pass
+    return root.resolve().name
+
+
+def build(args) -> None:
+    root = Path(args.path)
+    if not root.is_dir():
+        die(f"not a directory: {root}")
+    entry = find_entry(root, args.entry)
+    name = game_name(root, args.name)
+    dist = Path(args.dist or (root / "dist" / PLATFORM)).resolve()
+    work = dist.parent / ".gameship-work"
+
+    cmd = [
+        sys.executable, "-m", "PyInstaller",
+        "--noconfirm", "--windowed", "--name", name,
+        "--distpath", str(dist), "--workpath", str(work),
+        "--specpath", str(work),
+    ]
+    sep = ";" if PLATFORM == "windows" else ":"
+    for adir in ("assets", "data", "resources"):
+        if (root / adir).is_dir():
+            cmd += ["--add-data", f"{root / adir}{sep}{adir}"]
+    if args.onefile:
+        cmd.append("--onefile")
+    cmd.append(str(entry))
+
+    print(f"gameship: building '{name}' from {entry.name} for {PLATFORM}")
+    try:
+        subprocess.run(cmd, check=True)
+    except FileNotFoundError:
+        die("PyInstaller not found — pip install pyinstaller")
+    except subprocess.CalledProcessError as e:
+        die(f"PyInstaller failed (exit {e.returncode})")
+    shutil.rmtree(work, ignore_errors=True)
+    print(f"gameship: done -> {dist}")
+    print("gameship: note — bundled asset paths resolve relative to the exe; "
+          "load files relative to __file__ or sys._MEIPASS-aware helpers.")
+
+
+def butler_bin() -> str:
+    found = shutil.which("butler")
+    if found:
+        return found
+    cache = Path.home() / ".cache" / "gameship"
+    exe = cache / ("butler.exe" if PLATFORM == "windows" else "butler")
+    if exe.exists():
+        return str(exe)
+    cache.mkdir(parents=True, exist_ok=True)
+    zip_path = cache / "butler.zip"
+    print(f"gameship: fetching butler ({BUTLER_URL})")
+    urllib.request.urlretrieve(BUTLER_URL, zip_path)
+    with zipfile.ZipFile(zip_path) as z:
+        z.extractall(cache)
+    zip_path.unlink()
+    exe.chmod(0o755)
+    return str(exe)
+
+
+def push(args) -> None:
+    if "/" not in args.target:
+        die("target must be user/game (your itch.io username/project slug)")
+    dist = Path(args.path or f"dist/{PLATFORM}")
+    if not dist.is_dir():
+        die(f"no build at {dist} — run `gameship build` first")
+    if not os.environ.get("BUTLER_API_KEY"):
+        die("BUTLER_API_KEY not set — get one at https://itch.io/user/settings/api-keys")
+    channel = args.channel or PLATFORM
+    cmd = [butler_bin(), "push", str(dist), f"{args.target}:{channel}"]
+    if args.userversion:
+        cmd += ["--userversion", args.userversion]
+    print("gameship:", " ".join(cmd))
+    subprocess.run(cmd, check=True)
+
+
+def web(args) -> None:
+    root = Path(args.path)
+    entry = find_entry(root, args.entry)
+    try:
+        import pygame  # noqa: F401
+
+        if not getattr(pygame, "IS_CE", False):
+            print(
+                "gameship: warning — pygbag supports pygame-ce, not classic pygame "
+                "(pip install pygame-ce). Also: your main loop must be async "
+                "(https://pygame-web.github.io/wiki/pygbag/). Continuing anyway."
+            )
+    except ImportError:
+        pass
+    try:
+        subprocess.run(
+            [sys.executable, "-m", "pygbag", "--build", str(entry.parent)], check=True
+        )
+    except FileNotFoundError:
+        die("pygbag not found — pip install pygbag")
+    except subprocess.CalledProcessError as e:
+        die(f"pygbag failed (exit {e.returncode})")
+    print(f"gameship: web build -> {entry.parent / 'build' / 'web'}")
+
+
+WORKFLOW = """\
+# Made by `gameship ci` — builds your game for Windows/macOS/Linux on every
+# version tag (and by hand from the Actions tab). To also publish to itch.io:
+#   1. repo Settings > Secrets > Actions: add BUTLER_API_KEY
+#   2. repo Settings > Variables > Actions: add ITCH_TARGET = youruser/your-game
+name: gameship
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  build:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { os: ubuntu-latest,  channel: linux }
+          - { os: windows-latest, channel: windows }
+          - { os: macos-latest,   channel: mac }
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - name: install game deps
+        shell: bash
+        run: |
+          pip install pyinstaller gameship
+          [ -f requirements.txt ] && pip install -r requirements.txt || pip install pygame-ce
+      - run: gameship build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: game-${{ matrix.channel }}
+          path: dist/
+      - name: publish to itch.io
+        if: ${{ env.KEY != '' && vars.ITCH_TARGET != '' }}
+        shell: bash
+        env:
+          KEY: ${{ secrets.BUTLER_API_KEY }}
+          BUTLER_API_KEY: ${{ secrets.BUTLER_API_KEY }}
+        run: gameship push "${{ vars.ITCH_TARGET }}" --channel "${{ matrix.channel }}"
+"""
+
+
+def ci(args) -> None:
+    out = Path(args.path) / ".github" / "workflows" / "gameship.yml"
+    if out.exists() and not args.force:
+        die(f"{out} exists — pass --force to overwrite")
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(WORKFLOW)
+    print(f"gameship: wrote {out}")
+    print("gameship: tag a release (git tag v1.0 && git push --tags) to build; "
+          "add BUTLER_API_KEY + ITCH_TARGET to publish.")
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(prog="gameship", description=__doc__.splitlines()[0])
+    ap.add_argument("--version", action="version", version=__version__)
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    b = sub.add_parser("build", help="freeze the game for this OS -> dist/<platform>/")
+    b.add_argument("path", nargs="?", default=".")
+    b.add_argument("--entry", help="entry .py (default: auto-detect main.py)")
+    b.add_argument("--name", help="app name (default: pyproject name or folder)")
+    b.add_argument("--dist", help="output dir (default: dist/<platform>)")
+    b.add_argument("--onefile", action="store_true", help="single-file binary")
+    b.set_defaults(fn=build)
+
+    p = sub.add_parser("push", help="push a build to itch.io via butler")
+    p.add_argument("target", help="itch.io user/game")
+    p.add_argument("path", nargs="?", help="build dir (default dist/<platform>)")
+    p.add_argument("--channel", help="itch channel (default: this platform)")
+    p.add_argument("--userversion", help="version string shown on itch")
+    p.set_defaults(fn=push)
+
+    w = sub.add_parser("web", help="browser build via pygbag (pygame-ce)")
+    w.add_argument("path", nargs="?", default=".")
+    w.add_argument("--entry")
+    w.set_defaults(fn=web)
+
+    c = sub.add_parser("ci", help="write the 3-OS GitHub Actions workflow")
+    c.add_argument("path", nargs="?", default=".")
+    c.add_argument("--force", action="store_true")
+    c.set_defaults(fn=ci)
+
+    args = ap.parse_args()
+    args.fn(args)
+
+
+if __name__ == "__main__":
+    main()

gameship-0.1.0/src/gameship.egg-info/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: gameship
+Version: 0.1.0
+Summary: Ship your Python game: one command to per-OS builds and itch.io
+License: FSL-1.1-MIT
+Project-URL: Homepage, https://github.com/Neuroforge/gameship
+Keywords: pygame,packaging,itch.io,pyinstaller,game
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Neuroforge/gameship/main/docs/logo.png" alt="gameship" width="480">
+</p>
+
+<p align="center">
+  <a href="https://github.com/Neuroforge/gameship/actions/workflows/ci.yml"><img src="https://github.com/Neuroforge/gameship/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://pypi.org/project/gameship/"><img src="https://img.shields.io/pypi/v/gameship" alt="PyPI"></a>
+  <img src="https://img.shields.io/pypi/pyversions/gameship" alt="Python versions">
+  <img src="https://img.shields.io/badge/license-FSL--1.1--MIT-blue.svg" alt="License: FSL-1.1-MIT">
+</p>
+
+**Ship your Python game.** One command from a pygame project to real
+Windows / macOS / Linux builds and an itch.io release — the workflow every
+Python gamedev currently hand-rolls from PyInstaller + GitHub Actions + butler
+blog posts, packaged.
+
+```bash
+pip install gameship pyinstaller
+
+gameship build                # freeze this OS's build   -> dist/<platform>/
+gameship push you/your-game   # publish to itch.io (butler auto-installed)
+gameship ci                   # write the 3-OS GitHub Actions workflow
+gameship web                  # browser build via pygbag (pygame-ce)
+```
+
+## Why
+
+Python gamedevs are great at game code and stuck on the last mile: a real
+double-clickable app for people who don't have Python, built for all three
+OSes, uploaded to itch.io. The tools all exist — PyInstaller can't
+cross-compile so you need per-OS builders, butler is scriptable but manual,
+the GitHub Actions matrix is a blog-post ritual. gameship glues them so you
+never think about it:
+
+- **`gameship build`** — detects your entry point (`main.py`) and `assets/`
+  folder, names the app from your `pyproject.toml` or folder, runs PyInstaller
+  windowed, outputs to `dist/<platform>/`.
+- **`gameship ci`** — drops a ready GitHub Actions workflow: every `v*` tag
+  builds Windows + macOS + Linux in parallel and uploads artifacts. Add a
+  `BUTLER_API_KEY` secret and an `ITCH_TARGET` variable and it also publishes
+  each build to the right itch.io channel.
+- **`gameship push`** — wraps [butler](https://itch.io/docs/butler/), itch.io's
+  official CLI (downloads it on first use), so local pushes are one line too.
+- **`gameship web`** — wraps [pygbag](https://pygame-web.github.io/) for a
+  browser build you can host on itch.io's HTML5 player (pygame-ce projects
+  with an async main loop).
+
+## Quick start (60 seconds, local)
+
+```bash
+cd your-game/          # has a main.py that runs your game
+pip install gameship pyinstaller
+gameship build
+open "dist/mac/YourGame.app"        # or dist/windows/, dist/linux/
+```
+
+## Full release pipeline (10 minutes, once)
+
+```bash
+gameship ci
+git add .github && git commit -m "release workflow" && git push
+# GitHub repo -> Settings -> Secrets -> Actions: BUTLER_API_KEY (from itch.io)
+# GitHub repo -> Settings -> Variables -> Actions: ITCH_TARGET=you/your-game
+git tag v1.0 && git push --tags
+```
+
+Three OS builds appear as artifacts; each pushes to `you/your-game:windows`,
+`:mac`, `:linux` on itch.io. Delta uploads, versioned channels — butler's
+whole feature set, none of its setup.
+
+## Honest limitations (v0)
+
+- PyInstaller quirks are inherited: Windows Defender sometimes flags frozen
+  Python apps (code-signing fixes it; on the roadmap), and asset paths inside
+  the bundle should be loaded relative to your script, not the cwd.
+- `gameship web` requires pygame-ce and an async-ified main loop — that's a
+  [pygbag rule](https://pygame-web.github.io/wiki/pygbag/), not ours; we warn
+  rather than rewrite your code.
+- macOS builds are unsigned/un-notarized (players right-click > Open). Signing
+  + notarization service is the roadmap item after this one.
+- Steam/Epic: not yet. itch.io first, on purpose.
+
+## Example
+
+[`example/`](example/) is a complete 60-line pygame catcher — the repo's CI
+builds it on all three OSes and smoke-runs the frozen binary headless
+(`SDL_VIDEODRIVER=dummy GAMESHIP_MAX_FRAMES=120`).
+
+## Common questions this answers
+
+**How do I turn my pygame game into an .exe?** `gameship build` on a Windows
+machine (or let the generated workflow's Windows runner do it) — PyInstaller
+under the hood, no spec file to write.
+
+**How do I make a Mac .app from a pygame game?** Same command on macOS:
+`gameship build` → `dist/mac/YourGame.app`.
+
+**How do I upload a pygame game to itch.io automatically?** `gameship push
+you/your-game` locally, or add the `BUTLER_API_KEY` secret so every tagged
+release publishes to your itch channels from CI.
+
+**How do I build my game for Windows, Mac, and Linux at once?** You can't
+cross-compile Python — nobody can — so `gameship ci` writes the GitHub
+Actions matrix that builds natively on all three, free on public repos.
+
+**Is gameship open source?** Source-available under FSL-1.1-MIT: free for
+any use except reselling gameship itself as a service, and each release
+converts to plain MIT after two years. Games built with it are entirely
+unaffected — they're yours.
+
+**Can my pygame game run in the browser?** If it's pygame-ce with an async
+main loop: `gameship web` (pygbag), then upload the build as an itch.io HTML5
+game.
+
+## Development
+
+```bash
+pip install -e . pytest
+pytest            # unit tests (pure logic, no PyInstaller needed)
+```
+
+The [CI](.github/workflows/ci.yml) dogfoods the tool: every push runs the
+tests on Python 3.11–3.13 and builds + headless-smoke-runs the example game
+on Windows, macOS, and Linux **with gameship itself**.
+
+## License
+
+**[FSL-1.1-MIT](https://github.com/Neuroforge/gameship/blob/main/LICENSE)** (Functional Source License), which in plain words means:
+
+- **Your games are yours.** Build them, sell them, ship them anywhere —
+  commercial use of gameship *for making things* is unrestricted, and nothing
+  about the license touches your game or its builds.
+- **The one thing you can't do** is offer gameship itself as a competing
+  product or service (e.g. a hosted build-your-game SaaS) — that lane funds
+  the tool's maintenance.
+- **Every release automatically becomes plain MIT two years after its
+  publication.** No takebacks, it's in the license text.
+
+Assets: none — the example uses shapes, and the logo is original.

gameship-0.1.0/src/gameship.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+src/gameship/__init__.py
+src/gameship.egg-info/PKG-INFO
+src/gameship.egg-info/SOURCES.txt
+src/gameship.egg-info/dependency_links.txt
+src/gameship.egg-info/entry_points.txt
+src/gameship.egg-info/top_level.txt
+tests/test_gameship.py

gameship-0.1.0/src/gameship.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

gameship-0.1.0/src/gameship.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+gameship = gameship:main

gameship-0.1.0/src/gameship.egg-info/top_level.txt

@@ -0,0 +1 @@
+gameship

gameship-0.1.0/tests/test_gameship.py

@@ -0,0 +1,89 @@
+"""Unit tests for gameship's pure logic (no PyInstaller/butler/network)."""
+import subprocess
+import sys
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+import gameship
+
+
+def test_version_flag():
+    with pytest.raises(SystemExit) as e:
+        sys.argv = ["gameship", "--version"]
+        gameship.main()
+    assert e.value.code == 0
+
+
+def test_find_entry_prefers_main(tmp_path):
+    (tmp_path / "main.py").touch()
+    (tmp_path / "other.py").touch()
+    assert gameship.find_entry(tmp_path, None).name == "main.py"
+
+
+def test_find_entry_single_candidate(tmp_path):
+    (tmp_path / "mygame.py").touch()
+    assert gameship.find_entry(tmp_path, None).name == "mygame.py"
+
+
+def test_find_entry_explicit_and_missing(tmp_path):
+    (tmp_path / "play.py").touch()
+    assert gameship.find_entry(tmp_path, "play.py").name == "play.py"
+    with pytest.raises(SystemExit):
+        gameship.find_entry(tmp_path, "nope.py")
+
+
+def test_find_entry_ambiguous_dies(tmp_path):
+    (tmp_path / "a.py").touch()
+    (tmp_path / "b.py").touch()
+    with pytest.raises(SystemExit):
+        gameship.find_entry(tmp_path, None)
+
+
+def test_game_name_sources(tmp_path):
+    assert gameship.game_name(tmp_path, "Explicit") == "Explicit"
+    (tmp_path / "pyproject.toml").write_text('[project]\nname = "toml-name"\n')
+    assert gameship.game_name(tmp_path, None) == "toml-name"
+    (tmp_path / "pyproject.toml").write_text("not [valid toml")
+    assert gameship.game_name(tmp_path, None) == tmp_path.resolve().name
+
+
+def test_build_command_construction(tmp_path, monkeypatch):
+    (tmp_path / "main.py").touch()
+    (tmp_path / "assets").mkdir()
+    seen = {}
+    monkeypatch.setattr(gameship.subprocess, "run", lambda cmd, check: seen.setdefault("cmd", cmd))
+    args = SimpleNamespace(path=str(tmp_path), entry=None, name="MyGame", dist=None, onefile=True)
+    gameship.build(args)
+    cmd = seen["cmd"]
+    assert "--windowed" in cmd and "--onefile" in cmd
+    assert cmd[cmd.index("--name") + 1] == "MyGame"
+    assert any(str(tmp_path / "assets") in c for c in cmd)  # --add-data wired
+
+
+def test_ci_writes_and_respects_force(tmp_path):
+    gameship.ci(SimpleNamespace(path=str(tmp_path), force=False))
+    wf = tmp_path / ".github" / "workflows" / "gameship.yml"
+    text = wf.read_text()
+    assert "windows-latest" in text and "macos-latest" in text and "ubuntu-latest" in text
+    assert "BUTLER_API_KEY" in text
+    with pytest.raises(SystemExit):
+        gameship.ci(SimpleNamespace(path=str(tmp_path), force=False))
+    gameship.ci(SimpleNamespace(path=str(tmp_path), force=True))  # no raise
+
+
+def test_push_validates_target_and_build_dir(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    with pytest.raises(SystemExit):
+        gameship.push(SimpleNamespace(target="no-slash", path=None, channel=None, userversion=None))
+    with pytest.raises(SystemExit):  # valid target, but no build dir
+        gameship.push(SimpleNamespace(target="user/game", path=None, channel=None, userversion=None))
+
+
+def test_cli_smoke():
+    out = subprocess.run(
+        [sys.executable, "-c", "import gameship; print(gameship.__version__)"],
+        capture_output=True, text=True, check=True,
+    )
+    assert out.stdout.strip() == gameship.__version__