Skip to content

Commit 6258cd7

Browse files
committed
Add development CLI for setup, validation and contracts
1 parent cc989b4 commit 6258cd7

24 files changed

Lines changed: 2293 additions & 32 deletions

‎.github/workflows/check.yml‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -21,10 +21,7 @@ jobs:
2121
version: "0.13.6"
2222
python-version: "3.14"
2323
- run: uv sync --locked
24-
- run: uv run ruff check
25-
- run: uv run ruff format --check
26-
- run: uv run ty check
27-
- run: uv run pytest
24+
- run: uv run rua-dev validate --lane python
2825
- run: uv lock --check --project examples/python
2926

3027
rust:
@@ -43,9 +40,14 @@ jobs:
4340
echo 'deb [signed-by=/usr/share/keyrings/llvm.gpg] https://apt.llvm.org/noble/ llvm-toolchain-noble-21 main' | sudo tee /etc/apt/sources.list.d/llvm.list
4441
sudo apt-get update
4542
sudo apt-get install -y pkg-config mold libudev-dev libglib2.0-dev clang-21 libclang-21-dev ffmpeg
43+
- uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
44+
with:
45+
version: "0.13.6"
46+
python-version: "3.14"
4647
- name: Prepare pinned robot assets
47-
run: python3 tools/prepare_robot_assets.py
48+
run: uv run rua-dev setup
4849
- run: rustup show active-toolchain
4950
- run: cargo fmt --all -- --check
5051
- run: cargo clippy --locked --all-targets --all-features
5152
- run: cargo test --locked --workspace --all-features
53+
- run: uv run rua-dev contracts --check

‎CONTRIBUTING.md‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ This is an early release of part of our robotics stack. Feedback and issue repor
44
are welcome.
55

