vuer-cli 0.0.1__tar.gz → 0.0.2__tar.gz

vuer_cli-0.0.2/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: vuer-cli
+Version: 0.0.2
+Summary: A Python CLI for Vuer, a real-time 3D visualization library
+Project-URL: Homepage, https://github.com/vuer-ai/vuer-cli
+Project-URL: Repository, https://github.com/vuer-ai/vuer-cli
+Project-URL: Issues, https://github.com/vuer-ai/vuer-cli/issues
+Author-email: Ge Yang <ge.ike.yang@gmail.com>
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Requires-Dist: params-proto>=3.0.0rc9
+Requires-Dist: requests>=2.31.0
+Requires-Dist: tqdm>=4.66.0
+Provides-Extra: all
+Provides-Extra: docs
+Requires-Dist: furo; extra == 'docs'
+Requires-Dist: myst-parser; extra == 'docs'
+Requires-Dist: sphinx-autobuild; extra == 'docs'
+Requires-Dist: sphinx-copybutton; extra == 'docs'
+Requires-Dist: sphinx>=4.0; extra == 'docs'
+Requires-Dist: tomli>=1.1.0; (python_version < '3.11') and extra == 'docs'
+Provides-Extra: example
+Description-Content-Type: text/markdown
+
+# Vuer Hub Environment Manager
+
+Vuer HUB and the vuer command line tool enable you to manage, version-control,
+and distribute physical simulation environments the same way you manage
+software packages.
+
+## Installation
+
+```bash
+pip install vuer-cli
+```
+
+## Environment Variables
+
+| Variable          | Required | Description                                                              |
+|-------------------|----------|--------------------------------------------------------------------------|
+| `VUER_AUTH_TOKEN` | ✅        | JWT token used for all authenticated requests                            |
+| `VUER_HUB_URL`    | ✅        | Base URL of the Vuer Hub API (required — no default; e.g. `https://hub.vuer.ai/api`) |
+
+## Commands
+
+| Command        | Description                                                           |
+|----------------|-----------------------------------------------------------------------|
+| `vuer`         | Show top-level help and list available commands                       |
+| `vuer --help`  | Show detailed CLI help                                                 |
+| `sync`         | Sync all environments from environment.json dependencies (like npm install) |
+| `add`          | Add an environment dependency to environment.json                     |
+| `remove`       | Remove an environment dependency from environment.json                |
+| `upgrade`      | Upgrade an environment dependency in environment.json to latest       |
+| `envs-publish` | Publish an environment version                                        |
+| `envs-pull`    | Download an environment by ID or `name/version`                       |
+
+## Usage
+
+Quick start — configure environment variables
+
+`VUER_HUB_URL` is required and has no default. Set it to the base URL of your Vuer Hub API.
+
+```bash
+export VUER_HUB_URL="https://hub.vuer.ai/api"
+# Optional: token for private hubs or authenticated operations
+export VUER_AUTH_TOKEN="eyJhbGci..."
+# Optional: enable dry-run mode to simulate operations (no network changes)
+export VUER_CLI_DRY_RUN="1"
+```
+
+```bash
+# Sync all environments from environment.json dependencies
+# Reads environment.json in current directory, validates dependencies,
+# and downloads all environments (including transitive deps) to vuer_environments/
+vuer sync
+vuer sync --output ./my-envs
+
+# Publish an environment (requires environment.json in the directory)
+vuer envs-publish --directory ./my-environment
+
+# Pull an environment (download and unpack into a directory)
+vuer envs-pull <environmentId>
+vuer envs-pull my-environment/1.0.0
+
+# Add an environment
+vuer add --env <environmentId>
+```
+
+### Sync Command Details
+
+The `sync` command works like `npm install`:
+
+1. Reads `environment.json` from the current directory
+2. Parses the `dependencies` field (e.g., `{"some-dependency": "1.2.3"}`)
+3. Validates all dependencies exist in the backend
+4. Fetches transitive dependencies for each environment
+5. Downloads all environments (direct + transitive) to `vuer_environments/` directory
+6. Preserves `environment.json` inside downloaded environment directories
+
+Publishing metadata (used by `envs-publish`)
+
+```json
+{
+  "name": "my-environment",
+  "version": "v1.0.0",
+  "description": "Demo robotic arm env",
+  "visibility": "PUBLIC",
+  "env-type": "isaac",
+  "dependencies": {
+    "my-environment-1": "v4.0.0"
+  }
+}
+```
+
+Fields and recommendations for publishing metadata
+- **name** (string, required): logical name of the environment (no slashes). This becomes the directory name under `vuer_environments/<name>/<version>/` when downloaded.
+- **version** (string, required): environment version string. Use a stable, reproducible format (we recommend semantic style like `v1.0.0`).
+- **description** (string, optional): short human-readable description of the environment.
+- **visibility** (string, optional): publishing visibility, commonly `PUBLIC` or `PRIVATE`.
+- **env-type** (string, optional): environment runtime/type identifier (for example `isaac`, `gazebo`, etc.).
+- **dependencies** (object, optional): mapping of dependency-name → version (e.g. `"some-dependency": "v1.2.3"`). These declare upstream environment dependencies and are validated during publish.
+
+Publishing notes
+- `envs-publish` expects the target directory to contain a valid `environment.json`. At minimum `name` and `version` must be present; `envs-publish` will validate metadata before uploading to `VUER_HUB_URL`.
+- The `environment.json` baked into an environment package is preserved when that package is later downloaded to `vuer_environments/<name>/<version>/`.
+- Keep the publishing `environment.json` authoritative: use `dependencies` to declare exact `name → version` mappings for transitive resolution.
+
+Project-level `environment.json` used by `vuer sync`
+
+For projects that consume environments (i.e., run `vuer sync`), you usually keep a simple `environment.json` at the project root that focuses on the `dependencies` map:
+
+```json
+{
+  "dependencies": {
+    "some-dependency": "v1.2.3",
+    "another-dependency": "v4.5.6"
+  }
+}
+```
+
+Note: The project-level `environment.json` used by `vuer sync` typically only needs a `dependencies` mapping. The publishing `environment.json` (shown above) must include `name` and `version`.
+
+Use `vuer <command> --help` for full options.
+
+### Add Command Details
+
+- Purpose: add an environment dependency to the current directory's `environment.json`.
+- Input: an environment identifier in canonical `name/version` form or a hub-specific environment ID (example: `my-environment/1.0.0`).
+- Behavior: validates the environment exists on the configured `VUER_HUB_URL` and updates the `dependencies` section of `environment.json`. Run `vuer sync` afterwards to download the environment and its transitive dependencies into `vuer_environments/`.
+
+### Remove Command Details
+
+- Purpose: remove a specific environment dependency from the current directory's `environment.json`.
+- Input: a canonical `name/version` spec (exact match required).
+- Behavior: removes only the exact `name/version` entry from `environment.json`. If the corresponding version directory exists under `vuer_environments/<name>/<version>/`, the local copy will be removed; empty parent directories are cleaned up automatically.
+
+### Upgrade Command Details
+
+- Purpose: update an existing dependency in `environment.json` to a newer version.
+- Input: a dependency name (to upgrade to the latest available) or an explicit `name/version` to target.
+- Behavior: queries the configured hub for available versions, updates `environment.json` with the selected version, and leaves installation to `vuer sync`.
+
+### envs-publish Command Details
+
+- Purpose: publish a prepared environment directory to the configured hub.
+- Input: a local directory containing an `environment.json` and environment content.
+- Behavior: validates the local environment metadata, then uploads the environment as a new version to `VUER_HUB_URL`. Authenticated operations require `VUER_AUTH_TOKEN`.
+
+### envs-pull Command Details
+
+- Purpose: download an environment from the hub and place it into a local directory.
+- Input: a hub environment ID or canonical `name/version` (e.g., `my-environment/1.0.0`).
+- Behavior: downloads the environment and creates the nested path `vuer_environments/<name>/<version>/` (or an alternate `--output` path), preserving the bundled `environment.json` metadata.

