modsmith 0.1.0__tar.gz

modsmith-0.1.0/.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 4
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.{json,toml,yaml,yml}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false

modsmith-0.1.0/.gitattributes

@@ -0,0 +1,4 @@
+* text=auto eol=lf
+*.jar binary
+*.zip binary
+*.mrpack binary

modsmith-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,23 @@
+---
+name: Bug report
+about: Something does not work as documented
+labels: bug
+---
+
+**What happened?**
+
+**What did you expect?**
+
+**Code to reproduce it**
+
+```python
+
+```
+
+**Environment**
+
+- Modsmith version:
+- Python version:
+- Operating system:
+- Launcher (standalone or Microsoft Store):
+- Minecraft version and mod loader:

modsmith-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,13 @@
+---
+name: Feature request
+about: Suggest something Modsmith should do
+labels: enhancement
+---
+
+**What do you want to do?**
+
+**How would you expect the API to look?**
+
+```python
+
+```

modsmith-0.1.0/.github/dependabot.yml

@@ -0,0 +1,18 @@
+version: 2
+
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      actions:
+        patterns: ["*"]
+
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      dependencies:
+        patterns: ["*"]

modsmith-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,7 @@
+## What changed and why
+
+## How it was tested
+
+- [ ] `uv run pytest`
+- [ ] `uv run pytest tests/live`, if platform or loader code changed
+- [ ] `CHANGELOG.md` updated, if users will notice this change

