feat(scripts): remote devcontainer orchestration via just recipe (#70)

.github/actions/setup-env/action.yml

@@ -7,11 +7,15 @@
 # - hadolint (for Containerfile linting in pre-commit)
 # - BATS + helper libraries (for shell script testing)
 #
-# IMPORTANT: The caller must checkout the repository before using this action.
-# This action does NOT checkout code, allowing callers to control ref, token,
-# persist-credentials, and other checkout options.
+# IMPORTANT:
+# - This action does NOT checkout code, allowing callers to control ref, token,
+#   persist-credentials, and other checkout options.
+# - Checkout is only required for operations that read repository files
+#   (for example, sync-dependencies or devcontainer CLI version lookup).
 #
 # Inputs:
+#   install-python:           Install Python (default: true)
+#   python-version:           Python version fallback when pyproject.toml is unavailable (default: '3.12')
 #   sync-dependencies:        Run uv sync to install project deps (default: false)
 #   install-podman:           Install podman (default: false)
 #   install-node:             Install Node.js (default: false)
@@ -25,10 +29,15 @@
 #   uv-version: The version of uv that was installed
 #
 # Usage:
-#   # Minimal (Python + uv only)
+#   # Default (Python + uv only)
 #   - uses: actions/checkout@v4
 #   - uses: ./.github/actions/setup-env
 #
+#   # uv only (skip Python setup)
+#   - uses: ./.github/actions/setup-env
+#     with:
+#       install-python: 'false'
+#
 #   # With project dependencies
 #   - uses: actions/checkout@v4
 #   - uses: ./.github/actions/setup-env
@@ -47,6 +56,14 @@ name: 'Setup Environment'
 description: 'Set up CI environment with Python, uv, and optional tools (podman, Node.js, devcontainer CLI, hadolint, BATS)'
 
 inputs:
+  install-python:
+    description: 'Install Python runtime'
+    required: false
+    default: 'true'
+  python-version:
+    description: 'Python version fallback when pyproject.toml is unavailable'
+    required: false
+    default: '3.12'
   sync-dependencies:
     description: 'Run uv sync to install project dependencies'
     required: false
@@ -87,31 +104,145 @@ inputs:
 outputs:
   uv-version:
     description: 'Version of uv installed'
-    value: ${{ steps.setup-uv.outputs.uv-version }}
+    value: ${{ steps.setup-uv-retry.outputs.uv-version || steps.setup-uv.outputs.uv-version }}
 
 runs:
   using: composite
   steps:
     # ── Python ───────────────────────────────────────────────────────────
-    - name: "Set up Python"
+    - name: "Set up Python from pyproject"
+      if: inputs.install-python == 'true' && hashFiles('pyproject.toml') != ''
       uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6
       with:
         python-version-file: "pyproject.toml"
 
+    - name: "Set up Python fallback"
+      if: inputs.install-python == 'true' && hashFiles('pyproject.toml') == ''
+      uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6
+      with:
+        python-version: ${{ inputs.python-version }}
+
     # ── uv ─────────────────────────────────────────────────────────────
     - name: Install uv
       id: setup-uv
+      continue-on-error: true
+      uses: astral-sh/setup-uv@5a095e7a2014a4212f075830d4f7277575a9d098  # v7
+      with:
+        enable-cache: true
+        # Install a specific version of uv.
+        version: "0.10.0"
+
+    - name: Wait before retrying uv install
+      if: steps.setup-uv.outcome == 'failure'
+      shell: bash
+      run: sleep 15
+
+    - name: Install uv (retry)
+      id: setup-uv-retry
+      if: steps.setup-uv.outcome == 'failure'
       uses: astral-sh/setup-uv@5a095e7a2014a4212f075830d4f7277575a9d098  # v7
       with:
         enable-cache: true
         # Install a specific version of uv.
         version: "0.10.0"
 
+    # ── retry() shell helper ───────────────────────────────────────────
+    - name: Export retry helper function
+      shell: bash
+      run: |
+        set -euo pipefail
+        RETRY_HELPER="$RUNNER_TEMP/setup-env-retry.sh"
+        PREV_BASH_ENV="${BASH_ENV:-}"
+
+        cat > "$RETRY_HELPER" <<'EOF'
+        retry() {
+          local retries=3
+          local backoff=1
+          local max_backoff=60
+          local rc=1
+
+          while [ "$#" -gt 0 ]; do
+            case "$1" in
+              --retries)
+                retries="$2"
+                shift 2
+                ;;
+              --backoff)
+                backoff="$2"
+                shift 2
+                ;;
+              --max-backoff)
+                max_backoff="$2"
+                shift 2
+                ;;
+              --)
+                shift
+                break
+                ;;
+              *)
+                echo "ERROR: Unknown retry option '$1'"
+                return 2
+                ;;
+            esac
+          done
+
+          if [ "$#" -eq 0 ]; then
+            echo "ERROR: retry requires a command after '--'"
+            return 2
+          fi
+
+          local attempt=1
+          local current_backoff="$backoff"
+          while [ "$attempt" -le "$retries" ]; do
+            if "$@"; then
+              return 0
+            fi
+            rc=$?
+            if [ "$attempt" -lt "$retries" ]; then
+              local wait="$current_backoff"
+              if [ "$wait" -gt "$max_backoff" ]; then
+                wait="$max_backoff"
+              fi
+              echo "Retry $attempt/$retries failed (exit $rc), waiting ${wait}s..."
+              sleep "$wait"
+              current_backoff=$((current_backoff * 2))
+            fi
+            attempt=$((attempt + 1))
+          done
+
+          echo "ERROR: Command failed after $retries attempts: $*"
+          return "$rc"
+        }
+        export -f retry
+        EOF
+
+        if [ -n "$PREV_BASH_ENV" ] && [ -f "$PREV_BASH_ENV" ] && [ "$PREV_BASH_ENV" != "$RETRY_HELPER" ]; then
+          {
+            echo "source \"$PREV_BASH_ENV\""
+            cat "$RETRY_HELPER"
+          } > "${RETRY_HELPER}.merged"
+          mv "${RETRY_HELPER}.merged" "$RETRY_HELPER"
+        fi
+
+        echo "BASH_ENV=$RETRY_HELPER" >> "$GITHUB_ENV"
+
     # ── Python dependencies ───────────────────────────────────────────────
     - name: Sync Python dependencies
       if: inputs.sync-dependencies == 'true'
       shell: bash
