v0.2.2: API cleanup, pinokin IK, tool support, hot path optimization

.github/workflows/release.yml

@@ -0,0 +1,43 @@
+name: release
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: write
+
+jobs:
+  bump-version:
+    name: Bump version to match release tag
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.release.target_commitish }}
+
+      - name: Extract version from tag
+        id: version
+        run: |
+          TAG="${{ github.event.release.tag_name }}"
+          # Strip leading 'v' if present (v0.2.0 -> 0.2.0)
+          VERSION="${TAG#v}"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Update version in pyproject.toml
+        run: |
+          sed -i "s/^version = \".*\"/version = \"${{ steps.version.outputs.version }}\"/" pyproject.toml
+
+      - name: Verify version
+        run: |
+          grep "^version = \"${{ steps.version.outputs.version }}\"" pyproject.toml
+
+      - name: Commit and push version bump
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add pyproject.toml
+          git diff --cached --quiet && echo "No changes to commit" && exit 0
+          git commit -m "bump version to ${{ steps.version.outputs.version }}"
+          git push

.github/workflows/tests.yml

@@ -1,6 +1,7 @@
 name: tests
 
 on:
+  workflow_dispatch:
   push:
     paths:
       - '**'
@@ -10,7 +11,7 @@ on:
 
 jobs:
   lint:
-    name: Lint (ruff + mypy)
+    name: Lint (pre-commit)
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
@@ -19,18 +20,17 @@ jobs:
         uses: actions/setup-python@v5
         with:
           python-version: '3.11'
-          cache: pip
-          cache-dependency-path: pyproject.toml
-      - name: Install dev dependencies
+      - name: Install dependencies
+        shell: bash
         run: |
           python -m pip install --upgrade pip
+          BRANCH="${GITHUB_HEAD_REF:-${GITHUB_REF_NAME}}"
+          if git ls-remote --heads https://github.com/Jepson2k/waldoctl.git "$BRANCH" 2>/dev/null | grep -q .; then
+            pip install "waldoctl @ git+https://github.com/Jepson2k/waldoctl.git@${BRANCH}"
+          fi
           pip install -e ".[dev]"
-      - name: Ruff (lint)
-        run: ruff check parol6
-      - name: Ruff (format check)
-        run: ruff format --check parol6
-      - name: MyPy
-        run: mypy parol6
+      - name: Run pre-commit
+        uses: pre-commit/action@v3.0.1
   test:
     name: ${{ matrix.os }} / Python ${{ matrix.python-version }}
     runs-on: ${{ matrix.os }}
@@ -39,7 +39,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, windows-latest, macos-latest]
-        python-version: ['3.10', '3.11']
+        python-version: ['3.11', '3.12', '3.13', '3.14']
 
     steps:
       - name: Checkout repository (with submodules)
@@ -52,17 +52,26 @@ jobs:
           cache: pip
           cache-dependency-path: pyproject.toml
 
-      - name: Upgrade pip and install dependencies
+      - name: Install cross-repo dependencies
+        shell: bash
         run: |
           python -m pip install --upgrade pip
+          BRANCH="${GITHUB_HEAD_REF:-${GITHUB_REF_NAME}}"
+          # waldoctl: try matching branch, fall back to tagged version
+          if git ls-remote --heads https://github.com/Jepson2k/waldoctl.git "$BRANCH" 2>/dev/null | grep -q .; then
+            pip install "waldoctl @ git+https://github.com/Jepson2k/waldoctl.git@${BRANCH}"
+          fi
+
+      - name: Install package
+        run: |
           pip install -e ".[dev]" pytest-timeout
 
       - name: Show environment
         run: |
           python -V
           pip list
 
-      - name: Run tests (skip hardware)
+      - name: Run tests
         env:
           PYTHONUNBUFFERED: '1'
           PYTHONUTF8: '1'

.gitignore

@@ -124,4 +124,5 @@ cython_debug/
 # VS Code
 .vscode/
 
-serial_port.txt
+serial_port.txt
+test-results.xml

.pre-commit-config.yaml

