unitport 0.0.1__tar.gz

unitport-0.0.1/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: unitport
+Version: 0.0.1
+Summary: UnitPort local helper — headless daemon bridging local Isaac Lab / MuJoCo / resources to the UnitPort cloud canvas.
+Author: UnitPort
+License: Proprietary
+Project-URL: Homepage, https://unitport.ai
+Keywords: unitport,isaac-lab,mujoco,reinforcement-learning,robotics
+Classifier: Environment :: No Input/Output (Daemon)
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: websockets>=12
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+
+# unitport — UnitPort local helper
+
+Headless daemon that connects a local **GPU / Isaac Lab host** (workstation *or*
+the user's own cloud server) to the UnitPort **cloud canvas**. The canvas is the
+remote control (遥控器); this process has **no GUI** — only terminal output.
+
+> Authoritative design: `../knowledges/local_helper_design.md`
+> (rulings LH-D1…LH-D6, contracts **C10** pairing / **C11** control protocol).
+
+## What it is (and is not)
+
+- **Is:** an outbound-only WebSocket agent exposing a *fixed* verb set to the
+  cloud (report capabilities, publish an asset index, receive a bundle from the
+  user's own canvas, start/stop a training run, stream telemetry).
+- **Is not:** a shell, an exec server, or a GUI. The cloud can never send an
+  arbitrary command — only the fixed verbs, only from a paired session of the
+  **same account**, only bundles that originate from the user's own canvas
+  (least-privilege red line, LH-D4 / C11).
+
+The same binary serves execution target ① (`UserServerTarget`, user cloud
+server) and ③ (`LocalHelperTarget`, local host) — only the host differs (LH-D5).
+
+## Install
+
+```
+pip install unitport
+```
+
+Cross-platform (Windows + Linux). Runtime deps: `websockets` (the live link) and,
+on Python < 3.11, `tomli` (TOML reader). Everything else is stdlib.
+
+## CLI (headless — everything else is driven remotely from the canvas)
+
+| Command | Purpose |
+|---|---|
+| `unitport login` | Browser-approve device pairing; stores a refreshable helper token |
+| `unitport up` (`serve`) | Dial out to the cloud relay and serve the fixed verb set |
+| `unitport status` | Connection / run state, paired account, config summary |
+| `unitport config` | Declare Isaac/MuJoCo interpreter paths + resource roots |
+| `unitport doctor` | Fail-loud self-check (interpreters, deps, cloud, token) |
+
+There are deliberately **no** `pull` / `train` / `push` local subcommands — those
+are *remote* verbs, triggered from the canvas (C11 §4).
+
+## Config
+
+- Config dir: `%APPDATA%\unitport\` (Windows) · `$XDG_CONFIG_HOME/unitport/`
+  or `~/.config/unitport/` (POSIX). Override with `UNITPORT_HOME`.
+- `config.toml` — cloud base URL, engine interpreter paths, `resource_roots`,
+  workspace dir. Human-editable; also managed by `unitport config`.
+- `token.json` — the helper token (secret; `chmod 600` on POSIX). Never printed,
+  never logged.
+- `device.json` — the persistent (non-secret) `device_id`.
+
+## Status
+
+Under active construction (phases LH-P1…LH-P8, Isaac Lab first). See the design
+doc §12 for the phase map. This tree currently implements the local foundation
+(config, capability detection, doctor, CLI) plus the pairing/transport clients;
+the `workers/relay` Durable Object cloud side lives in `../workers/relay`.

unitport-0.0.1/README.md

@@ -0,0 +1,60 @@
+# unitport — UnitPort local helper
+
+Headless daemon that connects a local **GPU / Isaac Lab host** (workstation *or*
+the user's own cloud server) to the UnitPort **cloud canvas**. The canvas is the
+remote control (遥控器); this process has **no GUI** — only terminal output.
+
+> Authoritative design: `../knowledges/local_helper_design.md`
+> (rulings LH-D1…LH-D6, contracts **C10** pairing / **C11** control protocol).
+
+## What it is (and is not)
+
+- **Is:** an outbound-only WebSocket agent exposing a *fixed* verb set to the
+  cloud (report capabilities, publish an asset index, receive a bundle from the
+  user's own canvas, start/stop a training run, stream telemetry).
+- **Is not:** a shell, an exec server, or a GUI. The cloud can never send an
+  arbitrary command — only the fixed verbs, only from a paired session of the
+  **same account**, only bundles that originate from the user's own canvas
+  (least-privilege red line, LH-D4 / C11).
+
+The same binary serves execution target ① (`UserServerTarget`, user cloud
+server) and ③ (`LocalHelperTarget`, local host) — only the host differs (LH-D5).
+
+## Install
+
+```
+pip install unitport
+```
+
+Cross-platform (Windows + Linux). Runtime deps: `websockets` (the live link) and,
+on Python < 3.11, `tomli` (TOML reader). Everything else is stdlib.
+
+## CLI (headless — everything else is driven remotely from the canvas)
+
+| Command | Purpose |
+|---|---|
+| `unitport login` | Browser-approve device pairing; stores a refreshable helper token |
+| `unitport up` (`serve`) | Dial out to the cloud relay and serve the fixed verb set |
+| `unitport status` | Connection / run state, paired account, config summary |
+| `unitport config` | Declare Isaac/MuJoCo interpreter paths + resource roots |
+| `unitport doctor` | Fail-loud self-check (interpreters, deps, cloud, token) |
+
+There are deliberately **no** `pull` / `train` / `push` local subcommands — those
+are *remote* verbs, triggered from the canvas (C11 §4).
+
+## Config
+
+- Config dir: `%APPDATA%\unitport\` (Windows) · `$XDG_CONFIG_HOME/unitport/`
+  or `~/.config/unitport/` (POSIX). Override with `UNITPORT_HOME`.
+- `config.toml` — cloud base URL, engine interpreter paths, `resource_roots`,
+  workspace dir. Human-editable; also managed by `unitport config`.
+- `token.json` — the helper token (secret; `chmod 600` on POSIX). Never printed,
+  never logged.
+- `device.json` — the persistent (non-secret) `device_id`.
+
+## Status
+
+Under active construction (phases LH-P1…LH-P8, Isaac Lab first). See the design
+doc §12 for the phase map. This tree currently implements the local foundation
+(config, capability detection, doctor, CLI) plus the pairing/transport clients;
+the `workers/relay` Durable Object cloud side lives in `../workers/relay`.

unitport-0.0.1/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "unitport"
+version = "0.0.1"
+description = "UnitPort local helper — headless daemon bridging local Isaac Lab / MuJoCo / resources to the UnitPort cloud canvas."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Proprietary" }
+authors = [{ name = "UnitPort" }]
+keywords = ["unitport", "isaac-lab", "mujoco", "reinforcement-learning", "robotics"]
+classifiers = [
+  "Environment :: No Input/Output (Daemon)",
+  "Operating System :: Microsoft :: Windows",
+  "Operating System :: POSIX :: Linux",
+  "Programming Language :: Python :: 3",
+]
+
+# Runtime deps kept minimal on purpose (LH-D1 "lightweight"):
+#   * websockets — the outbound live link (LH-D2); lazily imported so config/
+#     doctor/capabilities work without it installed.
+#   * tomli      — TOML *reader* backport for Python < 3.11 (stdlib tomllib on
+#     3.11+). We hand-roll the writer, so no writer dep.
+# Everything else (pairing HTTP, atomic IO, capability probes) is pure stdlib.
+dependencies = [
+  "websockets>=12",
+  "tomli>=2.0 ; python_version < '3.11'",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[project.scripts]
+unitport = "unitport.cli:main"
+
+[project.urls]
+Homepage = "https://unitport.ai"
+
+[tool.setuptools]
+packages = ["unitport"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

unitport-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

unitport-0.0.1/tests/test_bundle_security.py

@@ -0,0 +1,71 @@
+"""Least-privilege boundary tests (C11 §7): own-canvas provenance + helper://
+path-escape guard. These must fail LOUD, never degrade."""
+
+from pathlib import Path
+
+import pytest
+
+from unitport import bundle as bundlemod
+from unitport import config as cfgmod
+from unitport import security
+from unitport.errors import SecurityError, VerbError
+
+
+@pytest.fixture
+def home(tmp_path, monkeypatch):
+    monkeypatch.setenv("UNITPORT_HOME", str(tmp_path))
+    return tmp_path
+
+
+def _bundle(uid):
+    return {
+        "run_id": "r1",
+        "backend": "sb3_mujoco",
+        "provenance": {"owner_uid": uid},
+        "env_cfg": {"source": "# cfg\n"},
+        "spec": {},
+        "assets": [],
+    }
+
+
+def test_foreign_bundle_rejected(home):
+    cfgmod.set_workspace(str(home / "ws"))
+    with pytest.raises(SecurityError):
+        bundlemod.materialize(_bundle("someone-else"), paired_uid="me", cfg=cfgmod.load_config())
+
+
+def test_missing_owner_rejected(home):
+    b = _bundle("")
+    with pytest.raises(SecurityError):
+        bundlemod.materialize(b, paired_uid="me", cfg=cfgmod.load_config())
+
+
+def test_helper_uri_inside_root_ok(home):
+    root = home / "assets"
+    root.mkdir()
+    f = root / "go2.xml"
+    f.write_text("<mujoco/>", encoding="utf-8")
+    got = security.resolve_helper_uri(f"helper://{f.as_posix()}", [str(root)])
+    assert got == f.resolve()
+
+
+def test_helper_uri_escape_rejected(home):
+    root = home / "assets"
+    root.mkdir()
+    outside = home / "secret.txt"
+    outside.write_text("nope", encoding="utf-8")
+    with pytest.raises(SecurityError):
+        security.resolve_helper_uri(f"helper://{outside.as_posix()}", [str(root)])
+
+
+def test_helper_uri_no_roots_rejected(home):
+    with pytest.raises(SecurityError):
+        security.resolve_helper_uri("helper:///anything", [])
+
+
+def test_unknown_backend_rejected(home):
+    cfgmod.set_workspace(str(home / "ws"))
+    b = _bundle("me")
+    b["backend"] = "tensorflow_magic"
+    with pytest.raises(VerbError):
+        bundlemod.materialize(b, paired_uid="me", cfg=cfgmod.load_config())

unitport-0.0.1/tests/test_capabilities.py

@@ -0,0 +1,35 @@
+import pytest
+
+from unitport import CAPABILITIES_SCHEMA
+from unitport import capabilities as caps
+
+
+@pytest.fixture
+def home(tmp_path, monkeypatch):
+    monkeypatch.setenv("UNITPORT_HOME", str(tmp_path))
+    return tmp_path
+
+
+def test_manifest_shape(home):
+    m = caps.build_manifest()
+    assert m["schema"] == CAPABILITIES_SCHEMA
+    assert m["host"]["os"] in ("windows", "linux", "darwin", "unknown")
+    assert set(m["engines"]) == {"isaac_lab", "mujoco", "sb3"}
+    for eng in m["engines"].values():
+        assert "installed" in eng
+    assert isinstance(m["gpu"]["nvidia_smi"], list)
+    assert isinstance(m["conda_envs"], list)
+    assert m["reported_at"]
+
+
+def test_isaac_absent_when_unconfigured(home):
+    # No interpreter declared → not installed, never raises.
+    got = caps.detect_isaac_lab({"installs": {}})
+    assert got["installed"] is False
+    assert got["python"] is None
+
+
+def test_isaac_missing_path(home):
+    got = caps.detect_isaac_lab({"installs": {"isaac_lab": {"python": "/no/such/python"}}})
+    assert got["installed"] is False
+    assert got["python_exists"] is False

unitport-0.0.1/tests/test_config.py

@@ -0,0 +1,59 @@
+import os
+import stat
+
+import pytest
+
+from unitport import config as cfgmod
+from unitport.errors import ConfigError
+
+
+@pytest.fixture
+def home(tmp_path, monkeypatch):
+    monkeypatch.setenv("UNITPORT_HOME", str(tmp_path))
+    monkeypatch.delenv("UNITPORT_BASE_URL", raising=False)
+    return tmp_path
+
+
+def test_config_roundtrip_nested_tables(home):
+    cfg = cfgmod.set_engine_python("isaac_lab", r"C:\isaac\python.exe")
+    assert cfg["installs"]["isaac_lab"]["python"] == "C:/isaac/python.exe"
+    # Reloading parses the TOML we wrote back into the same structure.
+    reloaded = cfgmod.load_config()
+    assert reloaded["installs"]["isaac_lab"]["python"] == "C:/isaac/python.exe"
+
+
+def test_add_resource_root_dedupes(home):
+    cfgmod.add_resource_root(r"A:\robots")
+    cfg = cfgmod.add_resource_root("A:/robots")  # same, forward-slash form
+    assert cfg["resource"]["roots"] == ["A:/robots"]
+
+
+def test_base_url_precedence(home, monkeypatch):
+    cfgmod.set_base_url("https://config.example")
+    assert cfgmod.base_url() == "https://config.example"
+    monkeypatch.setenv("UNITPORT_BASE_URL", "https://env.example/")
+    assert cfgmod.base_url() == "https://env.example"
+
+
+def test_device_id_stable(home):
+    a = cfgmod.get_or_create_device_id()
+    b = cfgmod.get_or_create_device_id()
+    assert a == b and len(a) == 32
+
+
+def test_token_roundtrip_and_perms(home):
+    cfgmod.save_token({"access_token": "secret", "uid": "u1", "device_id": "d1"})
+    tok = cfgmod.load_token()
+    assert tok["access_token"] == "secret"
+    if os.name != "nt":  # POSIX: token must be 0600
+        mode = stat.S_IMODE(os.stat(cfgmod.token_path()).st_mode)
+        assert mode == 0o600
+    cfgmod.clear_token()
+    assert cfgmod.load_token() is None
+
+
+def test_malformed_toml_fails_loud(home):
+    cfgmod.config_path().parent.mkdir(parents=True, exist_ok=True)
+    cfgmod.config_path().write_text("this is = = not toml", encoding="utf-8")
+    with pytest.raises(ConfigError):
+        cfgmod.load_config()

unitport-0.0.1/tests/test_e2e_run.py

@@ -0,0 +1,83 @@
+"""In-process end-to-end: receive-bundle → materialize → start-run → telemetry →
+push-results, driven against the mock trainer (no relay, no GPU). Proves the
+LH-P4/P5/P6 plumbing deterministically."""
+
+import sys
+from pathlib import Path
+
+import pytest
+
+from unitport import bundle as bundlemod
+from unitport import config as cfgmod
+from unitport.verbs import HelperContext
+
+MOCK = str(Path(__file__).parent / "mock_trainer.py")
+
+
+@pytest.fixture
+def home(tmp_path, monkeypatch):
+    monkeypatch.setenv("UNITPORT_HOME", str(tmp_path))
+    return tmp_path
+
+
+def _make_bundle(uid, source, run_id="smoke-1"):
+    return {
+        "run_id": run_id,
+        "backend": "sb3_mujoco",
+        "provenance": {"owner_uid": uid},
+        "env_cfg": {"file_name": "unitport_env_cfg.py", "source": source},
+        "spec": {"max_iterations": 3},
+        "assets": [],
+    }
+
+
+def test_receive_start_results(home):
+    cfgmod.save_token({"access_token": "x", "uid": "uid-test", "device_id": "d1"})
+    cfgmod.set_engine_field("sb3_mujoco", "launcher", MOCK)
+    cfgmod.set_engine_field("sb3_mujoco", "python", sys.executable)
+    cfgmod.set_workspace(str(home / "ws"))
+
+    ctx = HelperContext()
+    events = []
+    ctx.emit = events.append
+    assert ctx.paired_uid == "uid-test"
+
+    # 1) receive-bundle → materialize
+    run = bundlemod.materialize(_make_bundle("uid-test", "# env cfg\n"), ctx.paired_uid, ctx.cfg)
+    assert (run.run_dir / "unitport_env_cfg.py").read_text(encoding="utf-8") == "# env cfg\n"
+    assert (run.run_dir / "spec.json").exists()
+    assert (run.run_dir / "run.json").exists()
+    ctx.runs[run.run_id] = {"run": run}
+
+    # 2) start-run → real subprocess (mock trainer) → 3) telemetry
+    runner = ctx.get_runner()
+    runner.start(run)
+    runner.wait(run.run_id, timeout=30)
+
+    tail = [e["payload"] for e in events if e.get("verb") == "tail-logs"]
+    kinds = {p.get("kind") for p in tail}
+    assert "progress" in kinds
+    assert "cmdmetrics" in kinds
+    assert "done_sentinel" in kinds
+    # a progress frame carries iteration/total
+    prog = [p for p in tail if p.get("kind") == "progress"]
+    assert prog and prog[-1]["iteration"] == 3 and prog[-1]["total"] == 3
+
+    # 4) push-results emitted with a checkpoint manifest
+    pushes = [e for e in events if e.get("verb") == "push-results"]
+    assert pushes, "no push-results emitted"
+    payload = pushes[0]["payload"]
+    assert Path(payload["checkpoint"]).exists()
+    man = payload["manifest"]
+    assert man["schema"] == "unitport.resource/bundles@1"
+    assert man["payload"]["bundle_kind"] == "checkpoint"
+    assert man["payload"]["checkpoint_ref"].startswith("helper://")
+    assert man["payload"]["run_id"] == "smoke-1"
+    assert len(man["id"]) == 12  # 12-hex SKU
+
+    # run.json reflects completion
+    import json
+
+    rj = json.loads((run.run_dir / "run.json").read_text(encoding="utf-8"))
+    assert rj["status"] == "completed"
+    assert rj["returncode"] == 0

unitport-0.0.1/tests/test_protocol.py

@@ -0,0 +1,53 @@
+import pytest
+
+from unitport import protocol
+from unitport.errors import ProtocolError, SecurityError
+from unitport.protocol import Verb
+
+
+def test_envelope_roundtrip():
+    env = protocol.make_req(Verb.RECEIVE_BUNDLE, id="1", payload={"a": 1}, run_id="r1")
+    raw = protocol.dumps(env)
+    back = protocol.parse_envelope(raw)
+    assert back["verb"] == Verb.RECEIVE_BUNDLE
+    assert back["run_id"] == "r1"
+    assert back["kind"] == protocol.KIND_REQ
+    assert back["v"] == protocol.PROTOCOL_VERSION
+
+
+def test_parse_rejects_garbage():
+    with pytest.raises(ProtocolError):
+        protocol.parse_envelope("not json")
+    with pytest.raises(ProtocolError):
+        protocol.parse_envelope("[]")  # not an object
+    with pytest.raises(ProtocolError):
+        protocol.parse_envelope('{"v":999,"kind":"req"}')  # bad version
+
+
+def test_gate_allows_cloud_to_helper_verb():
+    env = protocol.make_req(Verb.RECEIVE_BUNDLE, id="1")
+    assert protocol.assert_inbound_allowed(env) == Verb.RECEIVE_BUNDLE
+
+
+def test_gate_rejects_unknown_verb():
+    env = protocol.make_req("rm -rf /", id="1")
+    with pytest.raises(SecurityError):
+        protocol.assert_inbound_allowed(env)
+
+
+def test_gate_rejects_wrong_direction_verb():
+    # The cloud must not be able to *invoke* a helper→cloud-only verb.
+    env = protocol.make_req(Verb.REPORT_CAPABILITIES, id="1")
+    with pytest.raises(SecurityError):
+        protocol.assert_inbound_allowed(env)
+
+
+def test_gate_lets_responses_through():
+    env = protocol.make_res(id="1", payload={"ok": True})
+    assert protocol.assert_inbound_allowed(env) == ""
+
+
+def test_gate_rejects_missing_verb_on_req():
+    env = protocol.make_envelope(protocol.KIND_REQ, id="1")
+    with pytest.raises(SecurityError):
+        protocol.assert_inbound_allowed(env)

unitport-0.0.1/unitport/__init__.py

@@ -0,0 +1,26 @@
+# -*- coding: utf-8 -*-
+"""unitport — UnitPort local helper (headless daemon).
+
+Package-level constants shared across modules. Keep this import cheap: NO heavy
+third-party imports here (websockets etc. are imported lazily where used) so that
+``config`` / ``doctor`` / ``capabilities`` stay usable even in a broken env.
+
+Authoritative design: ``knowledges/local_helper_design.md`` (LH-D1…D6, C10/C11).
+"""
+
+__version__ = "0.0.1"
+
+# Wire / schema identifiers — must match the design doc and the cloud edge.
+CAPABILITIES_SCHEMA = "unitport.helper.capabilities@1"  # design §5
+PROTOCOL_VERSION = 1  # envelope { v, kind, id, verb, run_id?, payload, ts } §2
+
+# Cloud edge (Cloudflare Workers, design §11). Overridable via config.toml
+# [cloud].base_url or the UNITPORT_BASE_URL env var — never hard-required here.
+DEFAULT_BASE_URL = "https://svc.unitport.ai"
+
+__all__ = [
+    "__version__",
+    "CAPABILITIES_SCHEMA",
+    "PROTOCOL_VERSION",
+    "DEFAULT_BASE_URL",
+]

unitport-0.0.1/unitport/__main__.py

@@ -0,0 +1,9 @@
+# -*- coding: utf-8 -*-
+"""Enable ``python -m unitport`` (mirrors the ``unitport`` console script)."""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())