feat(utils): resolve_asset_path with @holosoma package alias

Add resolve_asset_path() for turning a config asset string into a concrete path,
and generalize the package-path resolution it shares with resolve_data_file_path.
The package-path trigger widens from the `holosoma/data` prefix (resolved against
files("holosoma.data")) to the `holosoma/` prefix (resolved against
files("holosoma")), and an `@holosoma/...` spelling alias is accepted for both.
Self-locating inputs (holosoma/, @holosoma/, s3://, absolute paths) pass through;
other relative inputs resolve against the package data root.

Motivation: the scene-asset spawners (added in following commits) need one
backend-agnostic way to resolve an asset path regardless of the working directory
or how the package was installed. Widening the prefix to `holosoma/` lets assets
outside data/ (and the @-alias form used by the new scene configs) resolve through
the same code. Note this also changes resolve_data_file_path's accepted prefix for
existing callers — they continue to work because `holosoma/data/...` still matches
the broader `holosoma/` prefix. Covered by test_path_resolution.py.

Author: juan-g-bonilla

src/holosoma/holosoma/utils/path.py

@@ -16,8 +16,9 @@ def resolve_data_file_path(file_path: str) -> str:
     Resolve a data file path.
 
     Handles multiple path formats:
-    1. S3 paths: "s3://bucket/path/to/file.npz" -> return as-is
-    2. Package data paths: "holosoma/data/.../file.npz" -> resolved via importlib.resources
+    1. S3 paths: "s3://bucket/path/to/file.npz" -> returned as-is
+    2. Package paths: "holosoma/..." (or the "@holosoma/..." alias) -> resolved
+       relative to the installed holosoma package via importlib.resources
     3. Absolute paths: "/path/to/file.npz" -> returned as-is
     4. Relative paths: "./data/file.npz" or "../data/file.npz" -> resolved relative to CWD
 
@@ -28,28 +29,32 @@ def resolve_data_file_path(file_path: str) -> str:
         The resolved absolute path as a string
 
     Examples:
-        >>> # Package data
-        >>> path = resolve_data_file_path("holosoma/data/motions/g1_29dof/whole_body_tracking/motion_crawl_slope.npz")
-        >>> print(path)
-        /path/to/installed/holosoma/data/motions/g1_29dof/whole_body_tracking/motion_crawl_slope.npz
+        >>> # Package data (both forms resolve to the same location)
+        >>> resolve_data_file_path("holosoma/data/robots/g1/g1_29dof.xml")
+        '/path/to/installed/holosoma/data/robots/g1/g1_29dof.xml'
+        >>> resolve_data_file_path("@holosoma/data/robots/g1/g1_29dof.xml")
+        '/path/to/installed/holosoma/data/robots/g1/g1_29dof.xml'
 
         >>> # User's custom file (absolute)
-        >>> path = resolve_data_file_path("/home/user/my_motions/custom.npz")
-        >>> print(path)
-        /home/user/my_motions/custom.npz
-
-        >>> # User's custom file (relative)
-        >>> path = resolve_data_file_path("./my_data/custom.npz")
-        >>> print(path)
-        /current/working/dir/my_data/custom.npz
+        >>> resolve_data_file_path("/home/user/my_motions/custom.npz")
+        '/home/user/my_motions/custom.npz'
+
+        >>> # User's custom file (relative to CWD)
+        >>> resolve_data_file_path("./my_data/custom.npz")
+        '/current/working/dir/my_data/custom.npz'
     """
     # 1. If it's an S3 path, return as-is
     if file_path.startswith("s3://"):
         return file_path
-    # 2. If starts with "holosoma/data", use importlib.resources
-    if file_path.startswith("holosoma/data"):
-        suffix = file_path[13:].lstrip("/")  # Remove "holosoma/data" and leading slashes
-        base = files("holosoma.data")
+
+    # 2. Package path. "@holosoma/..." is a spelling alias for "holosoma/...";
+    #    normalize it so both forms resolve via the same importlib.resources path
+    #    (robust for namespace/zipped packages, unlike __file__ arithmetic).
+    if file_path.startswith("@holosoma/"):
+        file_path = file_path[len("@") :]  # "@holosoma/..." -> "holosoma/..."
+    if file_path.startswith("holosoma/"):
+        suffix = file_path[len("holosoma") :].lstrip("/")  # path within the holosoma package
+        base = files("holosoma")
         return str(base / suffix) if suffix else str(base)
 
     # 3. If it's an absolute path, return as-is
@@ -60,3 +65,18 @@ def resolve_data_file_path(file_path: str) -> str:
     # 4. Otherwise, resolve relative path to absolute (relative to CWD)
     resolved = path_obj.resolve()
     return str(resolved)
+
+
+def resolve_asset_path(asset_file: str, asset_root: str | None) -> str:
+    """Resolve an asset path, optionally rooted under ``asset_root``.
+
+    A package path ("holosoma/..." or "@holosoma/...") or an absolute/S3 path is
+    self-locating and resolved directly, ignoring ``asset_root`` — joining a root
+    onto it would turn it into a bogus filesystem path. Only a plain relative path is
+    joined onto ``asset_root`` (when one is given) before resolution. The self-locating
+    cases are exactly the non-CWD-relative branches of :func:`resolve_data_file_path`.
+    """
+    is_self_locating = asset_file.startswith(("holosoma/", "@holosoma/", "s3://")) or Path(asset_file).is_absolute()
+    if asset_root and not is_self_locating:
+        asset_file = f"{asset_root.rstrip('/')}/{asset_file}"
+    return resolve_data_file_path(asset_file)

src/holosoma/tests/utils/test_path_resolution.py

@@ -0,0 +1,88 @@
+"""Unit tests for asset/data path resolution (pure, no simulator).
+
+resolve_data_file_path / resolve_asset_path are the single path-classification layer that
+every backend funnels scene + robot assets through (package "holosoma/..." paths, the
+"@holosoma/..." alias, s3://, absolute, and asset_root-relative). Two real bugs this branch
+fixed lived exactly here (raw ``Path(asset_root)/...`` joins crashing on package paths), so
+each classification branch is locked down below.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+if sys.version_info >= (3, 9):
+    from importlib.resources import files
+else:
+    from importlib_resources import files  # type: ignore[import-not-found]
+
+import pytest
+
+from holosoma.utils.path import resolve_asset_path, resolve_data_file_path
+
+PKG = str(files("holosoma"))  # absolute path of the installed holosoma package
+
+
+# ----- resolve_data_file_path: one assertion per input class -----
+
+
+def test_s3_path_returned_as_is():
+    assert resolve_data_file_path("s3://bucket/path/to/box.usd") == "s3://bucket/path/to/box.usd"
+
+
+def test_package_path_resolves_under_holosoma():
+    assert (
+        resolve_data_file_path("holosoma/data/scene_objects/boxes/small_box.urdf")
+        == f"{PKG}/data/scene_objects/boxes/small_box.urdf"
+    )
+
+
+def test_at_holosoma_alias_resolves_identically():
+    plain = resolve_data_file_path("holosoma/data/scene_objects/boxes/small_box.urdf")
+    alias = resolve_data_file_path("@holosoma/data/scene_objects/boxes/small_box.urdf")
+    assert alias == plain == f"{PKG}/data/scene_objects/boxes/small_box.urdf"
+
+
+def test_package_root_with_trailing_slash_resolves_to_package_dir():
+    # The "holosoma/..." rule keys on the trailing slash; "holosoma/" -> the package dir.
+    # (Bare "holosoma" with no slash is NOT a package path — it's treated as relative.)
+    assert resolve_data_file_path("holosoma/") == PKG
+
+
+def test_absolute_path_returned_as_is():
+    assert resolve_data_file_path("/home/user/custom.npz") == "/home/user/custom.npz"
+
+
+def test_relative_path_resolved_against_cwd():
+    assert resolve_data_file_path("my_data/custom.npz") == str(Path.cwd() / "my_data/custom.npz")
+
+
+# ----- resolve_asset_path: asset_root applies ONLY to plain relative paths -----
+
+
+@pytest.mark.parametrize(
+    "asset_file",
+    [
+        "holosoma/data/scene_objects/boxes/small_box.urdf",
+        "@holosoma/data/scene_objects/boxes/small_box.urdf",
+        "s3://bucket/box.usd",
+        "/abs/box.urdf",
+    ],
+)
+def test_self_locating_paths_ignore_asset_root(asset_file):
+    """Package/alias/s3/absolute paths are self-locating — asset_root must NOT be joined
+    (joining would produce a bogus filesystem path)."""
+    assert resolve_asset_path(asset_file, asset_root="/some/root") == resolve_data_file_path(asset_file)
+
+
+def test_relative_path_joined_onto_asset_root():
+    assert resolve_asset_path("box.urdf", asset_root="/some/root") == resolve_data_file_path("/some/root/box.urdf")
+
+
+def test_relative_path_strips_trailing_slash_on_root():
+    assert resolve_asset_path("box.urdf", asset_root="/some/root/") == resolve_data_file_path("/some/root/box.urdf")
+
+
+def test_relative_path_without_root_falls_back_to_cwd():
+    assert resolve_asset_path("box.urdf", asset_root=None) == str(Path.cwd() / "box.urdf")