Initial Py-Ritone monorepo scaffold

Author: GSstarGamer

.editorconfig

@@ -0,0 +1,17 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.{java,py,md,json,toml,yml,yaml,properties,gradle}]
+indent_style = space
+indent_size = 4
+
+[*.{gradle,properties,json,yml,yaml,toml}]
+indent_size = 2
+
+[Makefile]
+indent_style = tab

.github/workflows/ci.yml

@@ -0,0 +1,65 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+
+jobs:
+  mod-build:
+    runs-on: windows-latest
+    defaults:
+      run:
+        shell: pwsh
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Java 21
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: "21"
+      - name: Build Fabric mod
+        working-directory: mod
+        run: .\gradlew.bat build --no-daemon
+      - name: Upload mod artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: pyritone-mod-jar
+          path: mod/build/libs/*.jar
+
+  python-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Install dependencies
+        working-directory: python
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install pytest build twine
+      - name: Run tests
+        working-directory: python
+        run: python -m pytest
+      - name: Build package
+        working-directory: python
+        run: python -m build
+      - name: Twine check
+        working-directory: python
+        run: python -m twine check dist/*
+      - name: Upload python artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: pyritone-python-dist
+          path: python/dist/*
+
+  protocol-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Validate protocol schema JSON
+        run: python -m json.tool protocol/bridge-protocol-v1.schema.json > /dev/null
+      - name: Ensure protocol doc exists
+        run: test -f protocol/bridge-protocol-v1.md

.gitignore

@@ -0,0 +1,29 @@
+# Root
+.git/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# IDE
+.idea/
+.vscode/
+*.iml
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.venv/
+venv/
+python/dist/
+python/build/
+
+# Gradle/Fabric
+mod/.gradle/
+mod/build/
+mod/run/
+
+# Runtime logs
+mod/logs/

LICENSE

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

README.md

@@ -0,0 +1,57 @@
+# Py-Ritone
+
+Py-Ritone is a zero-setup local bridge between a Fabric Minecraft client (with Baritone installed) and Python.
+
+## Monorepo Layout
+
+- `mod/`: Fabric client mod (`pyritone_bridge`) exposing a local NDJSON socket bridge.
+- `python/`: PyPI-ready package (`pyritone`) with async client, sync wrapper, and CLI.
+- `protocol/`: Versioned bridge protocol docs and JSON schema.
+- `docs/`: Developer setup and runbook.
+
+## Quick Start
+
+1. Install Minecraft Fabric client for 1.21.8.
+2. Install Baritone `v1.15.0` mod.
+3. Build or install `pyritone_bridge` mod jar into your client mods folder.
+4. Install Python package:
+
+```bash
+pip install pyritone
+```
+
+5. Start Minecraft client. Py-Ritone opens `127.0.0.1:27841` automatically.
+6. Use the package:
+
+```python
+from pyritone import PyritoneClient
+
+with PyritoneClient() as client:
+    print(client.ping())
+    print(client.status_get())
+    print(client.execute("goto 100 70 100"))
+```
+
+## One-Click Dev Client
+
+- Double-click `run_dev_client.bat` at repo root, or run it in terminal:
+
+```powershell
+.\run_dev_client.bat
+```
+
+- In VS Code, use the task button:
+  - `Terminal` -> `Run Build Task` -> `Py-Ritone: Build and Run Dev Client`
+
+This compiles and starts the Fabric dev client, and auto-downloads Baritone for dev runtime.
+
+## Security Model (v1)
+
+- Bridge binds to loopback only.
+- Auth token is generated by the mod and written to:
+  - `<minecraft>/config/pyritone_bridge/bridge-info.json`
+- Python auto-discovers this file by default.
+
+## License
+
+MIT

docs/dev-setup.md

@@ -0,0 +1,47 @@
+# Developer Setup
+
+## Requirements
+
+- Java 21+ (build targets Java 21 bytecode)
+- Python 3.10+
+- Git
+
+## Build Fabric Mod
+
+```powershell
+cd mod
+.\gradlew.bat build
+```
+
+Output jar:
+
+- `mod/build/libs/pyritone_bridge-<version>.jar`
+
+## Run Python Tests
+
+```powershell
+cd python
+python -m pytest
+```
+
+## Build Python Package
+
+```powershell
+cd python
+python -m build
+python -m twine check dist/*
+```
+
+## Local End-to-End Smoke
+
+1. Install Baritone `v1.15.0` and Py-Ritone mod jar in your Fabric client `mods` folder.
+2. Start Minecraft client and join a world.
+3. From Python:
+
+```python
+from pyritone import PyritoneClient
+
+with PyritoneClient() as client:
+    print(client.ping())
+    print(client.status_get())
+```

docs/runbook.md

@@ -0,0 +1,31 @@
+# Runbook
+
+## Bridge Not Starting
+
+- Check Minecraft client logs for `pyritone_bridge` startup errors.
+- Ensure no process is already using `127.0.0.1:27841`.
+
+## Python Client Cannot Connect
+
+- Confirm Minecraft has started with both mods installed.
+- Confirm bridge file exists:
+  - `%APPDATA%\.minecraft\config\pyritone_bridge\bridge-info.json`
+- Use explicit options for troubleshooting:
+
+```bash
+pyritone --host 127.0.0.1 --port 27841 --token <token> ping
+```
+
+## Unauthorized Errors
+
+- Token mismatch between Python side and bridge info file.
+- Restart Minecraft client to regenerate/update bridge metadata.
+
+## Baritone Unavailable
+
+- Baritone mod is missing or wrong version.
+- Install `baritone-api-fabric-1.15.0.jar`.
+
+## Not In World
+
+- Connect to any singleplayer or multiplayer world before running `baritone.execute`.