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

vuer_cli-0.0.3/CLAUDE.md

@@ -0,0 +1,8 @@
+
+- Release Procedure:
+1. update pip install and uv add instruction in the README to include the version tag of the current version
+2. push to latest and the version tag in git
+3. publish this version
+
+# Skills
+- params-proto: https://raw.githubusercontent.com/geyang/params-proto/main/skill/index.md

vuer_cli-0.0.3/CONTRIBUTING.md

@@ -0,0 +1,97 @@
+# Development Guide
+
+This project uses modern Python packaging with [uv](https://docs.astral.sh/uv/) and `pyproject.toml`.
+
+## Setup
+
+### Option 1: Using uv (recommended)
+
+Create a virtual environment and install dependencies:
+
+```bash
+uv sync --group dev
+```
+
+Activate the environment:
+
+```bash
+source .venv/bin/activate
+```
+
+### Option 2: Using pip
+
+Install in your current environment (conda, virtualenv, or system Python):
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Common Tasks
+
+### Documentation
+
+Build documentation:
+
+```bash
+make docs
+```
+
+Preview documentation with live reload:
+
+```bash
+make preview-docs
+```
+
+The preview server will start at `http://0.0.0.0:8000`
+
+### Testing
+
+Run tests:
+
+```bash
+make test
+```
+
+### Code Quality
+
+Format code with ruff:
+
+```bash
+ruff format .
+```
+
+Lint code:
+
+```bash
+ruff check .
+```
+
+Fix linting issues automatically:
+
+```bash
+ruff check --fix .
+```
+
+## Project Structure
+
+```
+vuer/
+├── src/vuer/          # Main package source
+├── docs/              # Sphinx documentation
+├── Makefile           # Build tasks
+└── pyproject.toml     # Project configuration
+```
+
+## Publishing
+
+### Using uv (recommended)
+
+1. Update version in `pyproject.toml`
+2. Build the package: `uv build`
+3. Publish: `uv publish`
+
+### Using traditional tools
+
+1. Update version in `pyproject.toml`
+2. Build: `python -m build`
+3. Publish: `twine upload dist/*`

vuer_cli-0.0.3/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: vuer-cli
+Version: 0.0.3
+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.3/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.3/docs/commands/add.md

@@ -0,0 +1,18 @@
+# vuer add
+
+Add an environment dependency to `environment.json` and run `sync`.
+
+## Usage
+
+```bash
+vuer add some-environment/1.2.3
+```
+
+## Behavior
+
+- Validates argument format `name/version`.
+- If `environments-lock.yaml` already contains the exact entry, the command
+  returns success without modifying `environment.json`.
+- Otherwise, it writes or updates `environment.json` and triggers `vuer sync`.
+
+

vuer_cli-0.0.3/docs/commands/index.md

@@ -0,0 +1,17 @@
+# Commands
+
+This section contains the user-facing command documentation. Each command has
+its own page linked below.
+
+```{toctree}
+:maxdepth: 1
+
+sync
+add
+remove
+upgrade
+```
+
+Use `vuer <command> --help` for per-command options.
+
+

vuer_cli-0.0.3/docs/commands/remove.md

@@ -0,0 +1,21 @@
+# vuer remove
+
+Remove an environment dependency from `environment.json` and run `sync`.
+
+## Usage
+
+```bash
+vuer remove some-environment/1.2.3
+```
+
+## Behavior
+
+- Requires `name/version` argument.
+- Only removes the dependency entry if the name and version exactly match the
+  current `environment.json` entry for that name.
+- Triggers `vuer sync` to reconcile local cache.
+
+If removing the last version directory for an environment, `sync` will also
+remove the empty parent `vuer_environments/<name>/` directory.
+
+

vuer_cli-0.0.3/docs/commands/sync.md

@@ -0,0 +1,31 @@
+# vuer sync
+
+Synchronize `environment.json` dependencies with the local cache (`vuer_environments/`).
+
+## Usage
+
+```bash
+vuer sync
+
+# Or specify output directory (optional)
+vuer sync --output ./vuer_environments
+```
+
+## Behavior
+
+1. Locate `environment.json` in the current working directory. If missing, the
+   command fails with an error.
+
+2. Parse `dependencies` and expand transitive dependencies via the backend.
+
+3. Deduplicate and write resolved dependencies to `environments-lock.yaml`.
+
+4. Download missing environments into `vuer_environments/<name>/<version>`.
+   Existing version directories listed in the lockfile are skipped.
+
+5. Remove version directories that are no longer present in the new lockfile.
+
+Dry-run mode (`VUER_CLI_DRY_RUN`) simulates validation and downloading without
+performing network calls.
+
+

vuer_cli-0.0.3/docs/commands/upgrade.md

@@ -0,0 +1,18 @@
+# vuer upgrade
+
+Upgrade a named environment to the latest version available in the backend.
+
+## Usage
+
+```bash
+vuer upgrade some-environment-name
+```
+
+## Behavior
+
+1. Read `environment.json` and locate the dependency by name.
+2. Call backend `/environments/latest-by-name?name=<name>` to fetch latest
+   `versionId`.
+3. If the latest version differs, update `environment.json` and trigger `vuer sync`.
+
+

vuer_cli-0.0.3/docs/concepts.md

@@ -0,0 +1,58 @@
+# Core concepts
+
+This page explains the main concepts used by Vuer CLI.
+
+## Environment Configuration File: `environment.json`
+
+Maintain an `environment.json` file in your project root directory to declare
+the list of environments your project depends on, similar to `package.json` in
+Node.js.
+
+**Example:**
+
+```json
+{
+  "dependencies": {
+    "some-dependency": "^1.2.3",
+    "another-dependency": "~4.5.6",
+    "new-dependency": "0.1.0"
+  }
+}
+```
+
+**`dependencies` field:**
+
+- **Key**: Environment name (e.g., `some-dependency`)
+- **Value**: Version expression (e.g., `^1.2.3`, `~4.5.6`, etc.)
+
+## Local cache: `vuer_environments/`
+
+`vuer sync` downloads direct and transitive dependencies into the
+`vuer_environments/` directory in the project root. Each environment uses a
+nested directory layout `vuer_environments/<name>/<version>`.
+
+Downloaded environment directories may contain their own `environment.json`;
+the CLI preserves these per-version metadata files.
+
+## Dependency index: `environments-lock.yaml`
+
+`vuer sync` generates `environments-lock.yaml` (next to `vuer_environments/`)
+as a system-maintained lockfile that records resolved and deduplicated
+environment dependencies. Do not edit it manually.
+
+Minimal example:
+
+```yaml
+environments:
+  - "some-dependency/^1.2.3"
+  - "another-dependency/~4.5.6"
+```
+
+## Environment variables
+
+- `VUER_HUB_URL` — Base URL of Vuer Hub API (required in non-dry-run)
+- `VUER_AUTH_TOKEN` — JWT token for API access (required in non-dry-run)
+- `VUER_CLI_DRY_RUN` — Enable dry-run mode (any non-"0"/"false" value enables
+  it)
+
+