66
For development, follow [source setup](docs/getting-started.md#from-source), then
7-
run `uv sync --locked` from the checkout root. The pinned Rust toolchain includes
7+
run `uv run rua-dev setup` from the checkout root. The pinned Rust toolchain includes
88
Clippy and rustfmt. Python checks run on 3.14; the package supports Python 3.12+.
99
Python dependencies keep a three-day minimum release age.
1010

@@ -17,6 +17,10 @@ uv run ty check
1717
uv run pytest
1818
```
1919

20+
`uv run rua-dev validate --lane python` runs the Python checks and tests together.
21+
Use `uv run rua-dev contracts --check` to verify schemas and the Python SDK, or
22+
omit `--check` to regenerate them. Targets default to SDKs present in the checkout.
23+
2024
For Rust changes:
2125

2226
```sh
@@ -25,6 +29,10 @@ cargo clippy --all-targets --all-features
2529
cargo test --workspace --all-features
2630
```
2731

32+
`uv run rua-dev validate` checks all included components. Native prerequisites
33+
are required for its Rust checks. To verify a built wheel outside the checkout,
34+
use `uv run rua-dev package check /path/to/hebbian_rua.whl`.
35+
2836
Check documentation links with `lychee --offline -v .`; use `lychee -v .` to
2937
include external links. CI checks Python and Rust on Ubuntu 24.04.
3038

‎docs/getting-started.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ Contributors need Rust 1.92+, Python 3.12+ and uv. On Ubuntu, install
2828
`build-essential`, `pkg-config`, `libudev-dev` and `mold`, then:
2929

3030
```sh
31-
python3 tools/prepare_robot_assets.py
31+
uv run rua-dev setup
3232
cargo build -p hebbian-station
3333
uv sync --project examples/python --locked
3434
uv run --project examples/python rua serve --profile ./robot.toml

‎examples/python/uv.lock‎

Lines changed: 2 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎pyproject.toml‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,16 +26,18 @@ module-root = ""
2626
module-name = "hebbian_rua"
2727

2828
[tool.uv.sources]
29-
hebbian-robot-use-client = { path = "hebbian_robot_use_client", editable = true }
29+
hebbian-robot-use-client = { workspace = true }
30+
rua-dev = { workspace = true }
3031

3132
[tool.uv.workspace]
33+
members = ["hebbian_robot_use_client", "tooling"]
3234
exclude = ["examples/python"]
3335

3436
[tool.uv]
3537
exclude-newer = "3 days"
3638

3739
[dependency-groups]
38-
dev = ["ruff>=0.17.4", "ty>=0.0.100", "pytest>=9.2.0", "openai>=3.49.0", "anthropic>=2.8.0", "google-genai>=3.1.0"]
40+
dev = ["rua-dev", "datamodel-code-generator>=0.89.0", "ruff>=0.17.4", "ty>=0.0.100", "pytest>=9.2.0", "openai>=3.49.0", "anthropic>=2.8.0", "google-genai>=3.1.0"]
3941

4042
[tool.ruff]
4143
line-length = 88
Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
"""Development tooling follows the SDK components available in a checkout."""
2+
3+
from pathlib import Path
4+
5+
import pytest
6+
from rua_dev.contracts import available_sdk_targets, generate_contracts
7+
from rua_dev.models import SdkTarget
8+
9+
10+
@pytest.mark.parametrize(
11+
("directories", "expected_targets"),
12+
[
13+
(["hebbian_robot_use_client"], {SdkTarget.PYTHON}),
14+
(["hebbian_robot_use_client", "sdk", "typescript-client"], set(SdkTarget)),
15+
],
16+
)
17+
def test_default_sdk_targets_follow_included_components(
18+
tmp_path: Path,
19+
monkeypatch: pytest.MonkeyPatch,
20+
directories: list[str],
21+
expected_targets: set[SdkTarget],
22+
) -> None:
23+
for directory in directories:
24+
(tmp_path / directory).mkdir()
25+
monkeypatch.chdir(tmp_path)
26+
assert available_sdk_targets() == expected_targets
27+
28+
29+
@pytest.mark.parametrize("target", [SdkTarget.RUST, SdkTarget.TYPESCRIPT])
30+
def test_missing_sdk_is_rejected_before_generating_any_output(
31+
tmp_path: Path, monkeypatch: pytest.MonkeyPatch, target: SdkTarget
32+
) -> None:
33+
output = tmp_path / "hebbian_robot_use_client/contract.py"
34+
output.parent.mkdir()
35+
output.write_text("existing client contract\n")
36+
monkeypatch.chdir(tmp_path)
37+
with pytest.raises(ValueError, match="components present in this checkout"):
38+
generate_contracts(frozenset({SdkTarget.PYTHON, target}))
39+
assert output.read_text() == "existing client contract\n"
40+
assert sorted(path.name for path in tmp_path.iterdir()) == [
41+
"hebbian_robot_use_client"
42+
]

‎tests/test_robot_assets.py‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
"""Robot preparation preserves pinned geometry, attribution and offline operation."""
2+
3+
import hashlib
4+
import io
5+
import urllib.request
6+
from pathlib import Path
7+
from zipfile import ZIP_DEFLATED, ZipFile
8+
9+
import pytest
10+
from rua_dev.robot_assets import prepare_robot_assets
11+
12+
ASSET_CONTENTS = {
13+
"robot.urdf": b'<robot name="fixture"><link name="base"/></robot>\n',
14+
"base.stl": b"fixture mesh geometry\n",
15+
"LICENSE.txt": b"fixture model license\n",
16+
"README.md": b"fixture model attribution\n",
17+
}
18+
19+
20+
def create_asset_source(repository: Path) -> tuple[Path, bytes]:
21+
(repository / "robots").mkdir()
22+
archive_buffer = io.BytesIO()
23+
with ZipFile(archive_buffer, "w", compression=ZIP_DEFLATED) as archive:
24+
for name, content in ASSET_CONTENTS.items():
25+
archive.writestr(f"model/{name}", content)
26+
archive.writestr("unrelated/private.txt", b"not a robot asset")
27+
archive_content = archive_buffer.getvalue()
28+
archive_digest = hashlib.sha256(archive_content).hexdigest()
29+
manifest = repository / "robots/so101-assets.toml"
30+
manifest.write_text(
31+
'archive_url = "https://offline.invalid/so101.whl"\n'
32+
f'archive_sha256 = "{archive_digest}"\n'
33+
'archive_prefix = "model/"\n\n[files]\n'
34+
+ "".join(
35+
f'"{name}" = "{hashlib.sha256(content).hexdigest()}"\n'
36+
for name, content in ASSET_CONTENTS.items()
37+
)
38+
)
39+
cache = repository / ".cache/so101"
40+
cache.mkdir(parents=True)
41+
(cache / f"{archive_digest}.whl").write_bytes(archive_content)
42+
return manifest, archive_content
43+
44+
45+
def test_cached_release_prepares_exact_assets_and_repairs_tampering_offline(
46+
tmp_path: Path,
47+
) -> None:
48+
create_asset_source(tmp_path)
49+
assets = prepare_robot_assets(tmp_path)
50+
assert {asset.name: asset.read_bytes() for asset in assets} == ASSET_CONTENTS
51+
assert not (tmp_path / "robots/so101/private.txt").exists()
52+
(tmp_path / "robots/so101/base.stl").write_bytes(b"unreviewed local edit")
53+
prepare_robot_assets(tmp_path)
54+
assert (
55+
tmp_path / "robots/so101/base.stl"
56+
).read_bytes() == b"fixture mesh geometry\n"
57+
# Once prepared, the runtime files alone are sufficient, even without a cache.
58+
for cached_archive in (tmp_path / ".cache/so101").iterdir():
59+
cached_archive.unlink()
60+
assert {
61+
asset.name: asset.read_bytes() for asset in prepare_robot_assets(tmp_path)
62+
} == ASSET_CONTENTS
63+
64+
65+
def test_untrusted_download_does_not_replace_existing_geometry(
66+
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
67+
) -> None:
68+
create_asset_source(tmp_path)
69+
destination = tmp_path / "robots/so101"
70+
destination.mkdir()
71+
(destination / "robot.urdf").write_bytes(b"previous geometry")
72+
for cached_archive in (tmp_path / ".cache/so101").iterdir():
73+
cached_archive.unlink()
74+
75+
def download_archive(url: str, timeout: int) -> io.BytesIO:
76+
return io.BytesIO(b"corrupt download")
77+
78+
monkeypatch.setattr(urllib.request, "urlopen", download_archive)
79+
with pytest.raises(ValueError, match="archive checksum"):
80+
prepare_robot_assets(tmp_path)
81+
assert (destination / "robot.urdf").read_bytes() == b"previous geometry"
82+
assert sorted(path.name for path in destination.iterdir()) == ["robot.urdf"]
83+
84+
85+
def test_mismatched_asset_pin_rejects_the_entire_update(tmp_path: Path) -> None:
86+
manifest, _ = create_asset_source(tmp_path)
87+
destination = tmp_path / "robots/so101"
88+
destination.mkdir()
89+
(destination / "robot.urdf").write_bytes(b"previous geometry")
90+
manifest.write_text(
91+
manifest.read_text().replace(
92+
hashlib.sha256(ASSET_CONTENTS["LICENSE.txt"]).hexdigest(), "0" * 64
93+
)
94+
)
95+
with pytest.raises(ValueError, match="asset checksum"):
96+
prepare_robot_assets(tmp_path)
97+
assert (destination / "robot.urdf").read_bytes() == b"previous geometry"
98+
assert sorted(path.name for path in destination.iterdir()) == ["robot.urdf"]
99+
100+
101+
@pytest.mark.parametrize(
102+
"filename", ["../outside.stl", "/outside.stl", "..\\outside.stl"]
103+
)
104+
def test_asset_pin_cannot_write_outside_its_generated_directory(
105+
tmp_path: Path, filename: str
106+
) -> None:
107+
manifest, _ = create_asset_source(tmp_path)
108+
# Literal TOML keys preserve backslashes for the traversal case.
109+
manifest.write_text(manifest.read_text() + f"'{filename}' = '{'0' * 64}'\n")
110+
with pytest.raises(ValueError, match="filename"):
111+
prepare_robot_assets(tmp_path)
112+
assert not (tmp_path / "robots/so101").exists()
113+
assert not (tmp_path / "robots/outside.stl").exists()

‎tooling/pyproject.toml‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
[project]
2+
name = "rua-dev"
3+
version = "0.1.0"
4+
description = "Development and release commands for the RUA source checkout"
5+
requires-python = ">=3.12"
6+
dependencies = [
7+
"cyclopts>=5.3.2",
8+
"hebbian-robot-use-client==0.1.0",
9+
"jsonref>=1.1.0",
10+
"packaging>=26.3",
11+
"pydantic>=2.11",
12+
"wheel>=0.45",
13+
]
14+
15+
[project.scripts]
16+
rua-dev = "rua_dev.cli:main"
17+
18+
[build-system]
19+
requires = ["uv_build>=0.13.6,<0.14"]
20+
build-backend = "uv_build"
21+
22+
[tool.uv.build-backend]
23+
module-root = ""
24+
module-name = "rua_dev"

‎tooling/rua_dev/__init__.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
"""Source-checkout development commands; never a runtime dependency."""

0 commit comments

Comments
 (0)