Merge upstream/main into feat/issue-4692-zcode

Author: jzhishu

.github/AGENTS.md

@@ -12,8 +12,9 @@ Before changing GitHub automation, read the current versions of:
 - `.github/workflows/report.atom.yml`
 - `.github/scripts/handoff.py`
 - `scripts/scopes.ts`
+- `specs/current/ci.md` when changing scope rules, confidence tiers, or guards
 - `e2e/tests/packaged-smoke-workflow.test.ts`
-- `scripts/approve-fork-pr-workflows.ts` and `scripts/approve-fork-pr-workflows.test.ts` when touching fork PR approval behavior
+- `scripts/approve-fork-pr-workflows.ts` and `e2e/tests/scripts/approve-fork-pr-workflows.test.ts` when touching fork PR approval behavior
 
 If the change affects cross-workflow behavior, update the topology tests instead of relying only on workflow YAML review.
 
@@ -163,4 +164,4 @@ GitHub artifact behavior is easy to drift: artifact names must be unique per upl
 
 ### Where should tests live?
 
-Cross-workflow topology tests belong in `e2e/tests/` when they observe repository-level behavior. Script-specific behavior can stay next to the script's existing tests. Do not add one-off `*.test.ts` files just because a workflow helper exists; prefer existing topology coverage and helper self-checks when that is enough.
+Cross-workflow topology tests belong in `e2e/tests/` when they observe repository-level behavior. Root `scripts/` is test-free (enforced by `pnpm guard`); script behavior-contract coverage lives in `e2e/tests/scripts/`. Do not add one-off `*.test.ts` files just because a workflow helper exists; prefer existing topology coverage and helper self-checks when that is enough.

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

@@ -14,6 +14,10 @@ inputs:
     description: JSON array of labels selected for this job's runs-on value
     required: false
     default: '[]'
+  save-pnpm-cache:
+    description: Save a missing pnpm cache after install; trusted main seed jobs only
+    required: false
+    default: 'false'
 
 runs:
   using: composite
@@ -62,13 +66,21 @@ runs:
       shell: bash
       run: echo "path=$(pnpm store path --silent)" >> "$GITHUB_OUTPUT"
 
-    - name: Cache pnpm store
+    - name: Restore pnpm store
+      id: pnpm-cache-restore
       if: ${{ steps.persistent-pnpm-store.outputs.enabled != 'true' }}
-      uses: actions/cache@v5.0.5
+      uses: actions/cache/restore@v5
       with:
         path: ${{ steps.pnpm-store.outputs.path }}
         key: pnpm-store-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
 
     - name: Install dependencies
       shell: bash
       run: pnpm install --frozen-lockfile