vuer_cli-0.0.2/README.md

@@ -0,0 +1,149 @@
+# Vuer Hub Environment Manager
+
+Vuer HUB and the vuer command line tool enable you to manage, version-control,
+and distribute physical simulation environments the same way you manage
+software packages.
+
+## Installation
+
+```bash
+pip install vuer-cli
+```
+
+## Environment Variables
+
+| Variable          | Required | Description                                                              |
+|-------------------|----------|--------------------------------------------------------------------------|
+| `VUER_AUTH_TOKEN` | ✅        | JWT token used for all authenticated requests                            |
+| `VUER_HUB_URL`    | ✅        | Base URL of the Vuer Hub API (required — no default; e.g. `https://hub.vuer.ai/api`) |
+
+## Commands
+
+| Command        | Description                                                           |
+|----------------|-----------------------------------------------------------------------|
+| `vuer`         | Show top-level help and list available commands                       |
+| `vuer --help`  | Show detailed CLI help                                                 |
+| `sync`         | Sync all environments from environment.json dependencies (like npm install) |
+| `add`          | Add an environment dependency to environment.json                     |
+| `remove`       | Remove an environment dependency from environment.json                |
+| `upgrade`      | Upgrade an environment dependency in environment.json to latest       |
+| `envs-publish` | Publish an environment version                                        |
+| `envs-pull`    | Download an environment by ID or `name/version`                       |
+
+## Usage
+
+Quick start — configure environment variables
+
+`VUER_HUB_URL` is required and has no default. Set it to the base URL of your Vuer Hub API.
+
+```bash
+export VUER_HUB_URL="https://hub.vuer.ai/api"
+# Optional: token for private hubs or authenticated operations
+export VUER_AUTH_TOKEN="eyJhbGci..."
+# Optional: enable dry-run mode to simulate operations (no network changes)
+export VUER_CLI_DRY_RUN="1"
+```
+
+```bash
+# Sync all environments from environment.json dependencies
+# Reads environment.json in current directory, validates dependencies,
+# and downloads all environments (including transitive deps) to vuer_environments/
+vuer sync
+vuer sync --output ./my-envs
+
+# Publish an environment (requires environment.json in the directory)
+vuer envs-publish --directory ./my-environment
+
+# Pull an environment (download and unpack into a directory)
+vuer envs-pull <environmentId>
+vuer envs-pull my-environment/1.0.0
+
+# Add an environment
+vuer add --env <environmentId>
+```
+
+### Sync Command Details
+
+The `sync` command works like `npm install`:
+
+1. Reads `environment.json` from the current directory
+2. Parses the `dependencies` field (e.g., `{"some-dependency": "1.2.3"}`)
+3. Validates all dependencies exist in the backend
+4. Fetches transitive dependencies for each environment
+5. Downloads all environments (direct + transitive) to `vuer_environments/` directory
+6. Preserves `environment.json` inside downloaded environment directories
+
+Publishing metadata (used by `envs-publish`)
+
+```json
+{
+  "name": "my-environment",
+  "version": "v1.0.0",
+  "description": "Demo robotic arm env",
+  "visibility": "PUBLIC",
+  "env-type": "isaac",
+  "dependencies": {
+    "my-environment-1": "v4.0.0"
+  }
+}
+```
+
+Fields and recommendations for publishing metadata
+- **name** (string, required): logical name of the environment (no slashes). This becomes the directory name under `vuer_environments/<name>/<version>/` when downloaded.
+- **version** (string, required): environment version string. Use a stable, reproducible format (we recommend semantic style like `v1.0.0`).
+- **description** (string, optional): short human-readable description of the environment.
+- **visibility** (string, optional): publishing visibility, commonly `PUBLIC` or `PRIVATE`.
+- **env-type** (string, optional): environment runtime/type identifier (for example `isaac`, `gazebo`, etc.).
+- **dependencies** (object, optional): mapping of dependency-name → version (e.g. `"some-dependency": "v1.2.3"`). These declare upstream environment dependencies and are validated during publish.
+
+Publishing notes
+- `envs-publish` expects the target directory to contain a valid `environment.json`. At minimum `name` and `version` must be present; `envs-publish` will validate metadata before uploading to `VUER_HUB_URL`.
+- The `environment.json` baked into an environment package is preserved when that package is later downloaded to `vuer_environments/<name>/<version>/`.
+- Keep the publishing `environment.json` authoritative: use `dependencies` to declare exact `name → version` mappings for transitive resolution.
+
+Project-level `environment.json` used by `vuer sync`
+
+For projects that consume environments (i.e., run `vuer sync`), you usually keep a simple `environment.json` at the project root that focuses on the `dependencies` map:
+
+```json
+{
+  "dependencies": {
+    "some-dependency": "v1.2.3",
+    "another-dependency": "v4.5.6"
+  }
+}
+```
+
+Note: The project-level `environment.json` used by `vuer sync` typically only needs a `dependencies` mapping. The publishing `environment.json` (shown above) must include `name` and `version`.
+
+Use `vuer <command> --help` for full options.
+
+### Add Command Details
+
+- Purpose: add an environment dependency to the current directory's `environment.json`.
+- Input: an environment identifier in canonical `name/version` form or a hub-specific environment ID (example: `my-environment/1.0.0`).
+- Behavior: validates the environment exists on the configured `VUER_HUB_URL` and updates the `dependencies` section of `environment.json`. Run `vuer sync` afterwards to download the environment and its transitive dependencies into `vuer_environments/`.
+
+### Remove Command Details
+
+- Purpose: remove a specific environment dependency from the current directory's `environment.json`.
+- Input: a canonical `name/version` spec (exact match required).
+- Behavior: removes only the exact `name/version` entry from `environment.json`. If the corresponding version directory exists under `vuer_environments/<name>/<version>/`, the local copy will be removed; empty parent directories are cleaned up automatically.
+
+### Upgrade Command Details
+
+- Purpose: update an existing dependency in `environment.json` to a newer version.
+- Input: a dependency name (to upgrade to the latest available) or an explicit `name/version` to target.
+- Behavior: queries the configured hub for available versions, updates `environment.json` with the selected version, and leaves installation to `vuer sync`.
+
+### envs-publish Command Details
+
+- Purpose: publish a prepared environment directory to the configured hub.
+- Input: a local directory containing an `environment.json` and environment content.
+- Behavior: validates the local environment metadata, then uploads the environment as a new version to `VUER_HUB_URL`. Authenticated operations require `VUER_AUTH_TOKEN`.
+
+### envs-pull Command Details
+
+- Purpose: download an environment from the hub and place it into a local directory.
+- Input: a hub environment ID or canonical `name/version` (e.g., `my-environment/1.0.0`).
+- Behavior: downloads the environment and creates the nested path `vuer_environments/<name>/<version>/` (or an alternate `--output` path), preserving the bundled `environment.json` metadata.