-      run: uv sync --frozen --all-extras
+      run: |
+        set -euo pipefail
+
+        if uv sync --frozen --all-extras; then
+          :
+        else
+          rc=$?
+          echo "WARNING: uv sync failed (exit $rc), clearing cache and .venv before retry..."
+          uv cache clean
+          rm -rf .venv
+          echo "Retrying uv sync..."
+          uv sync --frozen --all-extras
+        fi
 
     # ── Podman ──────────────────────────────────────────────────────────
     - name: Install podman
@@ -162,8 +293,10 @@ runs:
         BIN_FILE="hadolint-${ARCH}"
         SHA_FILE="${BIN_FILE}.sha256"
 
-        curl -fsSL "${BASE_URL}/${BIN_FILE}" -o "${BIN_FILE}"
-        curl -fsSL "${BASE_URL}/${SHA_FILE}" -o "${SHA_FILE}"
+        retry --retries 3 --backoff 5 --max-backoff 60 -- \
+          curl -fsSL "${BASE_URL}/${BIN_FILE}" -o "${BIN_FILE}"
+        retry --retries 3 --backoff 5 --max-backoff 60 -- \
+          curl -fsSL "${BASE_URL}/${SHA_FILE}" -o "${SHA_FILE}"
 
         EXPECTED_SHA="$(awk '{print $1}' "${SHA_FILE}")"
         echo "${EXPECTED_SHA}  ${BIN_FILE}" | sha256sum -c -
