v0.9.3 - sandboxing

.gitattributes

@@ -0,0 +1,17 @@
+# Force LF line endings on every text file in every working tree.
+#
+# Why global: the WSL CI job runs against a checkout on the windows-latest
+# runner (default core.autocrlf=true). Any text file without an explicit
+# attribute is normalised to CRLF on checkout, which has surfaced as a
+# series of unrelated CI failures:
+#   * bash scripts:    `$'\r': command not found` / `set: pipefail: invalid option name`
+#   * .jh source:      `jaiph format --check` reports "needs formatting"
+#                      because format normalises to LF
+# Per-extension whack-a-mole would keep finding new variants. `text=auto`
+# tells git to detect text vs binary per file; combined with `eol=lf` it
+# stores LF in the index and writes LF to working trees on every platform.
+* text=auto eol=lf
+
+# Belt-and-suspenders: explicitly mark binary assets so `text=auto` cannot
+# misclassify them and corrupt the bytes by line-ending normalisation.
+*.png binary

.github/workflows/ci.yml

@@ -4,6 +4,19 @@ on:
   push:
 
 jobs:
+  shellcheck:
+    name: ShellCheck
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install shellcheck
+        run: sudo apt-get update && sudo apt-get install -y shellcheck
+
+      - name: Run shellcheck
+        run: shellcheck runtime/overlay-run.sh
+
   test:
     name: Compiler and unit tests
     runs-on: ubuntu-latest
@@ -33,12 +46,26 @@ jobs:
           git ls-remote --exit-code https://github.com/jaiphlang/jaiph.git "refs/tags/v${VERSION}"
 
   e2e:
-    name: E2E install and CLI workflow (${{ matrix.os }})
+    name: E2E (${{ matrix.os }}, ${{ matrix.label }})
     runs-on: ${{ matrix.os }}
+    env:
+      # Host/safe split applies on Ubuntu only. macOS runners do not ship Docker the same way — keep host-only there.
+      # "docker": unset JAIPH_UNSAFE so resolveDockerConfig enables the sandbox (pulls ghcr.io/jaiphlang/jaiph-runtime).
+      # "host": explicit opt-out, same as a fast local `JAIPH_UNSAFE=true npm run test:e2e`.
+      JAIPH_UNSAFE: ${{ matrix.jaiph_unsafe }}
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, macos-latest]
+        include:
+          - os: ubuntu-latest
+            label: docker
+            jaiph_unsafe: ""
+          - os: ubuntu-latest
+            label: host
+            jaiph_unsafe: "true"
+          - os: macos-latest
+            label: host
+            jaiph_unsafe: "true"
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -48,6 +75,12 @@ jobs:
         with:
           node-version: "20"
 
+      - name: Build runtime image for Docker E2E
+        if: matrix.label == 'docker'
+        run: |
+          docker build -t jaiph-ci-runtime:local -f runtime/Dockerfile .
+          echo "JAIPH_DOCKER_IMAGE=jaiph-ci-runtime:local" >> "$GITHUB_ENV"
+
       - name: Run runtime acceptance E2E
         run: |
           npm ci
@@ -77,6 +110,11 @@ jobs:
           node-version: "20"
           cache: npm
 
+      - name: Build runtime image for docs sample Docker runs
+        run: |
+          docker build -t jaiph-ci-runtime:local -f runtime/Dockerfile .
+          echo "JAIPH_DOCKER_IMAGE=jaiph-ci-runtime:local" >> "$GITHUB_ENV"
+
       - name: Install dependencies
         run: npm ci
 
@@ -151,38 +189,133 @@ jobs:
         id: detect_wsl
         shell: pwsh
         run: |
+          $ciDistro = "jaiph-ci-ubuntu"
           $distros = @(wsl -l -q | ForEach-Object { $_.Trim() } | Where-Object { $_ -ne "" })
           if ($distros.Count -eq 0) {
-            "distro=" >> $env:GITHUB_OUTPUT
-            Write-Warning "No WSL distro is available on this runner. Skipping WSL E2E."
-            exit 0
+            Write-Warning "No WSL distro is available on this runner. Importing Ubuntu rootfs for CI."
+            $archivePath = Join-Path $env:RUNNER_TEMP "ubuntu-base-amd64.tar.gz"
+            $installPath = Join-Path $env:RUNNER_TEMP "wsl-ubuntu"
+            $ubuntuBaseReleaseIndexUrl = "https://cdimage.ubuntu.com/ubuntu-base/releases/24.04/release/"
+
+            if (Test-Path $installPath) {
+              Remove-Item -Path $installPath -Recurse -Force
+            }
+            New-Item -ItemType Directory -Path $installPath -Force | Out-Null
+            $releaseIndex = Invoke-WebRequest -Uri $ubuntuBaseReleaseIndexUrl
+            $matches = [regex]::Matches($releaseIndex.Content, 'ubuntu-base-24\.04\.(\d+)-base-amd64\.tar\.gz')
+            $candidates = @($matches | ForEach-Object { $_.Value } | Sort-Object -Unique)
+            if ($candidates.Count -eq 0) {
+              Write-Error "Unable to resolve an Ubuntu Base 24.04 amd64 archive from $ubuntuBaseReleaseIndexUrl"
+              exit 1
+            }
+            $archiveName = $candidates |
+              Sort-Object {
+                [int]([regex]::Match($_, '24\.04\.(\d+)-').Groups[1].Value)
+              } -Descending |
+              Select-Object -First 1
+            $ubuntuBaseUrl = "$ubuntuBaseReleaseIndexUrl$archiveName"
+            Write-Host "Downloading Ubuntu base archive: $ubuntuBaseUrl"
+            try {
+              Invoke-WebRequest -Uri $ubuntuBaseUrl -OutFile $archivePath -MaximumRetryCount 3 -RetryIntervalSec 2
+            } catch {
+              Write-Error "Failed to download $ubuntuBaseUrl : $($_.Exception.Message)"
+              exit 1
+            }
+            wsl --import "$ciDistro" "$installPath" "$archivePath" --version 2
+            $distros = @("$ciDistro")
           }
           $ubuntu = $distros | Where-Object { $_ -match "^Ubuntu" } | Select-Object -First 1
           $selected = if ($ubuntu) { $ubuntu } else { $distros[0] }
