Merge pull request #4 from burtenshaw/openenv-cli/v1-ci

Openenv cli/v1 ci

Author: burtenshaw

.github/workflows/pr-new-env-health-check.yml renamed to .github/workflows/pr-new-env.yml

@@ -103,6 +103,7 @@ jobs:
         environment: ${{ fromJSON(needs.detect-new-envs.outputs.new_envs_json) }}
     env:
       HF_TOKEN: ${{ secrets.HF_PR_TOKEN }}
+      HUGGINGFACEHUB_API_TOKEN: ${{ secrets.HF_PR_TOKEN }}
       HF_NAMESPACE: ${{ vars.HF_PR_NAMESPACE }}
       SPACE_SUFFIX: -pr-${{ github.event.number }}
     steps:
@@ -127,18 +128,24 @@ jobs:
             exit 1
           fi
 
-      - name: Install Hugging Face CLI
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install OpenEnv package
         shell: bash
         run: |
-          curl -LsSf https://hf.co/cli/install.sh | bash
-          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+          set -euo pipefail
+          python -m pip install --upgrade pip
+          pip install .
 
-      - name: Deploy environment to Hugging Face
+      - name: Deploy environment with OpenEnv CLI
         shell: bash
         run: |
           set -euo pipefail
-          chmod +x scripts/deploy_to_hf.sh
-          ./scripts/deploy_to_hf.sh --env "${{ matrix.environment }}" --space-suffix "${SPACE_SUFFIX}"
+          repo_id="${HF_NAMESPACE}/${{ matrix.environment }}${SPACE_SUFFIX}"
+          openenv push "${{ matrix.environment }}" --repo-id "$repo_id"
 
       - name: Wait for deployment to stabilize
         shell: bash
@@ -161,13 +168,15 @@ jobs:
           health_url="https://${namespace_slug}-${space_slug}.hf.space/health"
           live_url="https://${namespace_slug}-${space_slug}.hf.space"
           space_repo_url="https://huggingface.co/spaces/${HF_NAMESPACE}/${space_name}"
+          space_repo_id="${HF_NAMESPACE}/${space_name}"
 
           echo "namespace_slug=${namespace_slug}" >> "$GITHUB_OUTPUT"
           echo "space_name=${space_name}" >> "$GITHUB_OUTPUT"
           echo "space_slug=${space_slug}" >> "$GITHUB_OUTPUT"
           echo "health_url=${health_url}" >> "$GITHUB_OUTPUT"
           echo "live_url=${live_url}" >> "$GITHUB_OUTPUT"
           echo "space_repo_url=${space_repo_url}" >> "$GITHUB_OUTPUT"
+          echo "space_repo_id=${space_repo_id}" >> "$GITHUB_OUTPUT"
 
       - name: Perform environment health check
         id: health_check
@@ -216,41 +225,100 @@ jobs:
           SPACE_NAME: ${{ steps.urls.outputs.space_name }}
           LIVE_URL: ${{ steps.urls.outputs.live_url }}
           SPACE_REPO_URL: ${{ steps.urls.outputs.space_repo_url }}
+          SPACE_REPO_ID: ${{ steps.urls.outputs.space_repo_id }}
           ENV_NAME: ${{ matrix.environment }}
+          COMMENT_TAG: "<!-- openenv-pr-preview -->"
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           script: |
             const status = process.env.HEALTH_CONCLUSION || 'failure';
             const spaceName = process.env.SPACE_NAME;
             const liveUrl = process.env.LIVE_URL;
             const repoUrl = process.env.SPACE_REPO_URL;
+            const repoId = process.env.SPACE_REPO_ID;
             const envName = process.env.ENV_NAME;
+            const marker = process.env.COMMENT_TAG;
 
             const header = status === 'success'
-              ? `✅ Deployment succeeded for \`${envName}\``
-              : `⚠️ Deployment failed for \`${envName}\``;
+              ? `✅ Deployment to Hugging Face succeeded for \`${envName}\``
+              : `⚠️ Deployment Hugging Face failed for \`${envName}\``;
 
             const summary = status === 'success'
-              ? 'Nice work! Wait for a code review and we\'re ready to go.'
-              : 'Please resolve your environment.';
+              ? 'Nice work! Wait for a code review and we\'re ready to go. You can test it with the CLI:'
+              : 'Please resolve your environment and test it with the CLI:';
 
             const body = [
+              marker,
+              '',
               header,
               '',
-              `- Space repo: [${repoUrl}](${repoUrl})`,
-              `- Live URL: [${liveUrl}](${liveUrl})`,
               '',
               summary,
               '',
-              'You can iterate locally or validate fixes by running `scripts/deploy_to_hf.sh --env "' + envName + '"`.'
+              '- `openenv push ' + envName + ' --repo-id ' + repoId + '`',
             ].join('\n');
 