+
+    - name: Save pnpm store
+      if: ${{ inputs.save-pnpm-cache == 'true' && steps.persistent-pnpm-store.outputs.enabled != 'true' && steps.pnpm-cache-restore.outputs.cache-hit != 'true' && github.ref == 'refs/heads/main' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch' || github.event_name == 'schedule') }}
+      uses: actions/cache/save@v5
+      with:
+        path: ${{ steps.pnpm-store.outputs.path }}
+        key: pnpm-store-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}

.github/pull_request_template.md

@@ -31,7 +31,7 @@ Fixes #
 
 - [ ] **UI** — new page / dialog / panel / menu item / setting / empty state in `apps/web` or `apps/desktop` (including Electron menu bar)
 - [ ] **Keyboard shortcut** — new or changed
-- [ ] **CLI / env var** — new `od` subcommand or flag, new `tools-dev` / `tools-pack` / `tools-pr` flag, or new `OD_*` env var
+- [ ] **CLI / env var** — new `od` subcommand or flag, new `tools-dev` / `tools-pack` flag, or new `OD_*` env var
 - [ ] **API / contract** — new `/api/*` endpoint, new SSE event, or changed shape in `packages/contracts`
 - [ ] **Extension point** — new entry under `skills/`, `design-systems/`, `design-templates/`, or `craft/`, or change to the skills protocol
 - [ ] **i18n keys** — added new translation keys (see `TRANSLATIONS.md` for the locale workflow)

.github/workflows/cache-maintenance.yml

@@ -0,0 +1,68 @@
+name: cache-maintenance
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - pnpm-lock.yaml
+      - .github/actions/setup-workspace/action.yml
+      - .github/workflows/cache-maintenance.yml
+  pull_request_target:
+    types: [closed]
+  workflow_dispatch:
+
+permissions:
+  actions: write
+  contents: read
+
+jobs:
+  seed-pnpm-windows:
+    if: github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/main')
+    runs-on: windows-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@v6.0.2
+
+      - name: Seed Windows pnpm cache
+        uses: ./.github/actions/setup-workspace
+        with:
+          save-pnpm-cache: 'true'
+
+  clean-closed-pr-buildkit:
+    if: github.event_name == 'pull_request_target' && github.repository == 'nexu-io/open-design'
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+    steps:
+      - name: Delete closed PR BuildKit caches
+        env:
+          CACHE_REF: refs/pull/${{ github.event.pull_request.number }}/merge
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+
+          cache_rows="$(
+            gh cache list \
+              --repo "$GITHUB_REPOSITORY" \
+              --ref "$CACHE_REF" \
+              --limit 10000 \
+              --json id,key,sizeInBytes \
+              --jq '.[] | select((.key | startswith("buildkit-blob-")) or (.key | startswith("index-buildkit-"))) | [.id, .key, .sizeInBytes] | @tsv'
+          )"
+
+          if [ -z "$cache_rows" ]; then
+            echo "No closed-PR BuildKit caches found for $CACHE_REF"
+            exit 0
+          fi
+
+          count=0
+          bytes=0
+          while IFS=$'\t' read -r cache_id cache_key cache_size; do
+            [ -n "$cache_id" ] || continue
+            echo "Deleting cache id=$cache_id key=$cache_key bytes=$cache_size ref=$CACHE_REF"
+            gh cache delete "$cache_id" --repo "$GITHUB_REPOSITORY"
+            count=$((count + 1))
+            bytes=$((bytes + cache_size))
+          done <<< "$cache_rows"
+
+          echo "Deleted $count closed-PR BuildKit caches ($bytes bytes) for $CACHE_REF"

.github/workflows/ci.yml

@@ -63,6 +63,7 @@ jobs:
       run_playwright_critical: ${{ steps.detect.outputs.run_playwright_critical }}
       run_playwright_visual: ${{ steps.detect.outputs.run_playwright_visual }}
       run_preflight: ${{ steps.detect.outputs.run_preflight }}
+      run_preflight_typecheck: ${{ steps.detect.outputs.run_preflight_typecheck }}
       run_ui_p0: ${{ steps.detect.outputs.run_ui_p0 }}
       run_web_workspace_tests: ${{ steps.detect.outputs.run_web_workspace_tests }}
       run_windows_tools_pack_payload_tests: ${{ steps.detect.outputs.run_windows_tools_pack_payload_tests }}
@@ -136,21 +137,31 @@ jobs:
     timeout-minutes: 10
     env:
       ACTIONLINT_VERSION: 1.7.12
+      SHELLCHECK_VERSION: 0.11.0
 
     steps:
       - name: Checkout
         uses: actions/checkout@v6.0.2
 
-      - name: Install actionlint
+      - name: Install actionlint and ShellCheck
         run: |
           case "$(uname -m)" in
-            x86_64) actionlint_arch=amd64 ;;
-            aarch64|arm64) actionlint_arch=arm64 ;;
+            x86_64)
+              actionlint_arch=amd64
+              shellcheck_arch=x86_64
+              ;;
+            aarch64|arm64)
+              actionlint_arch=arm64
+              shellcheck_arch=aarch64
+              ;;
             *) echo "Unsupported actionlint architecture: $(uname -m)" >&2; exit 1 ;;
           esac
           curl -fsSL "https://github.com/rhysd/actionlint/releases/download/v${ACTIONLINT_VERSION}/actionlint_${ACTIONLINT_VERSION}_linux_${actionlint_arch}.tar.gz" \
             | tar -xz actionlint