@@ -1,33 +1,25 @@
-default_language_version:
-  python: python3.11
-
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.6.0
+    rev: v6.0.0
     hooks:
       - id: check-yaml
       - id: end-of-file-fixer
       - id: trailing-whitespace
       - id: check-merge-conflict
-      - id: check-added-large-files
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.6.9
+    rev: v0.14.10
     hooks:
       - id: ruff
         args: ["--fix"]
       - id: ruff-format
 
-  - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.11.2
+  - repo: local
     hooks:
-      - id: mypy
-        name: mypy (parol6)
+      - id: ty
+        name: ty (parol6)
+        entry: ty check parol6
+        language: system
         files: ^parol6/
         pass_filenames: false
-        args: ["parol6"]
-        stages: [commit, push]
-        additional_dependencies:
-          - numpy==1.26.4
-          - spatialmath-python==1.1.14
-          - scipy==1.11.4
+        stages: [pre-commit, pre-push]

CLAUDE.md

@@ -0,0 +1,154 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+PAROL6 Python API is a lightweight client and controller for PAROL6 6-DOF robot arms. It provides:
+- **AsyncRobotClient**: Async UDP client for robot control
+- **RobotClient**: Synchronous wrapper for imperative scripts
+- **Controller**: Fixed-rate control loop with serial/simulator transport
+
+## Architecture
+
+```
+┌─────────────────────────────────────────┐
+│           Client Application            │
+│  (AsyncRobotClient / RobotClient)       │
+└──────────────────┬──────────────────────┘
+         UDP commands (port 5001)
+         Multicast status (239.255.0.101:50510)
+┌──────────────────▼──────────────────────┐
+│              Controller                 │
+│  (parol6/server/controller.py)          │
+│  - 100 Hz control loop (configurable)   │
+│  - Command queue & execution            │
+│  - Status multicast broadcasting        │
+└──────────────────┬──────────────────────┘
+         Serial (3 Mbaud) or MockSerial
+┌──────────────────▼──────────────────────┐
+│     Robot Hardware / Simulator          │
+└─────────────────────────────────────────┘
+```
+
+## Build & Test Commands
+
+```bash
+# Development setup
+pip install -e .[dev]
+pre-commit install
+
+# Linting & formatting
+ruff check .
+ruff format .
+ty check parol6/
+
+# Run all pre-commit hooks
+pre-commit run -a
+
+# Testing (simulator used by default via conftest.py — do NOT prefix with env vars)
+pytest
+
+# Run specific test file
+pytest tests/unit/test_wire.py -v
+```
+
+**IMPORTANT: Do NOT prefix `pytest` commands with environment variables like `PAROL6_FAKE_SERIAL=1 pytest ...`. The conftest.py already configures `PAROL6_FAKE_SERIAL=1`. Just run `pytest` directly.**
+
+## Controller CLI
+
+```bash
+# Start controller
+parol6-server --log-level=INFO
+
+# With explicit serial port
+parol6-server --serial=/dev/ttyUSB0 --log-level=DEBUG
+
+# Verbosity shortcuts: -v (INFO), -vv (DEBUG), -vvv (TRACE)
+```
+
+## Key Modules
+
+- **`parol6/client/async_client.py`**: Primary API - async UDP client with motion commands, queries, and status streaming
+- **`parol6/server/controller.py`**: Controller with fixed-rate loop and command execution
+- **`parol6/commands/`**: Polymorphic command classes using `@register_command(CmdType.XXX)` decorator
+- **`parol6/protocol/wire.py`**: Msgpack message encoding/decoding, command structs (tagged union)
+- **`parol6/PAROL6_ROBOT.py`**: Robot kinematics config, DH parameters, joint limits, tool transforms
+
+## Adding a New Command
+
+1. Create a class in `parol6/commands/` and decorate with `@register_command(CmdType.YOUR_CMD)`
+2. Define a `PARAMS_TYPE` msgspec Struct for wire validation
+3. Implement `do_setup(state)` and `execute_step(state)` lifecycle methods
+4. For motion commands, set `streamable=True` if supporting high-rate streaming
+
+## Environment Variables
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `PAROL6_CONTROL_RATE_HZ` | 100 | Control loop frequency |
+| `PAROL6_STATUS_RATE_HZ` | 50 | Status broadcast rate (tests use 20 Hz) |
+| `PAROL6_FAKE_SERIAL` | 0 | Enable simulator (no hardware) |
+| `PAROL6_COM_PORT` | auto | Serial port override |
+| `PAROL_TRACE` | 0 | Enable TRACE logging |
+
+## Simulator Mode
+
+- Uses `MockSerialTransport` to emulate robot dynamics without hardware
+- Toggle via client: `simulator(True)` / `simulator(False)`
+- Controller updates `PAROL6_FAKE_SERIAL` and reinitializes transport seamlessly
+- **Important**: Simulator cannot guarantee hardware success—motor/current limits may cause failures on real robot
+
+## Kinematics Notes
+
+- Uses numerical IK via pinokin (C++/Pinocchio with nanobind Python bindings)
+- J4 is particularly sensitive—some cartesian targets may fail to solve
+- Update `PAROL6_ROBOT.py` for modified hardware (gear ratios, limits, DH params)
+
+## Test Markers
+
+- `@pytest.mark.unit`: Isolated component tests
+- `@pytest.mark.integration`: Component interaction tests (uses simulator)
+
+## Performance Warnings
+
+If you see `Control loop avg period degraded by +XX%`:
+- Reduce `PAROL6_CONTROL_RATE_HZ`
+- Disable TRACE logging (significant overhead)
+- Avoid heavy background tasks during motion
+
+## Hot Path Rules
+
+`execute_step()` and `tick()` run at 100 Hz. **No heap allocations** in these methods.
+
+For streamable commands (`streamable = True`), `do_setup()` also runs at high frequency (50 Hz from UI) via `assign_params()` + `do_setup()` fast-path. Treat it as a hot path too.
+
+- No `list(...)`, `[x for x in ...]`, `dict(...)`, or other container construction
+- No string formatting or f-strings (except in error/stop paths that run once)
+- Pre-allocate all buffers in `__init__`
+- `ndarray[:] = list` is fine — numpy writes into existing buffer in-place
+- Use `dest[:] = src` for array copies. Only use `np.copyto(dest, src, casting=...)` when casting is needed — it's slower otherwise
+
+## Code Style
+
+- **Comments**: Describe the final code state, not what changed. Avoid "changed X to Y" or "added this because..." comments.
+- **Git commits/PRs**: No emoji, no "Generated by..." footers, no co-author boilerplate.
+- **Type annotations**: Fix type errors properly instead of using `# type: ignore`. Prefer:
+  - `@overload` decorators for functions with different return types based on input
+  - `assert` statements to narrow types after None checks
+  - `cast()` from typing when the type is known but the checker can't infer it
+  - `np.atleast_1d()` or similar to guarantee array returns from numpy functions
+  - Only use `# type: ignore` as a last resort for genuine type checker limitations (e.g., numpy's `ArrayLike` being too broad)
+
+## Shell Command Style
+
+- **Do NOT use compound `cd` commands** like `cd foo && git status` or `cd foo && pytest`. Compound commands that cross directories require explicit user approval and slow things down. Instead, issue a standalone `cd foo` command first, then run the action as a separate command. The Bash tool's working directory persists between calls.
+
+## Testing Guidelines
+
+**When CI tests fail, fix them.** Don't waste time analyzing whether failures are "related to your changes" — just fix all failing tests. The goal is a green CI, not attribution.
+
+Prefer fewer, comprehensive integration tests that mimic manual testing over a large number of unit tests. We have no code coverage requirements—the goal is working features, not metrics.
+- **Test results are in `test-results.xml`.** Pytest writes JUnit XML to `test-results.xml` automatically. When diagnosing failures, read this file — it contains test names, durations, failure messages, and captured output. This is more reliable than parsing console output.
+- **NEVER run parol6 and web commander test suites in parallel** — no proper isolation, they share resources and have timing issues when resource-constrained. Always run sequentially.
+- **NEVER allow subagents to run tests.** Many tests are timing-sensitive and the system doesn't have enough resources for agents and tests to run simultaneously. Only the main conversation should run tests, and only after all agents have completed.