+          if (-not $selected) {
+            Write-Error "Failed to provision a WSL distro for CI."
+            exit 1
+          }
           "distro=$selected" >> $env:GITHUB_OUTPUT
           Write-Host "Using WSL distro: $selected"
 
       - name: Install Node and run E2E tests in WSL
-        if: steps.detect_wsl.outputs.distro != ''
         shell: pwsh
         run: |
           $workspace = "${{ github.workspace }}"
           $distro = "${{ steps.detect_wsl.outputs.distro }}"
-          wsl -d "$distro" -- bash -lc "set -euo pipefail
+          $env:JAIPH_WORKSPACE = $workspace
+          $bashScript = @'
+          set -euo pipefail
           export DEBIAN_FRONTEND=noninteractive
-          sudo apt-get update
-          sudo apt-get install -y curl ca-certificates
+          export JAIPH_UNSAFE=true
+          SUDO=
+          if [ "$(id -u)" -ne 0 ]; then
+            SUDO=sudo
+          fi
+          $SUDO apt-get update
+          # git: required by feature-coverage tests (124_install_command,
+          # 129_artifacts_lib, the git-aware section of 10_basic_workflows).
+          # docs/install only needs git when not installing from a local source,
+          # so installing it here does not change the "no-git host" code path
+          # those tests already cover via JAIPH_FROM_LOCAL.
+          $SUDO apt-get install -y curl ca-certificates git
           if ! command -v node >/dev/null 2>&1; then
-            curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
-            sudo apt-get install -y nodejs
+            if [ -n "$SUDO" ]; then
+              curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
+            else
+              curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
+            fi
+            $SUDO apt-get install -y nodejs
           fi
-          cd \"\$(wslpath '$workspace')\"
+          cd "$(wslpath "$JAIPH_WORKSPACE")"
           npm ci
           npm run test:e2e
-          "
+          '@
+          # PowerShell on Windows can keep CRLF in here-strings; strip CR so bash does not see "pipefail\r".
+          $bashScript = $bashScript -replace "`r", ""
+          wsl -d "$distro" -- bash -lc "$bashScript"
 
-      - name: WSL E2E skipped
-        if: steps.detect_wsl.outputs.distro == ''
-        shell: pwsh
+  docker-publish:
+    name: Publish Docker runtime image
+    needs: [test, e2e, docs-local, e2e-wsl]
+    if: github.ref == 'refs/heads/nightly' || startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    env:
+      REGISTRY: ghcr.io
+      IMAGE_NAME: jaiphlang/jaiph-runtime
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Image tags
+        id: meta
+        run: |
+          if [[ "${GITHUB_REF}" == refs/tags/v* ]]; then
+            VERSION="${GITHUB_REF_NAME#v}"
+            echo "tags=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${VERSION},${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest" >> "$GITHUB_OUTPUT"
+          else
+            echo "tags=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:nightly" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: runtime/Dockerfile
+          push: true
+          platforms: linux/amd64,linux/arm64
+          tags: ${{ steps.meta.outputs.tags }}
+
+      - name: Verify pushed image contains jaiph
         run: |
-          Write-Host "No WSL distro found on this runner image; skipping WSL E2E."
+          TAG="$(echo '${{ steps.meta.outputs.tags }}' | cut -d',' -f1)"
+          docker run --rm --entrypoint sh "${TAG}" -lc "command -v jaiph && jaiph --version"
+          docker run --rm --user 0:0 --cap-drop ALL --cap-add SYS_ADMIN --entrypoint sh "${TAG}" -lc "command -v jaiph"

.gitignore

@@ -48,4 +48,12 @@ e2e/ensure_fail.sh
 e2e/current_branch.sh
 e2e/assign_capture.sh
 
-.obsidian/
+.obsidian/
+
+# debug / temp directories (never commit)
+docker-*/
+nested-*/
+overlay-*/
+local-*/
+.tmp*/
+QUEUE.md.tmp.*