ci: Clean documentation, and refactor workflow.

Author: dylan-sutton-chavez

.github/README.md

@@ -1,27 +1,8 @@
 # Edge Python CI/CD
 
-One workflow, [`main.yml`](main.yml), drives the whole monorepo, so the Actions tab
-shows a single "CI / CD" run per push/PR with every job as a node in one graph. Each
-package's logic lives in a **composite action** under [`../actions/`](../actions);
-`main.yml` only wires the dependency graph. The composite actions are not workflows
-and do not appear in the Actions tab.
+One workflow, [`main.yml`](main.yml), drives the whole monorepo, so the Actions tab shows a single "CI / CD" run per push/PR with every job as a node in one graph. Each package's logic lives in a **composite action** under [`../actions/`](../actions); `main.yml` only wires the dependency graph. The composite actions are not workflows and do not appear in the Actions tab.
 
-```
-compiler-check ┐
-runtime-lint  ─┴─► compiler ─► runtime ─┬─► host (matrix) ─┐
-                                        └─► std  (matrix) ─┤
-cli-release (matrix, starts at t=0) ───────────────────────┴─► cli-test
-                                                                  │ (push to main)
-                                cdn ◄── demo ◄── docs ◄───────────┘
-            (docs builds on every run; deploys only on push to main)
-```
-
-`compiler-check`, `runtime-lint` and `cli-release` start at t=0. If any job fails the
-dependents never run (`needs:`), so a red build stops the deploys, including the docs
-deploy. The
-`host` and `std` matrices use `fail-fast: false` so one capability / package failure
-still reports the others. `cli-release` is the slow heavy build, so it starts
-immediately and `cli-test` waits on `host`, `std`, and the release artifacts.
+`compiler-check`, `runtime-lint` and `cli-release` start at t=0. If any job fails the dependents never run (`needs:`), so a red build stops the deploys, including the docs deploy. The `host` and `std` matrices use `fail-fast: false` so one capability / package failure still reports the others. `cli-release` is the slow heavy build, so it starts immediately and `cli-test` waits on `host`, `std`, and the release artifacts.
 
 ## Composite actions
 
@@ -38,24 +19,22 @@ immediately and `cli-test` waits on `host`, `std`, and the release artifacts.
 
 ## Cloudflare Pages
 
-Three **Direct Upload** projects. Actions push prebuilt directories via
-`wrangler pages deploy`; Cloudflare doesn't clone or build.
+Three **Direct Upload** projects. Actions push prebuilt directories via `wrangler pages deploy`; Cloudflare doesn't clone or build.
 
 | Project | Source | Production URL |
 |---------|--------|----------------|
 | `edge-python-cdn` | `_site/{compiler,runtime,std,host,cli}` (consolidates the old per-package `-runtime` / `-host` / `-std` projects) | `https://edge-python-cdn.pages.dev` |
 | `edge-python-demo` | `demo/` (wasm hashed for `version.json`, not bundled) | `https://edge-python-demo.pages.dev` |
 | `edge-python-docs` | `docs/out` (Nextra static export) | `https://edgepython.com` (custom domain; also `https://edge-python-docs.pages.dev`) |
 
-All deploys run **only on pushes to `main`** and are pinned to the production `main`
-branch. PRs and tags never deploy; the next `main` push refreshes the projects.
+All deploys run **only on pushes to `main`** and are pinned to the production `main` branch. PRs and tags never deploy; the next `main` push refreshes the projects.
 
 ### Cloudflare and GitHub setup
 
 ```bash
 # Wrangler CLI (Node 22+)
 npx wrangler login
-npx wrangler pages project create edge-python-cdn  --production-branch=main
+npx wrangler pages project create edge-python-cdn --production-branch=main
 npx wrangler pages project create edge-python-demo --production-branch=main
 npx wrangler pages project create edge-python-docs --production-branch=main
 ```
@@ -73,8 +52,7 @@ Rotate: create new token -> update secret -> revoke old token.
 
 ## Releases
 
-Pushing a `v*` tag runs the pipeline; the `compiler` build job uploads
-`compiler_lib.wasm` to the matching Release. Tag must match workspace version.
+Pushing a `v*` tag runs the pipeline; the `compiler` build job uploads `compiler_lib.wasm` to the matching Release. Tag must match workspace version.
 
 1. Bump `version` under `[workspace.package]` in root `Cargo.toml` (every crate inherits via `version.workspace = true`). Run `cargo check` to refresh `Cargo.lock`, commit.
 2. Tag and push:
@@ -84,18 +62,10 @@ git tag v0.1.0
 git push origin v0.1.0
 ```
 
-On tag push: `compiler-check` lints, then the `compiler` build job optimizes the
-artifact and attaches it to a fresh Release with auto-generated notes. The CDN, demo
-and docs deploys do not run on tags; they already deployed from the preceding `main` push.
+On tag push: `compiler-check` lints, then the `compiler` build job optimizes the artifact and attaches it to a fresh Release with auto-generated notes. The CDN, demo and docs deploys do not run on tags; they already deployed from the preceding `main` push.
 
-Nothing is published to crates.io, distribution is the `.wasm` on the Release.
-`starter-module` carries its own version and isn't bumped with the workspace.
+Nothing is published to crates.io, distribution is the `.wasm` on the Release. `starter-module` carries its own version and isn't bumped with the workspace.
 
-Consumer crates pick up the release automatically: `compiler/Cargo.toml` declares
-`links = "compiler_lib"` and `compiler/build.rs` downloads
-`<repository>/releases/download/v<version>/compiler_lib.wasm` into `OUT_DIR`.
-Downstreams read `DEP_COMPILER_LIB_WASM` in their own `build.rs`, see
-[root README](../../README.md#consume-the-release-from-a-rust-host). Tag bumps flow via `cargo update`.
+Consumer crates pick up the release automatically: `compiler/Cargo.toml` declares `links = "compiler_lib"` and `compiler/build.rs` downloads `<repository>/releases/download/v<version>/compiler_lib.wasm` into `OUT_DIR`. Downstreams read `DEP_COMPILER_LIB_WASM` in their own `build.rs`, see [root README](../../README.md#consume-the-release-from-a-rust-host). Tag bumps flow via `cargo update`.
 
-Gated behind the default-on `prebuilt` feature. Producer-side compiler steps pass
-`--no-default-features` to avoid fetching the asset that this same pipeline uploads later.
+Gated behind the default-on `prebuilt` feature. Producer-side compiler steps pass `--no-default-features` to avoid fetching the asset that this same pipeline uploads later.

.github/actions/cli/action.yml

@@ -1,9 +1,9 @@
 name: CLI
-description: cli/ is its own workspace. release = lint/check + build per target; test = cargo test.
+description: cli/ is its own workspace. lint = clippy + check; release = build per target; test = cargo test.
 
 inputs:
   mode:
-    description: "release | test"
+    description: "lint | release | test"
     required: true
   target:
     description: Rust target triple (release mode).
@@ -13,12 +13,31 @@ inputs:
 runs:
   using: composite
   steps:
+    - name: Toolchain (lint)
+      if: inputs.mode == 'lint'
+      uses: dtolnay/rust-toolchain@stable
+      with:
+        components: clippy
+
+    - name: Cache Rust (lint)
+      if: inputs.mode == 'lint'
+      uses: Swatinem/rust-cache@v2
+      with:
+        workspaces: cli -> cli/target
+
+    - name: Clippy and check
+      if: inputs.mode == 'lint'
+      shell: bash
+      working-directory: cli
+      run: |
+        cargo clippy --all-targets -- -D warnings
+        cargo check
+
     - name: Toolchain (release)
       if: inputs.mode == 'release'
       uses: dtolnay/rust-toolchain@stable
       with:
         targets: ${{ inputs.target }}
-        components: clippy
 
     - name: Install musl tools
       if: inputs.mode == 'release' && contains(inputs.target, 'linux-musl')
@@ -32,15 +51,6 @@ runs:
         workspaces: cli -> cli/target
         key: ${{ inputs.target }}
 
-    # Lint + check once, anchored to the linux x86 target so the matrix doesn't repeat it.
-    - name: Clippy and check
-      if: inputs.mode == 'release' && inputs.target == 'x86_64-unknown-linux-musl'
-      shell: bash
-      working-directory: cli
-      run: |
-        cargo clippy --release --target "${{ inputs.target }}" -- -D warnings
-        cargo check --release --target "${{ inputs.target }}"
-
     - name: Build release
       if: inputs.mode == 'release'
       shell: bash

.github/actions/docs/action.yml

@@ -1,11 +1,10 @@
-name: Docs build & deploy
-description: Build the Nextra static export (docs/out); deploy to edge-python-docs when deploy=true.
+name: Docs
+description: Nextra static export. build = next build + upload docs/out; deploy = pull artifact + push to edge-python-docs.
 
 inputs:
-  deploy:
-    description: true to deploy after a successful build.
-    required: false
-    default: "false"
+  mode:
+    description: "build | deploy"
+    required: true
   cloudflare-api-token:
     description: Cloudflare API token (deploy only).
     required: false
@@ -18,25 +17,44 @@ inputs:
 runs:
   using: composite
   steps:
-    - uses: actions/setup-node@v6
+    - name: Setup Node
+      if: inputs.mode == 'build'
+      uses: actions/setup-node@v6
       with:
         node-version: "22"
         cache: npm
         cache-dependency-path: docs/package-lock.json
 
     # Reproducible install from the committed lockfile.
     - name: Install
+      if: inputs.mode == 'build'
       shell: bash
       working-directory: docs
       run: npm ci
 
     - name: Build
+      if: inputs.mode == 'build'
       shell: bash
       working-directory: docs
       run: npm run build
 
+    - name: Upload static export
+      if: inputs.mode == 'build'
+      uses: actions/upload-artifact@v6
+      with:
+        name: docs-out
+        path: docs/out
+        retention-days: 1
+
+    - name: Download static export
+      if: inputs.mode == 'deploy'
+      uses: actions/download-artifact@v8
+      with:
+        name: docs-out
+        path: docs/out
+
     - name: Deploy to Cloudflare Pages
-      if: inputs.deploy == 'true'
+      if: inputs.mode == 'deploy'
       uses: cloudflare/wrangler-action@v4
       with:
         apiToken: ${{ inputs.cloudflare-api-token }}

.github/workflows/main.yml

@@ -1,15 +1,6 @@
 name: CI / CD
 
-# Single pipeline for the whole monorepo. Each job's logic lives in a composite
-# action under .github/actions/<pkg>; this file only wires the dependency graph.
-#
-#   compiler-check ┐
-#   runtime-lint  ─┴─► compiler ─► runtime ─┬─► host (matrix) ─┐
-#                                           └─► std  (matrix) ─┤
-#   cli-release (matrix, starts at t=0) ─────────────────────┴─► cli-test
-#                                                                   │ (push to main)
-#                                    cdn ◄── demo ◄── docs ◄────────┘
-#   docs deploys only on push to main, gated behind the full pipeline.
+# Single pipeline for the whole monorepo. Each job's logic lives in a composite action under .github/actions/<pkg>; this file only wires the dependency graph.
 
 on:
   push:
@@ -95,9 +86,20 @@ jobs:
         with:
           package: ${{ matrix.package }}
 
-  # Starts at t=0 (no needs): the heavy release build runs in parallel; cli-test awaits its artifacts.
+  # Clippy + check once (no matrix); gates the release build.
+  cli-lint:
+    name: CLI / Lint and Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: ./.github/actions/cli
+        with:
+          mode: lint
+
+  # Heavy release build per target; starts as soon as cli-lint is green.
   cli-release:
     name: CLI / Release (${{ matrix.target }})
+    needs: [cli-lint]
     strategy:
       fail-fast: false
       matrix:
@@ -142,7 +144,7 @@ jobs:
 
   demo:
     name: Demo
-    needs: [cli-test]
+    needs: [cdn]
     if: github.event_name == 'push' && github.ref == 'refs/heads/main'
     runs-on: ubuntu-latest
     steps:
@@ -152,14 +154,27 @@ jobs:
           cloudflare-api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
           cloudflare-account-id: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
 
-  docs:
+  # Builds on every run (PR gate) and uploads the static export for docs-deploy.
+  docs-build:
     name: Docs / Build
     needs: [cli-test]
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
       - uses: ./.github/actions/docs
         with:
-          deploy: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+          mode: build
+
+  # Tail of the cdn -> demo -> docs deploy chain; main pushes only.
+  docs-deploy:
+    name: Docs / Deploy
+    needs: [demo, docs-build]
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: ./.github/actions/docs
+        with:
+          mode: deploy
           cloudflare-api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
           cloudflare-account-id: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

cli/src/uninstall.rs

@@ -27,11 +27,10 @@ pub fn run() -> Result<()> {
     // Tell the script which prompt path the user already answered.
     cmd.env("EDGE_UNINSTALL_REMOVE_BROWSER", if remove_browser { "1" } else { "0" });
     // Point at the install dir derived from where this binary lives, so non-default installs still clean up.
-    if let Ok(exe) = std::env::current_exe() {
-        if let Some(dir) = exe.parent() {
+    if let Ok(exe) = std::env::current_exe()
+        && let Some(dir) = exe.parent() {
             cmd.env("EDGE_INSTALL_DIR", dir);
         }
-    }
 
     let status = cmd.status().map_err(|e| anyhow!("running bash: {e}"))?;
     let _ = std::fs::remove_file(&temp);