-            await github.rest.issues.createComment({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              issue_number: context.payload.pull_request.number,
-              body
-            });
+            const {owner, repo} = context.repo;
+            const issue_number = context.payload.pull_request.number;
+
+            const existing = await github.paginate(
+              github.rest.issues.listComments,
+              { owner, repo, issue_number, per_page: 100 },
+              (response, done) => {
+                const match = response.data.find(comment => comment.body && comment.body.includes(marker));
+                if (match) {
+                  done();
+                  return [match];
+                }
+                return [];
+              }
+            );
+
+            if (existing.length > 0) {
+              await github.rest.issues.updateComment({
+                owner,
+                repo,
+                comment_id: existing[0].id,
+                body,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner,
+                repo,
+                issue_number,
+                body,
+              });
+            }
+
+      - name: Delete preview space on Hugging Face
+        if: always()
+        continue-on-error: true
+        shell: bash
+        env:
+          SPACE_REPO_ID: ${{ steps.urls.outputs.space_repo_id }}
+        run: |
+          set -euo pipefail
+          if [ -z "${SPACE_REPO_ID:-}" ]; then
+            echo "No space repo id; skipping deletion"
+            exit 0
+          fi
+
+          TOKEN="${HF_TOKEN:-${HUGGINGFACEHUB_API_TOKEN:-}}"
+          if [ -z "$TOKEN" ]; then
+            echo "HF token not available; cannot delete space"
+            exit 0
+          fi
+
+          set +e
+          hf repo delete "$SPACE_REPO_ID" --repo-type space --yes --token "$TOKEN"
+          status=$?
+          set -e
+
+          if [ $status -eq 0 ]; then
+            echo "Deleted preview space $SPACE_REPO_ID"
+          else
+            echo "Failed to delete space $SPACE_REPO_ID (exit $status)"
+          fi
 
       - name: Fail job if health check failed
         if: steps.health_check.conclusion == 'failure'

.github/workflows/publish-pypi-core.yml

@@ -36,6 +36,8 @@ jobs:
     - name: Build package
       run: |
         cd src/core
+        # Verify openenv_cli is accessible
+        ls -la ../openenv_cli || echo "Warning: openenv_cli directory not found"
         python -m build
 
     - name: Check package

README.md

@@ -143,6 +143,118 @@ To use an environment:
 
 See example scripts in `examples/` directory.
 
+### Deploying Environments to Hugging Face Spaces
+
+The OpenEnv CLI provides a self-service workflow for publishing environments to Hugging Face Spaces. This enables community members to share environments without requiring adding them as examples to this repo. 
+
+#### Installation
+
+The CLI is installed as part of the OpenEnv package:
+
+```bash
+pip install -e .
+```
+
+#### Push Environment
+
+Push an environment to Hugging Face Spaces:
+
+```bash
+openenv push <env_name> [options]
+```
+
+**Arguments:**
+- `env_name`: Name of the environment to push (e.g., `echo_env`, `coding_env`)
+
+**Options:**
+- `--repo-id <repo_id>`: Hugging Face repository ID in format `namespace/space-name`. If not provided, uses `{username}/{env_name}`.
+- `--private`: Create a private space (default: public)
+- `--base-image <image>`: Base Docker image to use (default: `ghcr.io/meta-pytorch/openenv-base:latest`)
+- `--dry-run`: Prepare files but don't upload to Hugging Face
+
+**Examples:**
+
+```bash
+# Push echo_env to your personal namespace
+openenv push echo_env
+
+# Push to a specific organization
+openenv push coding_env --repo-id my-org/coding_env
+
+# Push with a custom space name
+openenv push echo_env --repo-id my-org/my-custom-space
+
+# Create a private space
+openenv push echo_env --private
+
+# Use a custom base image
+openenv push echo_env --base-image ghcr.io/my-org/custom-base:latest
+
+# Prepare files without uploading
+openenv push echo_env --dry-run
+```
+
+#### How It Works
+
+The `openenv push` command performs the following steps:
+
+1. **Validation**: Checks that the environment exists in `src/envs/<env_name>/`
+2. **Authentication**: Ensures you're authenticated with Hugging Face via interactive login (prompts if needed)
+3. **Space Provisioning**: Determines the target Space repository ID (uses `--repo-id` if provided, otherwise `{username}/{env_name}`). Creates the Docker Space if needed (using `exist_ok=True` to handle existing spaces automatically)
+4. **Build Process**:
+   - Creates a staging directory
+   - Copies core and environment files
+   - Generates/modifies Dockerfile with web interface enabled
+   - Prepares README: If the environment's README already has Hugging Face front matter (starts and ends with `---`), uses it as-is. Otherwise, generates front matter with random emoji and colors from approved options
+5. **Deployment**: Uploads all files to the Hugging Face Space
+6. **Cleanup**: Removes staging directory after successful upload
+
+All pushed environments automatically include the web interface, available at `/web` on deployed spaces.
+
+For more details on the CLI architecture and development, see [`src/openenv_cli/README.md`](src/openenv_cli/README.md).
+
+## CLI Troubleshooting
+
+### Authentication Issues
+
+**Problem**: "Failed to retrieve token after login" or authentication errors
+
+**Solution**: 
+- Check that `huggingface_hub` is properly installed: `pip install --upgrade huggingface_hub`
+- Try logging in via the Hugging Face CLI: `huggingface-cli login`
+- Clear cached credentials if needed (credentials are stored by `huggingface_hub`)
+- Ensure you have "write" permissions on the namespace where you're pushing
+
+### Space Creation Fails
+
+**Problem**: "Failed to create space" or "Permission denied"
+
+**Solution**:
+- Check that namespace/username is correct
+- Verify you have permission to create spaces in that namespace
+- If the space already exists, `exist_ok=True` handles it automatically (you may see a warning from the Hub CLI)
+- For authentication errors, see "Authentication Issues" above
+
+### Upload Fails
+
+**Problem**: "Failed to upload to space"
+
+**Solution**:
+- Check internet connection
+- Verify you're still authenticated (may need to log in again)
+- Try `--dry-run` first to check file preparation
+- Check staging directory exists and has files
+- Verify you have write permissions on the target space
+
+### Environment Not Found
+
+**Problem**: "Environment 'xyz' not found"
+
+**Solution**:
+- Verify environment exists in `src/envs/<env_name>/`
+- Check spelling of environment name
+- Ensure environment directory has required structure (models.py, server/, etc.)
+
 ## Design Principles
 
 1. **Separation of Concerns**: Clear client-server boundaries

