orca/.github/actions/prepare-native-runtime/action.yml

name: Prepare native runtime
description: Restore and probe source-built native modules for the requested runtime.

inputs:
  native-runtime:
    description: Native runtime to prepare (none, node, or electron).
    required: false
    default: none
  node-version:
    description: Resolved Node.js version provided by setup-node.
    required: true
  persist-native-cache:
    description: Save native modules at job end unless a later step changes their ABI.
    required: false
    default: 'true'

outputs:
  cache-scope:
    description: Operating-system image scope used by the native module cache.
    value: ${{ steps.native-cache-scope.outputs.scope }}
  cache-key:
    description: Exact key requested for this runtime, independent of whether restoration succeeds.
    value: ${{ steps.native-cache-scope.outputs.key }}
  cache-path:
    description: Native build directories covered by the requested cache.
    value: ${{ steps.native-cache-scope.outputs.path }}
  cache-hit:
    description: Whether compiled native modules were restored under the exact requested key.
    value: ${{ steps.native-cache-restore.outputs.cache-hit || steps.native-cache-restore-only.outputs.cache-hit }}

runs:
  using: composite
  steps:
    - name: Validate native runtime
      shell: bash
      env:
        NATIVE_RUNTIME: ${{ inputs.native-runtime }}
        NODE_VERSION: ${{ inputs.node-version }}
      run: |
        case "$NATIVE_RUNTIME" in
          none) ;;
          node|electron) test -n "$NODE_VERSION" ;;
          *)
            echo "::error::native-runtime must be none, node, or electron"
            exit 2
            ;;
        esac

    # Exact keys separate runtime, architecture and host libc; every restored addon is probed.
    - name: Resolve native cache scope
      id: native-cache-scope
      if: inputs.native-runtime != 'none'
      shell: bash
      env:
        NATIVE_RUNTIME: ${{ inputs.native-runtime }}
        NODE_VERSION: ${{ inputs.node-version }}
        NATIVE_SOURCE_HASH: ${{ hashFiles('pnpm-lock.yaml', 'pnpm-workspace.yaml', '.npmrc', '.pnpmfile.cjs', '.github/actions/prepare-native-runtime/action.yml', 'config/scripts/ensure-native-runtime.mjs', 'config/scripts/rebuild-native-deps.mjs', 'config/scripts/node-pty-job-ownership.cjs', 'config/scripts/windows-pe-machine.cjs', 'config/scripts/windows-process-tree-gyp-rebuild.mjs', 'config/scripts/windows-process-tree-creation-time.cjs', 'config/scripts/install-electron-package-binary.mjs', 'config/scripts/electron-platform-path.mjs', 'config/scripts/zip-extractor-command.mjs', 'src/shared/zip-extractor-command.ts', 'config/scripts/shared-electron-dist-cache.mjs', 'config/scripts/space-sharing-copy.mjs', 'config/patches/node-pty@1.1.0.patch', 'config/patches/@vscode__windows-process-tree@0.8.0.patch', 'native/windows-registry/src/addon.cc', 'native/windows-registry/binding.gyp', 'native/windows-registry/package.json', 'native/windows-registry/index.js') }}
      run: |
        scope="${ImageOS:-$RUNNER_OS}"
        if [ -r /etc/os-release ]; then
          . /etc/os-release
          scope="${ID:-linux}-${VERSION_ID:-unknown}"
        fi
        pnpm_version="$(pnpm --version)"
        test -n "$pnpm_version"
        printf 'scope=%s\n' "$scope" >> "$GITHUB_OUTPUT"
        printf 'key=native-modules-%s-%s-%s-%s-node%s-pnpm%s-%s\n' "$RUNNER_OS" "$scope" "$RUNNER_ARCH" "$NATIVE_RUNTIME" "$NODE_VERSION" "$pnpm_version" "$NATIVE_SOURCE_HASH" >> "$GITHUB_OUTPUT"
        cat >> "$GITHUB_OUTPUT" <<'ORCA_NATIVE_CACHE_PATHS'
        path<<ORCA_NATIVE_BUILD_DIRECTORIES
        node_modules/.pnpm/node-pty@*/node_modules/node-pty/build
        native/windows-registry/build
        node_modules/.pnpm/@vscode+windows-process-tre*/node_modules/@vscode/windows-process-tree/build
        ORCA_NATIVE_BUILD_DIRECTORIES
        ORCA_NATIVE_CACHE_PATHS

    - name: Restore compiled native modules
      id: native-cache-restore
      if: inputs.native-runtime != 'none' && inputs.persist-native-cache != 'false'
      uses: actions/cache@v5
      with:
        # Post-job saving cannot resolve nested composite step outputs.
        path: |
          node_modules/.pnpm/node-pty@*/node_modules/node-pty/build
          native/windows-registry/build
          node_modules/.pnpm/@vscode+windows-process-tre*/node_modules/@vscode/windows-process-tree/build
        key: ${{ steps.native-cache-scope.outputs.key }}

    - name: Restore compiled native modules without saving
      id: native-cache-restore-only
      if: inputs.native-runtime != 'none' && inputs.persist-native-cache == 'false'
      uses: actions/cache/restore@v5
      with:
        path: |
          node_modules/.pnpm/node-pty@*/node_modules/node-pty/build
          native/windows-registry/build
          node_modules/.pnpm/@vscode+windows-process-tre*/node_modules/@vscode/windows-process-tree/build
        key: ${{ steps.native-cache-scope.outputs.key }}

    # pnpm's bundled gyp_main.py is not executable; Electron rebuild uses its own node-gyp API.
    - name: Use external node-gyp
      if: runner.os == 'Linux' && inputs.native-runtime == 'node'
      shell: bash
      env:
        NATIVE_RUNTIME: ${{ inputs.native-runtime }}
        NATIVE_CACHE_HIT: ${{ steps.native-cache-restore.outputs.cache-hit || steps.native-cache-restore-only.outputs.cache-hit }}
      run: |
        # A cache hit can contain unusable addons; probe before skipping the rebuild toolchain.
        if [ "$NATIVE_RUNTIME" = node ] && [ "$NATIVE_CACHE_HIT" = true ] &&
          node config/scripts/ensure-native-runtime.mjs --check-only; then
          exit 0
        fi
        npm install -g node-gyp@11.5.0
        echo "npm_config_node_gyp=$(npm root -g)/node-gyp/bin/node-gyp.js" >> "$GITHUB_ENV"

    - name: Prepare native runtime
      if: inputs.native-runtime != 'none'
      shell: bash
      env:
        NATIVE_RUNTIME: ${{ inputs.native-runtime }}
      run: node config/scripts/ensure-native-runtime.mjs --runtime="$NATIVE_RUNTIME"