@@ -189,11 +322,17 @@ runs:
             ;;
         esac
 
-        TAPLO_VERSION="$(curl -fsSL https://api.github.com/repos/tamasfe/taplo/releases/latest | sed -n 's/.*"tag_name": *"\([^"]*\)".*/\1/p')"
+        TAPLO_VERSION="$(retry --retries 3 --backoff 5 --max-backoff 60 -- \
+          curl -fsSL https://api.github.com/repos/tamasfe/taplo/releases/latest | sed -n 's/.*"tag_name": *"\([^"]*\)".*/\1/p')"
+        if [ -z "${TAPLO_VERSION:-}" ]; then
+          echo "ERROR: Failed to resolve Taplo version from GitHub releases API"
+          exit 1
+        fi
         BASE_URL="https://github.com/tamasfe/taplo/releases/download/${TAPLO_VERSION}"
         BIN_FILE="taplo-linux-${ARCH}.gz"
 
-        curl -fsSL "${BASE_URL}/${BIN_FILE}" -o "${BIN_FILE}"
+        retry --retries 3 --backoff 5 --max-backoff 60 -- \
+          curl -fsSL "${BASE_URL}/${BIN_FILE}" -o "${BIN_FILE}"
         gunzip "${BIN_FILE}"
         sudo install -m 0755 "taplo-linux-${ARCH}" /usr/local/bin/taplo
         rm -f "taplo-linux-${ARCH}"

.github/actions/test-image/action.yml

@@ -125,21 +125,8 @@ runs:
         echo "Pulling image: $IMAGE_TAG"
 
         # Retry logic for podman pull (network flakiness)
-        RETRIES=3
-        for i in $(seq 1 $RETRIES); do
-          if podman pull "$IMAGE_TAG"; then
-            echo "Image pulled successfully"
-            break
-          else
-            if [ $i -lt $RETRIES ]; then
-              echo "Pull failed, retrying ($i/$RETRIES)..."
-              sleep 3
-            else
-              echo "Pull failed after $RETRIES attempts"
-              exit 1
-            fi
-          fi
-        done
+        uv run retry --retries 3 --backoff 3 --max-backoff 3 -- podman pull "$IMAGE_TAG"
+        echo "Image pulled successfully"
 
     - name: Verify image is available
       if: inputs.image-source == 'local'

.github/actions/test-project/action.yml

@@ -97,6 +97,7 @@ runs:
       run: |
         uv run pytest \
           tests/test_utils.py \
+          tests/test_devc_remote_uri.py \
           packages/vig-utils/tests \
           --cov --cov-report=term-missing --cov-report=xml \
           $TEST_ARGS

.github/agent-blocklist.toml

@@ -1,5 +1,5 @@
 # Canonical blocklist for AI agent identity fingerprints.
-# Referenced by: validate-commit-msg, pre-commit hooks, pr-title-check CI.
+# Referenced by: validate-commit-msg, pre-commit hooks.
 # Refs: #163
 
 [patterns]

.github/pr-draft-236-into-70.md

@@ -0,0 +1,63 @@
+## Description
+
+Add `gh:org/repo[:branch]` target syntax to `devc-remote.sh`, enabling one-command clone-and-start of a project's devcontainer on a remote host. Existing `host:path` syntax continues to work unchanged.
+
+## Type of Change
+
+- [x] `feat` -- New feature
+- [ ] `fix` -- Bug fix
+- [ ] `docs` -- Documentation only
+- [ ] `chore` -- Maintenance task (deps, config, etc.)
+- [ ] `refactor` -- Code restructuring (no behavior change)
+- [ ] `test` -- Adding or updating tests
+- [ ] `ci` -- CI/CD pipeline changes
+- [ ] `build` -- Build system or dependency changes
+- [ ] `revert` -- Reverts a previous commit
+- [ ] `style` -- Code style (formatting, whitespace)
+
+### Modifiers
+
+- [ ] Breaking change (`!`) -- This change breaks backward compatibility
+
+## Changes Made
+
+- `scripts/devc-remote.sh` — Extended `parse_args` to recognize `gh:org/repo[:branch]` as second positional arg; new `remote_clone_project` function (single SSH call: clone or fetch, optional branch checkout, config-based path resolution); wired into `main()` between `check_ssh` and `remote_preflight`; updated help text with new syntax and examples
+- `assets/workspace/scripts/devc-remote.sh` — Synced copy via manifest
+- `tests/bats/devc-remote.bats` — 7 new tests: 4 for arg parsing (gh:org/repo, gh:org/repo:branch, host:path+gh:, invalid gh:), 3 for clone function (fresh clone, fetch existing, branch checkout)
+- `CHANGELOG.md` — Added entry under Unreleased
+
+## Changelog Entry
+
+### Added
+- **`gh:org/repo[:branch]` target for devc-remote** ([#236](https://github.com/vig-os/devcontainer/issues/236))
+  - Clone a GitHub repo on the remote host and start its devcontainer in one command
+  - Supports `gh:org/repo` (default branch) and `gh:org/repo:branch` (specific branch)
+  - Already-cloned repos are fetched, not re-cloned
+  - Clone location resolved from remote config `projects_dir` or overridden via `host:path`
+
+## Testing
+
+- [x] Tests pass locally (`just test`)
+- [ ] Manual testing performed (describe below)
+
+### Manual Testing Details
+
+N/A
+
+## Checklist
+
+- [x] My code follows the project's style guidelines
+- [x] I have performed a self-review of my code
+- [ ] I have commented my code, particularly in hard-to-understand areas
+- [ ] I have updated the documentation accordingly (edit `docs/templates/`, then run `just docs`)
+- [x] I have updated `CHANGELOG.md` in the `[Unreleased]` section (and pasted the entry above)
+- [x] My changes generate no new warnings or errors
+- [x] I have added tests that prove my fix is effective or that my feature works
+- [x] New and existing unit tests pass locally with my changes
+- [ ] Any dependent changes have been merged and published
+
+## Additional Notes
+
+Design: https://github.com/vig-os/devcontainer/issues/236#issuecomment-4019537584
+
+Refs: #236

.github/workflows/ci.yml

@@ -193,7 +193,9 @@ jobs:
           sync-dependencies: 'true'
 
       - name: Install safety
-        run: uv pip install safety==3.7.0
+        run: |
+          set -euo pipefail
+          uv run retry --retries 3 --backoff 5 --max-backoff 30 -- uv pip install safety==3.7.0
 
       - name: Run Bandit (Python security linting)
         id: bandit
@@ -311,7 +313,7 @@ jobs:
 
       - name: Upload SARIF to GitHub Security
         if: always()
-        uses: github/codeql-action/upload-sarif@0d579ffd059c29b07949a3cce3983f0780820c98  # v4
+        uses: github/codeql-action/upload-sarif@38697555549f1db7851b81482ff19f1fa5c4fedc  # v4
         with:
           sarif_file: trivy-results.sarif
           category: 'container-image'

.github/workflows/codeql.yml

@@ -48,11 +48,11 @@ jobs:
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@0d579ffd059c29b07949a3cce3983f0780820c98  # v4
+        uses: github/codeql-action/init@38697555549f1db7851b81482ff19f1fa5c4fedc  # v4
         with:
           languages: ${{ matrix.language }}
 
       - name: Run CodeQL analysis
-        uses: github/codeql-action/analyze@0d579ffd059c29b07949a3cce3983f0780820c98  # v4
+        uses: github/codeql-action/analyze@38697555549f1db7851b81482ff19f1fa5c4fedc  # v4
         with:
           category: '/language:${{ matrix.language }}'