pyproject.toml

@@ -12,11 +12,23 @@ dependencies = [
     "requests>=2.25.0",
     "fastapi>=0.104.0",
     "uvicorn>=0.24.0",
-    "smolagents>=1.22.0,<2"
+    "smolagents>=1.22.0,<2",
+    "huggingface_hub>=0.20.0",
+    "rich>=13.0.0",
 ]
 
 [tool.setuptools]
 package-dir = {"" = "src"}
 
 [tool.setuptools.packages.find]
 where = ["src"]
+
+[project.scripts]
+openenv = "openenv_cli.__main__:main"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-mock>=3.10.0",
+    "pytest-cov>=4.0.0"
+]

scripts/deploy_to_hf.sh

@@ -75,6 +75,10 @@ while [[ $# -gt 0 ]]; do
             ENV_NAME="$2"
             shift 2
             ;;
+        --hub-tag)
+            HUB_TAG="$2"
+            shift 2
+            ;;
         --base-sha|--base-image-sha)
             BASE_IMAGE_SHA="$2"
             shift 2
@@ -127,6 +131,10 @@ while [[ $# -gt 0 ]]; do
     esac
 done
 
+if [ -z "$HUB_TAG" ]; then
+    HUB_TAG="openenv"
+fi
+
 if [ -z "$ENV_NAME" ]; then
     echo "Error: Environment name is required" >&2
     usage
@@ -364,6 +372,8 @@ sdk: docker
 pinned: false
 app_port: 8000
 base_path: /web
+tags:
+  - ${HUB_TAG}
 ---
 
 # ${env_title} Environment Server

src/core/pyproject.toml

@@ -18,8 +18,14 @@ dependencies = [
     "requests>=2.25.0",
     "fastapi>=0.104.0",
     "uvicorn>=0.24.0",
+    "huggingface_hub>=0.20.0",
+    "rich>=13.0.0",
+    "typer>=0.12.0",
 ]
 
+[project.scripts]
+openenv = "openenv_cli.__main__:main"
+
 [project.optional-dependencies]
 dev = [
     "pytest>=7.0.0",
@@ -41,6 +47,10 @@ packages = [
     "openenv_core.containers",
     "openenv_core.containers.runtime",
     "openenv_core.env_server",
-    "openenv_core.tools"
+    "openenv_core.tools",
+    "openenv_cli",
+    "openenv_cli.commands",
+    "openenv_cli.core",
+    "openenv_cli.utils",
 ]
-package-dir = {"openenv_core" = "."}
+package-dir = {"openenv_core" = ".", "openenv_cli" = "../openenv_cli"}

src/envs/atari_env/README.md

@@ -1,8 +1,8 @@
 ---
 title: Atari Environment Server
 emoji: 🕹️
-colorFrom: '#FF6200'
-colorTo: '#D4151B'
+colorFrom: yellow
+colorTo: red
 sdk: docker
 pinned: false
 app_port: 8000