+          curl -fsSL "https://github.com/koalaman/shellcheck/releases/download/v${SHELLCHECK_VERSION}/shellcheck-v${SHELLCHECK_VERSION}.linux.${shellcheck_arch}.tar.gz" \
+            | tar -xz --strip-components=1 "shellcheck-v${SHELLCHECK_VERSION}/shellcheck"
           sudo install -m 0755 actionlint /usr/local/bin/actionlint
+          sudo install -m 0755 shellcheck /usr/local/bin/shellcheck
 
       - name: Check workflow files
         run: actionlint -color
@@ -245,12 +256,14 @@ jobs:
       # If postinstall grows a targeted app type-generation phase covering these
       # three exports without broad app builds, this CI prebuild can be removed.
       - name: Prebuild workspace type declarations
+        if: ${{ needs.scopes.outputs.run_preflight_typecheck == 'true' }}
         run: |
           pnpm --filter @open-design/daemon build
           pnpm --filter @open-design/desktop build
           pnpm --filter @open-design/web build:sidecar
 
       - name: Typecheck workspaces
+        if: ${{ needs.scopes.outputs.run_preflight_typecheck == 'true' }}
         run: |
           pnpm -r --filter '!open-design' --filter '!@open-design/landing-page' --workspace-concurrency="${OPEN_DESIGN_WORKSPACE_CONCURRENCY:-1}" --if-present run typecheck
           pnpm exec tsc -p scripts/tsconfig.json --noEmit
@@ -291,7 +304,13 @@ jobs:
             pnpm --filter @open-design/tools-dev test
           fi
           if [ "${{ needs.scopes.outputs.tools_pack_tests_required }}" = "true" ]; then
+            pnpm --filter @open-design/desktop build
+            pnpm --filter @open-design/desktop test
+            pnpm --filter @open-design/packaged test
             pnpm --filter @open-design/tools-pack test
+            if [ "${{ needs.scopes.outputs.run_e2e_vitest }}" != "true" ]; then
+              pnpm --filter @open-design/e2e test tests/packaged-launcher-update-loop.test.ts
+            fi
           fi
 
       - name: Probe watcher environment
@@ -723,8 +742,11 @@ jobs:
               marker="<!-- merge-queue-needs-validation -->"
               {
                 printf '%s\n' "$marker"
+                # Markdown code spans are intentional literal text.
+                # shellcheck disable=SC2016
                 printf 'Ejected from the merge queue: this PR still carries the `needs-validation` label.\n\n'
                 printf 'The merge queue gate ([run %s](%s/%s/actions/runs/%s)) blocked the queued group because of the label. That failure runs on the queue'"'"'s transient ref, so it never appears in this PR'"'"'s own checks — they stay green, and this notice is the only visible trace on the PR.\n\n' "$RUN_ID" "$GITHUB_SERVER_URL" "$REPO" "$RUN_ID"
+                # shellcheck disable=SC2016
                 printf 'To land this PR: complete the QA pass the label is tracking, remove the `needs-validation` label, then add the PR back to the merge queue.\n'
               } > "$handoff_dir/body.md"
               jq -n \

.github/workflows/cut-patch-release.yml