modsmith-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,123 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+  workflow_call:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  lint:
+    name: Lint and type check
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+      - name: Check the lockfile
+        run: uv lock --check
+      - run: uv sync --locked
+      - name: Run pre-commit hooks
+        run: uv run --no-sync pre-commit run --all-files --show-diff-on-failure
+      - name: Type check
+        run: uv run --no-sync pyright
+
+  test:
+    name: Test (${{ matrix.os }}, Python ${{ matrix.python }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-java@b843ebf9b913146b38da2eaa7aeddf76074ae1ad # v6.1.0
+        with:
+          distribution: temurin
+          java-version: "21"
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync --locked --no-default-groups --group test
+      - name: Run tests
+        run: uv run --no-sync pytest --cov
+      - name: Summarize coverage
+        shell: bash
+        run: uv run --no-sync coverage report --format=markdown >> "$GITHUB_STEP_SUMMARY"
+
+  minimum-dependencies:
+    name: Test (lowest dependencies)
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-java@b843ebf9b913146b38da2eaa7aeddf76074ae1ad # v6.1.0
+        with:
+          distribution: temurin
+          java-version: "21"
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+      - name: Run tests
+        run: uv run --isolated --resolution lowest-direct --group test pytest
+
+  docs:
+    name: Build documentation
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+      - run: uv sync --locked --no-default-groups --group docs
+      - name: Build the site
+        run: uv run --no-sync sphinx-build -W -n -b dirhtml docs docs/_build/html
+      - name: Run the examples
+        run: uv run --no-sync sphinx-build -W -b doctest docs docs/_build/doctest
+
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+      - run: uv build
+      - name: Check package metadata
+        run: uvx twine check --strict dist/*
+      - name: Import the built wheel
+        run: uv run --isolated --no-project --with dist/*.whl python -c "import modsmith; print(modsmith.__version__)"
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  all-checks:
+    name: All checks
+    if: always()
+    needs: [lint, test, minimum-dependencies, docs, build]
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Require every job to pass
+        env:
+          PASSED: ${{ !contains(needs.*.result, 'failure') && !contains(needs.*.result, 'cancelled') && !contains(needs.*.result, 'skipped') }}
+        run: test "$PASSED" = "true"

modsmith-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,45 @@
+name: Documentation
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build the site
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+      - run: uv sync --locked --no-default-groups --group docs
+      - name: Build the site
+        run: uv run --no-sync sphinx-build -W -n -b dirhtml docs docs/_build/html
+      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: docs/_build/html
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1

modsmith-0.1.0/.github/workflows/live.yml

@@ -0,0 +1,33 @@
+name: Live tests
+
+on:
+  schedule:
+    - cron: "17 3 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}
+  cancel-in-progress: false
+
+jobs:
+  live:
+    name: Live (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 60
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+      - run: uv sync --locked --no-default-groups --group test
+      - name: Run live tests
+        env:
+          CURSEFORGE_API_KEY: ${{ secrets.CURSEFORGE_API_KEY }}
+        run: uv run --no-sync pytest tests/live

modsmith-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,64 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  check-version:
+    name: Check the tag
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+      - name: Compare the tag with the project version
+        env:
+          TAG: ${{ github.ref_name }}
+        run: test "v$(uv version --short)" = "$TAG"
+
+  ci:
+    name: CI
+    needs: check-version
+    uses: ./.github/workflows/ci.yml
+
+  pypi:
+    name: Publish to PyPI
+    needs: ci
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/project/modsmith/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
+
+  github-release:
+    name: Create the GitHub release
+    needs: pypi
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+          path: dist/
+      - name: Create the release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          TAG: ${{ github.ref_name }}
+        run: gh release create "$TAG" dist/* --verify-tag --generate-notes

modsmith-0.1.0/.gitignore

@@ -0,0 +1,34 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+wheels/
+
+# Environments
+.venv/
+.env
+
+# Tool caches
+.cache/
+.coverage
+.coverage.*
+.pyright/
+.pytest_cache/
+.ruff_cache/
+htmlcov/
+
+# Editors and systems
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db
+
+# Local game files and logs
+*.log
+.minecraft/
+
+# Documentation
+docs/_build/
+docs/reference/*/

modsmith-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,22 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-merge-conflict
+      - id: check-toml
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: ruff check
+        entry: uv run --no-sync ruff check --fix --force-exclude
+        language: system
+        types_or: [python, pyi]
+      - id: ruff-format
+        name: ruff format
+        entry: uv run --no-sync ruff format --force-exclude
+        language: system
+        types_or: [python, pyi]

modsmith-0.1.0/.python-version

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

modsmith-0.1.0/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this project are documented in this file. The format is
+based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this
+project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-03
+
+### Added
+
+- `modsmith.platforms`: search and fetch from Modrinth and CurseForge.
+- `modsmith.packs`: read mrpack and CurseForge modpacks without network access.
+- `modsmith.loaders`: install Forge, NeoForge, Fabric and Quilt.
+- `modsmith.instances`: `Instance.diff()` and `Instance.sync()` for installing
+  and updating game directories while keeping user changes.
+- `modsmith.minecraft`, `modsmith.java`, `modsmith.launcher` and `modsmith.net`.
+
+- `Instance.sync` stages new files and rolls back if it cannot finish, so a
+  failed update leaves the instance as it was.
+- `Platform.iter_releases` reads releases page by page, so finding the latest
+  one takes a single request.
+- Modpack overrides are streamed, so large packs no longer load into memory.
+- `Instance` remembers file hashes, so a sync with nothing to do is faster.
+- `Loader.is_installed` works offline for the built-in loaders.
+- Download progress counts skipped and resumed files, and reaches the total.
+- Forge and NeoForge installs prefer newer Java runtimes, which fixes old
+  versions on Windows and Apple Silicon.
+- Requests respect `Retry-After`, and downloads use `If-Range` to resume.
+
+### Changed
+
+- The project was renamed from CurseCraft and rebuilt as a developer toolkit.

modsmith-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,117 @@
+# Contributing
+
+## Setup
+
+You need [uv](https://docs.astral.sh/uv/) and a JDK, because the functional
+tests compile and run a small processor jar.
+
+```bash
+uv sync
+```
+
+```bash
+uv run pre-commit install
+```
+
+## Checks
+
+Run these before you open a pull request:
+
+```bash
+uv run ruff format .
+```
+
+```bash
+uv run ruff check .
+```
+
+```bash
+uv run pyright
+```
+
+```bash
+uv run pytest --cov
+```
+
+## Testing
+
+| Layer | Contains | Runs |
+| :--- | :--- | :--- |
+| `tests/unit` | Pure logic and real local files | By default |
+| `tests/functional` | A real local HTTP server and a real JVM; the internet is blocked | By default |
+| `tests/live` | Real platforms and complete loader installs | On request |
+
+Run the live tests with:
+
+```bash
+uv run pytest tests/live
+```
+
+CurseForge tests need `CURSEFORGE_API_KEY` and are skipped without it.
+
+Tests do not use mocks. Do not use `unittest.mock`, patch internal functions or
+fake a process or an HTTP client. Setting environment variables with
+`monkeypatch` is allowed, because that configures the environment. If code is
+hard to test this way, give it a parameter, such as a URL, instead.
+
+Platform behaviour is tested only in `tests/live`, against the real services.
+
+### Known gaps
+
+- `replace_file` falls back to copying when a rename fails with `EXDEV`. The
+  cross-filesystem test only runs when the working directory and the temp
+  directory are on different drives. The MSIX behaviour that needed the
+  fallback cannot be reproduced in a normal environment.
+- `is_running()` is checked against the real process table, but no test starts
+  the official launcher, and the Microsoft Store launcher's process name is
+  unconfirmed.
+- No test starts the game.
+
+## Docstrings
+
+Write Google-style docstrings, in English, for every module, class and function.
+Ruff checks that they exist, so also check that they match what the code does.
+
+- Describe behaviour. Type annotations already give the types.
+- Add `Args`, `Returns` and `Raises` when a caller needs them.
+- Use single backticks for modsmith objects, which become links in the
+  documentation, and double backticks for parameters and literal values.
+- Use a code comment only to explain why something is done.
+
+## Documentation
+
+The site is built with Sphinx and MyST, and the API reference comes from the
+docstrings. Warnings and broken references fail the build:
+
+```bash
+uv run sphinx-build -W -n -b dirhtml docs docs/_build/html
+```
+
+Examples in docstrings run as tests:
+
+```bash
+uv run sphinx-build -W -b doctest docs docs/_build/doctest
+```
+
+## Continuous integration
+
+| Workflow | Runs | Does |
+| :--- | :--- | :--- |
+| `ci.yml` | Pull requests and pushes to `main` | Lint, type checks, tests on every OS and Python version, lowest dependencies, documentation, package build |
+| `live.yml` | Every Monday, or by hand | Runs `tests/live` on every OS |
+| `release.yml` | `v*` tags | Runs CI, publishes to PyPI and creates a GitHub release |
+
+`ci.yml` ends with an `All checks` job, which is the one to require in branch
+protection. `live.yml` reads `CURSEFORGE_API_KEY` from the repository secrets.
+
+## Releasing
+
+1. Set `version` in `pyproject.toml` and move the `Unreleased` notes in
+   `CHANGELOG.md` under the new version.
+2. Merge that change into `main`.
+3. Push a tag such as `v0.1.0`. The tag must match the project version.
+
+## Commits
+
+Keep the change focused, write the subject in the imperative mood, and add a
+line to `CHANGELOG.md` under `Unreleased` when users will notice the change.

modsmith-0.1.0/LICENSE

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