raydriver 0.1.0__tar.gz

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

@@ -0,0 +1,180 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    name: Lint and typecheck
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Build wheel
+        uses: PyO3/maturin-action@v1
+        with:
+          command: build
+          args: --release --out dist
+
+      - name: Install wheel
+        run: pip install dist/raydriver-*.whl
+
+      - name: Lint Python
+        run: pip install ruff && ruff check tests/ python/
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@1.98.1
+        with:
+          components: rustfmt, clippy
+
+      - name: Lint Rust
+        shell: bash
+        run: |
+          set -o pipefail
+          cargo fmt --check 2>&1 | tee fmt-output.txt
+          cargo clippy -- -D warnings 2>&1 | tee clippy-output.txt
+
+      - name: Persist diagnostics to ci-logs branch
+        if: failure()
+        shell: bash
+        run: |
+          mkdir -p logs
+          cp fmt-output.txt clippy-output.txt logs/ 2>/dev/null || true
+          git config user.name ci-bot
+          git config user.email ci-bot@users.noreply.github.com
+          git add logs
+          git diff --cached --quiet && echo "nothing to persist" && exit 0
+          git commit -qm "lint diagnostics @ ${{ github.sha }}"
+          git push -q -f origin "HEAD:refs/heads/ci-logs-lint"
+
+  test:
+    name: Tests (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 40
+    strategy:
+      fail-fast: false
+      # Windows is covered by the sharded windows-shard job (its
+      # release build is slow and one hang must not hide the rest).
+      matrix:
+        os: [ubuntu-latest, macos-15-intel, macos-15]
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Build wheel
+        uses: PyO3/maturin-action@v1
+        with:
+          command: build
+          args: --release --out dist
+
+      - name: Install wheel
+        shell: bash
+        run: pip install dist/raydriver-*.whl
+
+      - name: Install test dependencies
+        shell: bash
+        run: pip install pytest pytest-asyncio pytest-timeout
+
+      - name: Run tests
+        shell: bash
+        run: |
+          set -o pipefail
+          rm -f pytest-output.txt
+          for attempt in 1 2 3; do
+            if pytest -v --timeout=60 --timeout-method=thread --tb=short -rA 2>&1 | tee -a pytest-output.txt; then
+              exit 0
+            fi
+            echo "attempt $attempt failed, retrying..." | tee -a pytest-output.txt
+          done
+          exit 1
+
+      - name: Persist diagnostics to ci-logs branch
+        if: failure() || cancelled()
+        shell: bash
+        run: |
+          mkdir -p logs
+          cp pytest-output.txt freeze-dump.txt logs/ 2>/dev/null || true
+          git config user.name ci-bot
+          git config user.email ci-bot@users.noreply.github.com
+          git add logs
+          git diff --cached --quiet && echo "nothing to persist" && exit 0
+          git commit -qm "test diagnostics: ${{ matrix.os }} @ ${{ github.sha }}"
+          git push -q -f origin "HEAD:refs/heads/ci-logs-main-${{ matrix.os }}"
+
+  windows-shard:
+    name: Windows shard (${{ matrix.file }})
+    runs-on: windows-latest
+    timeout-minutes: 60
+    strategy:
+      fail-fast: false
+      matrix:
+        file:
+          - tests/test_cli.py
+          - tests/test_parser.py
+          - tests/test_session.py
+          - tests/test_streaming.py
+          - tests/test_stress.py
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@1.98.1
+
+      - name: Install maturin
+        shell: bash
+        run: pip install maturin
+
+      - name: Build wheel
+        shell: bash
+        run: |
+          set -o pipefail
+          maturin build --release --out dist 2>&1 | tee build-output.txt
+
+      - name: Persist build diagnostics to ci-logs branch
+        if: failure()
+        shell: bash
+        run: |
+          mkdir -p logs
+          cp build-output.txt logs/ 2>/dev/null || true
+          git config user.name ci-bot
+          git config user.email ci-bot@users.noreply.github.com
+          git add logs
+          git diff --cached --quiet && echo "nothing to persist" && exit 0
+          git commit -qm "windows build diagnostics: ${{ matrix.file }} @ ${{ github.sha }}"
+          git push -q -f origin "HEAD:refs/heads/ci-logs-win-build-${{ matrix.file }}"
+
+      - name: Install wheel
+        shell: bash
+        run: pip install dist/raydriver-*.whl
+
+      - name: Install test dependencies
+        shell: bash
+        run: pip install pytest pytest-asyncio pytest-timeout
+
+      - name: Run shard
+        shell: bash
+        run: |
+          set -o pipefail
+          rm -f shard-output.txt
+          for attempt in 1 2 3; do
+            if python -u -m pytest ${{ matrix.file }} -v --timeout=30 --timeout-method=thread --tb=long -rA 2>&1 | tee -a shard-output.txt; then
+              exit 0
+            fi
+            echo "attempt $attempt failed, retrying..." | tee -a shard-output.txt
+          done
+          exit 1
+
+      - name: Persist shard diagnostics to ci-logs branch
+        if: failure() || cancelled()
+        shell: bash
+        run: |
+          mkdir -p logs
+          cp shard-output.txt freeze-dump.txt logs/ 2>/dev/null || true
+          git config user.name ci-bot
+          git config user.email ci-bot@users.noreply.github.com
+          git add logs
+          git diff --cached --quiet && echo "nothing to persist" && exit 0
+          git commit -qm "windows shard diagnostics: ${{ matrix.file }} @ ${{ github.sha }}"
+          git push -q -f origin "HEAD:refs/heads/ci-logs-win-shard"

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

@@ -0,0 +1,85 @@
+name: Build and Publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build-wheels:
+    name: Build wheels on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-15-intel, macos-15]
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Set version from tag
+        if: startsWith(github.ref, 'refs/tags/v')
+        shell: bash
+        run: |
+          VERSION="${GITHUB_REF#refs/tags/v}"
+          sed -i.bak "s/^version = \".*\"/version = \"$VERSION\"/" Cargo.toml
+
+      - uses: PyO3/maturin-action@v1
+        with:
+          command: build
+          args: --release --out dist
+
+      - name: Upload wheels as artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.os }}
+          path: dist/*.whl
+
+  build-sdist:
+    name: Build sdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Set version from tag
+        if: startsWith(github.ref, 'refs/tags/v')
+        shell: bash
+        run: |
+          VERSION="${GITHUB_REF#refs/tags/v}"
+          sed -i.bak "s/^version = \".*\"/version = \"$VERSION\"/" Cargo.toml
+
+      - uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: --out dist
+
+      - name: Upload sdist as artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  publish:
+    name: Publish to PyPI
+    needs: [build-wheels, build-sdist]
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: write
+    steps:
+      - name: Download all artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+
+      - name: Upload artifacts to GitHub Release
+        uses: softprops/action-gh-release@v2
+        if: startsWith(github.ref, 'refs/tags/')
+        with:
+          files: dist/*

raydriver-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+target/
+__pycache__/
+*.pyc
+*.so
+*.pyd
+dist/
+.venv/
+.ruff_cache/
+.pytest_cache/

raydriver-0.1.0/AGENTS.md

@@ -0,0 +1,111 @@
+# AGENTS.md
+
+## Available commands
+
+- `make dev` — build and install into the active venv
+- `make stubs` — re-generate `.pyi` type stubs (after changing `src/python/` bindings)
+- `make lint` — lint all code (Rust + Python)
+- `make lint-rust` — lint Rust only
+- `make lint-python` — lint Python only
+- `make format` — auto-format all code (Rust + Python, including PEP8 import ordering)
+- `make format-rust` — format Rust only
+- `make format-python` — format Python only (ruff handles formatting and import sorting)
+- `make test` — run the full test suite. make sure to "make dev" before you test
+- `make check` — lint + test
+- `make build` — build the wheel (release)
+
+## CLI
+
+- `raydriver run job.gcode --port /dev/ttyUSB0` — stream a G-code
+  file to a real device with live progress
+- `raydriver run job.gcode --emulator` — same, against the built-in
+  firmware emulator (no hardware needed)
+- `raydriver status --port /dev/ttyUSB0` — connect and print live
+  status reports
+
+## Testing
+
+All tests are Python-based, under `tests/`, and run against
+`raydriver.emulator.GrblEmulator` — a GRBL 1.1h *firmware emulator*
+(not a mock): it models the character-counting RX buffer, the
+15-block planner with deferred acknowledgements, realtime command
+interception, modal G-code state, feed-rate-timed motion, alarms,
+homing, probing and the `$` system commands.  Device-side code
+consumes session writes via `MockTransport.take_new_sent()` (a
+monotonic cursor — never index into `sent()`, which tests may clear
+at any time).
+
+## Rules
+
+- You are strictly forbidden from editing stubs manually. They are only
+  to be edited using "make stubs".
+- Use make commands when available - avoid calling the underlying tools
+  directly.
+- Never add Rust tests (`#[cfg(test)]` / `#[test]` blocks in `src/`).
+  All tests are Python-based, under `tests/`. Exercise new Rust code
+  through PyO3 bindings from Python test code.
+- Keep the Grbl protocol behavior byte-for-byte compatible with the
+  Python driver in Rayforge
+  (`rayforge/machine/driver/grbl/grbl_serial.py`). Do not change
+  protocol quirks (ack extraction order, realtime bypass, buffer
+  accounting, stall/liveness rules) without an explicit request.
+
+## Layering Rules Specification
+
+The crate is split into two layers that depend only downward:
+
+```
+grbl (protocol + session core)  →  python (PyO3 bindings)
+```
+
+- `src/grbl/` must not depend on PyO3 or any Python types. It is pure
+  Rust: protocol parsing, flow control, transports, and the session
+  state machines. Python-facing notifications go through the
+  `SessionEvents` trait; the `python` feature provides the
+  implementation that marshals events across the boundary.
+- `src/python/` contains all PyO3 bindings and may use `src/grbl/`
+  freely, never the other way around.
+
+## Export Policy: Explicit Paths
+
+Every item has exactly one canonical path — its leaf module. Parent
+mod.rs must not re-export children's items (no namespace flattening).
+
+Exceptions: Primitive types, errors, classes and constants that are
+_public_ AND _shared_ within a submodule.
+
+Python sub-modules mirror the Rust hierarchy - no aliases or re-exports
+at higher levels. The compiled module is `raydriver.raydriver`; the
+pure-Python packages under `python/raydriver/` serve as the importable
+packages and delegate to the Rust module via module-level
+`__getattr__`:
+
+```python
+import raydriver.raydriver as _raydriver
+
+def __getattr__(name):
+    return getattr(_raydriver.grbl, name)
+```
+
+Rust submodules registered with `add_submodule` are intentionally NOT
+registered in `sys.modules` — the Python `__init__.py` of the same
+name is the package.
+
+## Python/Rust Boundary Rules
+
+- No domain model objects cross the Python/Rust boundary — only
+  primitive types, typed pyclasses defined in this crate, and
+  JSON-serialisable dicts.
+- Async Rust methods return asyncio futures that are completed from
+  the tokio side via `call_soon_threadsafe` on the caller's event
+  loop. Never block the loop inside a binding.
+- Events emitted by the session are delivered to the Python
+  `event_callback(name: str, payload)` on the event loop thread.
+  Bindings must not call the callback from a foreign thread directly.
+
+## Dialects
+
+Dialects remain data owned by Rayforge. This crate receives resolved
+command templates (a plain dict of format strings) and only needs the
+subset used for interactive commands. Formatting supports the Python
+`str.format` subset `{name}` and `{name:.Nf}`.