@@ -100,10 +100,12 @@ jobs:
           # (e.g. version=0.15.1 gates open-design-v0.15.0, not the latest 0.14.0).
           vmajor=${V%%.*}; vrest=${V#*.}; vminor=${vrest%%.*}
           MINOR_BASE="${vmajor}.${vminor}.0"
-          echo "version=$V"                          >> "$GITHUB_OUTPUT"
-          echo "branch=release/v$V"                  >> "$GITHUB_OUTPUT"
-          echo "minor_base=$MINOR_BASE"              >> "$GITHUB_OUTPUT"
-          echo "minor_tag=open-design-v$MINOR_BASE"  >> "$GITHUB_OUTPUT"
+          {
+            echo "version=$V"
+            echo "branch=release/v$V"
+            echo "minor_base=$MINOR_BASE"
+            echo "minor_tag=open-design-v$MINOR_BASE"
+          } >> "$GITHUB_OUTPUT"
           echo "Cutting patch v$V (branch release/v$V); gating on stable v$MINOR_BASE"
 
       # Guard: the minor this patch sits on (the Tuesday cut) must already be a

.github/workflows/landing-page-ci.yml

@@ -81,9 +81,9 @@ jobs:
       - name: Setup workspace
         uses: ./.github/actions/setup-workspace
 
-      - name: Cache generated previews
+      - name: Restore generated previews
         id: previews-cache
-        uses: actions/cache@v5.0.5
+        uses: actions/cache/restore@v5
         with:
           path: apps/landing-page/public/previews
           key: landing-page-previews-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml', 'package.json', 'apps/landing-page/package.json', 'apps/landing-page/scripts/generate-previews.ts', 'apps/landing-page/scripts/fallback-preview-card.ts', 'skills/**', 'design-templates/**', 'templates/live-artifacts/**', 'plugins/_official/**') }}
@@ -125,6 +125,13 @@ jobs:
           OD_LANDING_NOINDEX: '1'
         run: pnpm --filter @open-design/landing-page build:static
 
+      - name: Save generated previews
+        if: ${{ steps.previews-cache.outputs.cache-hit != 'true' && github.ref == 'refs/heads/main' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch') }}
+        uses: actions/cache/save@v5
+        with:
+          path: apps/landing-page/public/previews
+          key: landing-page-previews-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml', 'package.json', 'apps/landing-page/package.json', 'apps/landing-page/scripts/generate-previews.ts', 'apps/landing-page/scripts/fallback-preview-card.ts', 'skills/**', 'design-templates/**', 'templates/live-artifacts/**', 'plugins/_official/**') }}
+
       - name: Lint changed blog SEO
         # The build above sets OD_LANDING_NOINDEX=1, so every rendered page in
         # `out/` carries `noindex`. Pass the same flag through so the SEO linter

.github/workflows/release-beta-s.yml

@@ -754,7 +754,8 @@ jobs:
             -BuildJsonPath "C:\.tmp\runner\od-beta\win_x64\build\build.json" `
             -IndexPath "C:\.tmp\runner\od-beta\win_x64\build\index.json" `
             -ReportRoot "C:\.tmp\runner\od-beta\win_x64\release-report\win_x64" `
-            -OutputsPath "C:\.tmp\runner\od-beta\win_x64\build\outputs.json"
+            -OutputsPath "C:\.tmp\runner\od-beta\win_x64\build\outputs.json" `
+            -RequireVelaCli
 
       - name: Write win_x64 release report
         if: ${{ always() }}
@@ -979,6 +980,10 @@ jobs:
           RELEASE_LATEST_CAS_REQUIRED: "true"
           RELEASE_ASSET_SUFFIX: auto
           RELEASE_CHANNEL: betas
+          RELEASE_LAUNCHER_VERSION_MIN_BETAS: ${{ vars.RELEASE_LAUNCHER_VERSION_MIN_BETAS }}
+          RELEASE_LAUNCHER_VERSION_MIN_STABLE: ${{ vars.RELEASE_LAUNCHER_VERSION_MIN_STABLE }}
+          RELEASE_LAUNCHER_VERSION_MIN_URL_BETAS: ${{ vars.RELEASE_LAUNCHER_VERSION_MIN_URL_BETAS }}
+          RELEASE_LAUNCHER_VERSION_MIN_URL_STABLE: ${{ vars.RELEASE_LAUNCHER_VERSION_MIN_URL_STABLE }}
           RELEASE_MANIFEST_DIR: ${{ runner.temp }}/release-platform-manifests
           RELEASE_METADATA_DIR: ${{ runner.temp }}/release-metadata
           RELEASE_NOTE_MANIFEST_PATH: ${{ runner.temp }}/release-metadata/release-note-publication.json