{vuer_cli-0.0.1 → vuer_cli-0.0.2}/pyproject.toml

@@ -4,11 +4,14 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vuer-cli"
-version = "0.0.1"
+version = "0.0.2"
 description = "A Python CLI for Vuer, a real-time 3D visualization library"
-readme = "README.md"
+readme = { file = "README.md", "content-type" = "text/markdown" }
 license = { text = "MIT" }
 requires-python = ">=3.8"
+authors = [
+    { name = "Ge Yang", email = "ge.ike.yang@gmail.com" }
+]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Programming Language :: Python",
@@ -21,14 +24,29 @@ classifiers = [
     "Operating System :: OS Independent",
 ]
 dependencies = [
-    "params-proto>=3.0.0rc3",
+    "params-proto>=3.0.0rc9",
+    "requests>=2.31.0",
+    "tqdm>=4.66.0",
 ]
 
+[project.urls]
+Homepage = "https://github.com/vuer-ai/vuer-cli"
+Repository = "https://github.com/vuer-ai/vuer-cli"
+Issues = "https://github.com/vuer-ai/vuer-cli/issues"
+
 [project.optional-dependencies]
 all = [
 ]
 example = [
 ]
+docs = [
+    "sphinx>=4.0",
+    "furo",
+    "myst-parser",
+    "sphinx-copybutton",
+    "sphinx-autobuild",
+    "tomli>=1.1.0; python_version < '3.11'",
+]
 
 [project.scripts]
 vuer = "vuer_cli:entrypoint"

