modkeel 0.1.1__tar.gz

modkeel-0.1.1/.github/workflows/cli.yml

@@ -0,0 +1,53 @@
+# CLI checks: lint and the pytest suite on every Python version the package supports.
+# Runs in the lab and, mirrored by tools/publish_cli.py, in the public Modkeel/modkeel repo,
+# so it needs no secrets and only reads the repository.
+name: cli
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "modkeel/**"
+      - "tests/**"
+      - "mod_auto_compiler.py"
+      - "pyproject.toml"
+      - ".github/workflows/cli.yml"
+  pull_request:
+    paths:
+      - "modkeel/**"
+      - "tests/**"
+      - "mod_auto_compiler.py"
+      - "pyproject.toml"
+      - ".github/workflows/cli.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: cli-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # One job per Python version; ruff runs inside the 3.12 job instead of its own job.
+  # Pull requests test the oldest and newest supported Python (2 jobs); pushes to main and
+  # manual runs test every version. Fewer jobs per PR keeps several open PRs under the
+  # account's concurrent-job limit for GitHub-hosted runners.
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ${{ fromJSON(github.event_name == 'pull_request' && '["3.10", "3.12"]' || '["3.10", "3.11", "3.12"]') }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - run: pip install -e ".[dev]"
+      - name: Lint
+        if: matrix.python-version == '3.12'
+        run: ruff check modkeel tests
+      - run: python -m pytest tests/ -q

modkeel-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,92 @@
+# Release the CLI when a version tag (vX.Y.Z) reaches this repo: build the wheel and sdist
+# once, then create the GitHub Release (notes = the tag's message) and upload the same files
+# to PyPI. The tag is created by the maintainers' publishing job when the package version
+# changes; nobody pushes it by hand.
+#
+# PyPI uses trusted publishing (OIDC): no token is stored. The project on pypi.org trusts
+# this repository, this workflow file and the environment "pypi".
+name: release
+
+on:
+  push:
+    tags: ["v*.*.*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    if: github.repository == 'Modkeel/modkeel'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      # The tag and the package must agree, or the release would ship another version.
+      - name: Build
+        env:
+          TAG: ${{ github.ref_name }}
+        run: |
+          pip install build twine
+          python -m build
+          version=$(python -c "import re,pathlib;print(re.search(r'MODKEEL_VERSION = \"([^\"]+)\"', pathlib.Path('modkeel/constants.py').read_text())[1])")
+          if [ "v$version" != "$TAG" ]; then
+            echo "::error::tag $TAG does not match the package version $version"
+            exit 1
+          fi
+          twine check --strict dist/*
+          ls -l dist
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 7
+
+  github-release:
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      # actions/checkout leaves the tag as a plain ref; fetch the annotated tag to read its
+      # message: first line = title, the rest = notes.
+      - name: Create the release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ github.ref_name }}
+        run: |
+          git fetch --force origin "refs/tags/$TAG:refs/tags/$TAG"
+          git tag -l --format='%(contents:body)' "$TAG" > notes.md
+          title=$(git tag -l --format='%(contents:subject)' "$TAG")
+          gh release create "$TAG" dist/* --verify-tag --title "${title:-$TAG}" \
+            --notes-file notes.md
+
+  pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    environment:
+      name: pypi
+      url: https://pypi.org/project/modkeel/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@v1.12.4

modkeel-0.1.1/.gitignore

@@ -0,0 +1,49 @@
+# Secrets
+github_token.txt
+*.token
+.env
+.env.*
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+*:Zone.Identifier
+
+# ModForge specific
+compiled_mods/
+temp_repos/
+*.jar
+compilation_report*.txt
+out/
+*.log
+
+# Virtual environments
+venv/
+.venv/
+env/
+
+# Research caches
+research/.cache/
+research/.runtime/
+research/.overnight/
+research/.overnight.console
+
+# Modpack crawl: committed gzipped (packs_*.json.gz)
+research/packs_*.json
+research/.aeo/

modkeel-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,65 @@
+# Contributing to Modkeel
+
+## Development Setup
+
+```bash
+git clone https://github.com/Modkeel/modkeel.git
+cd modkeel
+pip install -e ".[dev]"   # the CLI plus pytest and ruff
+```
+
+## Running Tests and Lint
+
+```bash
+python3 -m pytest tests/ -q
+ruff check modkeel tests
+```
+
+Both must pass before submitting a PR. CI runs them on Python 3.10 and 3.12 for pull
+requests, and on 3.10, 3.11 and 3.12 for every push to `main`
+([`.github/workflows/cli.yml`](.github/workflows/cli.yml)).
+
+## Project Structure
+
+All new code goes into the `modkeel/` package. The root `mod_auto_compiler.py` is a deprecated shim -- do not modify it.
+
+The package is composition-based: `Pipeline` (`pipeline.py`) orchestrates one client per concern.
+
+| Module | Role |
+|--------|------|
+| `cli.py`, `commands/` | Typer app; one module per command: `compile`, `search`, `get`, `token`, `status`, `recommend` |
+| `pipeline.py` | Clone, compile, multi-pass dependency retry, Docker test, report |
+| `github.py`, `validation.py`, `buildinfo.py` | Fork discovery, branch scoring, reading build targets remotely |
+| `prebuild.py`, `symbols.py`, `mappings.py`, `javascan.py` | Skip builds whose outcome is knowable before cloning |
+| `linkage.py`, `memberlink.py`, `mixinscan.py` | Bytecode checks: does a JAR really target the requested version |
+| `build.py` | Gradle build and JAR validation |
+| `modrinth.py`, `recommend.py`, `scanner.py` | Modrinth lookups, mods-folder scanning, version/loader recommendations |
+| `docker.py` | Headless server boot test |
+| `loaders.py`, `version.py`, `models.py`, `config.py` | Loader data, version ranges, data classes, user config |
+
+Tests patch `modkeel.<module>.<object>`, never the deprecated shim.
+
+## Code Style
+
+- **Python 3.10+** target
+- **100 character** line length
+- **Type hints** on all public functions
+- `snake_case` for functions/variables, `PascalCase` for classes, `UPPER_SNAKE_CASE` for constants
+- All code, comments, docstrings, and error messages in **English**
+
+## Pull Request Guidelines
+
+1. Create a feature branch from `main`
+2. Use [conventional commits](https://www.conventionalcommits.org/): `feat:`, `fix:`, `refactor:`, `docs:`, `test:`
+3. Ensure tests and lint pass (`pytest tests/ -q`, `ruff check modkeel tests`)
+4. Keep PRs focused -- one feature or fix per PR
+
+## Reporting Issues
+
+Open an issue at [github.com/Modkeel/modkeel/issues](https://github.com/Modkeel/modkeel/issues) with:
+
+- Modkeel version (`modkeel --version`)
+- Python version
+- OS and architecture
+- Steps to reproduce
+- Relevant log output (use `--log-file modkeel.log`)

modkeel-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Modkeel
+
+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.

modkeel-0.1.1/PKG-INFO

@@ -0,0 +1,268 @@
+Metadata-Version: 2.4
+Name: modkeel
+Version: 0.1.1
+Summary: Minecraft Mod Auto-Compiler - find, compile, and verify unofficial mod forks
+Author: Modkeel
+License-Expression: MIT
+License-File: LICENSE
+Keywords: compiler,fabric,forge,minecraft,mods,neoforge
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Games/Entertainment
+Requires-Python: >=3.10
+Requires-Dist: requests>=2.31.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: toml>=0.10.2
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff<0.17,>=0.15; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Modkeel
+
+> **Compile the mods Mojang left behind**
+
+![Python](https://img.shields.io/badge/python-3.10+-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+[![PyPI](https://img.shields.io/pypi/v/modkeel)](https://pypi.org/project/modkeel/)
+[![CI](https://github.com/Modkeel/modkeel/actions/workflows/cli.yml/badge.svg)](https://github.com/Modkeel/modkeel/actions/workflows/cli.yml)
+
+---
+
+Modkeel is a CLI tool that finds, compiles, and verifies unofficial Minecraft mod forks for versions the original authors don't support. When Mojang releases a patch version (like 1.21.10), major mods skip it -- but community forks exist on GitHub as uncompiled branches. Modkeel finds them, builds them, and validates the output.
+
+Playing the mods, not building them? The [Modkeel Companion](https://github.com/Modkeel/companion)
+mod backs up your worlds when your mods change and fixes crashes in one click.
+
+## Quick Start
+
+```bash
+pipx install modkeel        # or: pip install modkeel
+modkeel compile repos.txt -m 1.21.10 -l neoforge -lv 64 -t "$(cat github_token.txt)"
+```
+
+## Quick Demo
+
+### Search for a mod
+![modkeel search](https://raw.githubusercontent.com/Modkeel/modkeel/main/demo/search.gif)
+
+### Compile mods from a list
+![modkeel compile](https://raw.githubusercontent.com/Modkeel/modkeel/main/demo/compile.gif)
+
+### Check status
+![modkeel status](https://raw.githubusercontent.com/Modkeel/modkeel/main/demo/status.gif)
+
+> GIFs generated with [VHS](https://github.com/charmbracelet/vhs). See [`demo/README.md`](https://github.com/Modkeel/modkeel/blob/main/demo/README.md) to regenerate.
+
+## How It Works
+
+For each repository in your list, Modkeel runs:
+
+1. **Modrinth Check** -- Search for a pre-compiled JAR first (skip compilation if found)
+2. **Fork Discovery** -- Search GitHub for compatible forks and independent ports
+3. **Branch Scoring** -- Rank branches by version match, loader match, and freshness
+4. **Pre-validation** -- Check `gradle.properties` via GitHub API before cloning
+5. **Cross-loader Fallback** -- If no NeoForge match, try Fabric forks via Sinytra Connector
+6. **Compile** -- Clone, run `gradlew build`, validate output JAR
+7. **Multi-pass Dependencies** -- Retry failed mods with `mavenLocal()` after others succeed
+8. **Docker Testing** (opt-in) -- Boot a headless MC server to verify mods load
+
+## Requirements
+
+- **Python 3.10+**
+- **Git** (in PATH)
+- **JDK 17 or 21** (for Gradle compilation)
+- **Docker** (optional, for `--docker-test`)
+
+```bash
+python --version  # 3.10+
+git --version
+java -version     # 17 or 21
+```
+
+## Installation
+
+```bash
+pipx install modkeel        # isolated install of the `modkeel` command (recommended)
+pip install modkeel         # or into the current environment
+```
+
+From source, to work on Modkeel itself:
+
+```bash
+git clone https://github.com/Modkeel/modkeel.git
+cd modkeel
+pip install -e ".[dev]"
+```
+
+Releases and their notes: [GitHub Releases](https://github.com/Modkeel/modkeel/releases).
+
+## Usage
+
+### Compile Mods
+
+```bash
+modkeel compile repos.txt \
+  --mc-version 1.21.10 \
+  --loader neoforge \
+  --loader-version 64 \
+  --github-token "$(cat github_token.txt)"
+```
+
+### Compile and Install to Instance
+
+```bash
+modkeel compile repos.txt \
+  -m 1.21.10 -l neoforge -lv 64 \
+  --instance "/path/to/minecraft/instance" \
+  -t "$(cat github_token.txt)"
+```
+
+### Compile and Test in Docker
+
+```bash
+modkeel compile repos.txt \
+  -m 1.21.10 -l neoforge -lv 64 \
+  --docker-test \
+  -t "$(cat github_token.txt)"
+```
+
+### Search Without Compiling
+
+```bash
+modkeel search "Create" -m 1.21.10 -l neoforge -t "$(cat github_token.txt)"
+```
+
+### Get One Mod
+
+```bash
+modkeel get "Create" -m 1.21.10 -l neoforge -lv 21.10.64
+```
+
+`get` (and `search`, without downloading) tries, in order, and prints what it tried:
+
+1. The mod's official build for that Minecraft version.
+2. An official build for an older version of the same line that still runs on it: its
+   metadata must allow your version, every Minecraft class it uses must exist there, no
+   method or field it calls may have been removed or renamed since the version it was
+   built for, and its mixins must still find their targets (with matching parameters). A
+   static check, so test it in game (or with `--docker-test`).
+3. A community fork compiled for that version (needs a token and `-lv`).
+4. Last resort: an older official build refused only by its declared Minecraft range. Modkeel
+   adds your version to that range, but keeps the result only if its bytecode resolves and a
+   headless server boots with it (needs Docker). The file is renamed `...+modkeel-relaxed-...`
+   and carries `META-INF/modkeel-relaxed.txt`.
+
+It never downloads a different mod with a similar name: addons are listed separately.
+
+When nothing runs on your version, Modkeel looks for the nearest Minecraft version with an
+official build and says so: in a terminal a 15-second countdown starts the search (Enter
+starts it now, `n` stops it); without a terminal it only prints the command to run.
+`--fallback auto|never` decides without asking. A result for another version goes to
+`out/mc-<version>/` and is never installed into `--instance`. `compile` does the same for
+the whole list (never with `--strict`): it proposes a version where more of the mods have
+an official build than were built on yours. On the few versions nearest yours, a mod also
+counts when its older build passes the static checks there. JARs from the first run that also pass the
+static checks on the new version are copied instead of built again; mods with an official
+build there are downloaded fresh.
+
+The last lines say what the JAR passed (`Evidence: metadata ✓ · linkage ✓ · ...`). With
+`--docker-test`, a headless server boots with each result before it is accepted: a JAR that
+crashes it (for example a mixin whose target changed) is removed and the next candidate is
+tried. Without Docker the JAR is kept and the output says the test did not run.
+
+`compile` follows the same order for each repository, with one more step after the official
+build: the author's own branch for that version, prebuilt or compiled, comes before an older
+build. `--strict` never uses an older build. The report says which source each mod came from
+and, for failures, everything that was tried.
+
+### Check Status
+
+```bash
+modkeel status
+```
+
+> **Legacy:** `python mod_auto_compiler.py ...` still works but is deprecated. Use `modkeel compile` instead.
+
+## Repository File Format
+
+The `repos.txt` file contains one repository URL per line:
+
+```
+# Base URL -- Modkeel finds the best branch automatically
+https://github.com/Creators-of-Create/Create
+https://github.com/mezz/JustEnoughItems
+
+# Specific branch
+https://github.com/PepperCode1/Continuity/tree/1.21.10/dev
+
+# Comments start with #
+```
+
+## Command Reference
+
+### `modkeel compile`
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `repos_file` | Text file with repository URLs | (required) |
+| `-m`, `--mc-version` | Minecraft version | (required) |
+| `-l`, `--loader` | Mod loader: `neoforge`, `forge`, `fabric` | (required) |
+| `-lv`, `--loader-version` | Loader version number | (required) |
+| `-i`, `--instance` | Minecraft instance path | -- |
+| `-o`, `--output-dir` | Output directory | `out` |
+| `-t`, `--github-token` | GitHub API token | -- |
+| `--strict` | Require exact MC version match | off |
+| `--no-cross-loader` | Disable Sinytra Connector fallback | off |
+| `--docker-test` | Test mods in Docker server | off |
+| `--docker-timeout` | Docker timeout (seconds) | 180 |
+| `--output-report` | Save report to file | -- |
+| `--log-file` | Write log to file | -- |
+| `--no-share` | Skip anonymous data sharing (sharing is not live yet) | off |
+
+### `modkeel search`
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `query` | Mod name to search | (required) |
+| `-m`, `--mc-version` | Minecraft version | (required) |
+| `-l`, `--loader` | Mod loader | `neoforge` |
+| `-t`, `--github-token` | GitHub API token | -- |
+
+### `modkeel status`
+
+No arguments. Shows version, config, cached loaders, and known NeoForge versions.
+
+## GitHub API Token
+
+Without a token you're limited to 60 API requests/hour. With a token: 5,000/hour.
+
+1. Go to [github.com/settings/tokens](https://github.com/settings/tokens)
+2. **Generate new token** > **Tokens (classic)**
+3. Select scope: **`public_repo`** (only permission needed)
+4. Save the token: `echo "ghp_xxx..." > github_token.txt`
+
+## Troubleshooting
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `gradle.properties not found` | Branch lacks Gradle files | Try a different branch |
+| `Compilation timeout (>10 min)` | Large mod or slow machine | Build manually with `./gradlew build` |
+| `GitHub API rate limit exceeded` | No token or too many requests | Use `--github-token` |
+| `minecraft_version is X, expected Y` | Branch targets wrong version | Expected -- Modkeel tries the next branch |
+| `No JAR file found in build/libs` | Unusual output path | Check `build.gradle` |
+| `JAR declares incompatible MC version` | Misconfigured `mods.toml` | Try another branch |
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/Modkeel/modkeel/blob/main/CONTRIBUTING.md) for development setup, testing, and PR guidelines.
+
+## License
+
+MIT License -- see [LICENSE](https://github.com/Modkeel/modkeel/blob/main/LICENSE) for details.