vuer_cli-0.0.2/vuer_cli/__init__.py

@@ -0,0 +1,20 @@
+"""Vuer CLI - Environment Manager for Vuer Hub."""
+
+from .add import Add
+from .envs_publish import EnvsPublish, Hub
+from .envs_pull import EnvsPull
+from .main import entrypoint
+from .remove import Remove
+from .sync import Sync
+from .upgrade import Upgrade
+
+__all__ = [
+    "entrypoint",
+    "Hub",
+    "Sync",
+    "Add",
+    "Remove",
+    "Upgrade",
+    "EnvsPublish",
+    "EnvsPull",
+]

vuer_cli-0.0.2/vuer_cli/add.py

@@ -0,0 +1,93 @@
+"""Add command - add an environment spec to environment.json then sync."""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+import json
+
+from .sync import Sync, read_environments_lock
+from .utils import print_error, parse_env_spec, normalize_env_spec
+
+
+# Use shared parser from utils; legacy '@' syntax is not supported anymore.
+
+
+@dataclass
+class Add:
+    """Add an environment to environment.json and run `vuer sync`.
+
+    Example:
+        vuer add some-environment/v1.2.3
+    """
+
+    # NOTE: We keep these fields for params-proto compatibility, but the primary
+    # way to call this command is positional: `vuer add name@version`.
+    env: str = ""  # Environment spec to add, e.g. "some-environment/v1.2.3"
+    name: Optional[str] = None  # Unused in current workflow
+    version: str = "latest"  # Unused in current workflow
+
+    def __call__(self) -> int:
+        """Execute add command."""
+        try:
+            env_spec = self.env
+            if not env_spec:
+                # If env is empty, params-proto likely didn't map the positional arg;
+                # treat this as a usage error.
+                raise ValueError(
+                    "Missing environment spec. Usage: vuer add some-environment/v1.2.3"
+                )
+
+            name, version = parse_env_spec(env_spec)
+            env_spec_normalized = normalize_env_spec(f"{name}/{version}")
+
+            cwd = Path.cwd()
+            lock_path = cwd / "environments-lock.yaml"
+
+            # Step 2: Check if already present in environments-lock.yaml
+            if lock_path.exists():
+                existing_deps = read_environments_lock(lock_path)
+                if env_spec_normalized in existing_deps:
+                    print(f"[INFO] Environment {env_spec_normalized} already present in {lock_path}")
+                    return 0
+
+            # Step 3: Ensure environment.json has this dependency, then run sync
+            env_json_path = cwd / "environment.json"
+            if env_json_path.exists():
+                with env_json_path.open("r", encoding="utf-8") as f:
+                    try:
+                        data = json.load(f)
+                    except json.JSONDecodeError as e:
+                        raise ValueError(
+                            f"Invalid environment.json: {e}"
+                        ) from e
+            else:
+                data = {}
+
+            deps = data.get("dependencies")
+            if deps is None:
+                deps = {}
+            if not isinstance(deps, dict):
+                raise ValueError(
+                    "environment.json 'dependencies' field must be an object"
+                )
+
+            # Add or update the dependency
+            deps[name] = version
+            data["dependencies"] = deps
+
+            with env_json_path.open("w", encoding="utf-8") as f:
+                json.dump(data, f, indent=2, ensure_ascii=False)
+                f.write("\n")
+
+            print(
+                f"[INFO] Added {env_spec_normalized} to environment.json dependencies. Running sync..."
+            )
+            return Sync()()
+
+        except (FileNotFoundError, ValueError, RuntimeError) as e:
+            print_error(str(e))
+            return 1
+        except Exception as e:
+            print_error(f"Unexpected error: {e}")
+            return 1