fix(actions): reuse installed CLI in high-level actions; drop npm cache (#478)

The setup action unconditionally ran `npm install -g` on every invocation
and cached `~/.npm` + the oclif data dir — neither of which contains the npm
global prefix where the `b2c` binary lives. The cache therefore never let the
install be skipped (it only saved download bandwidth) while growing to
gigabytes on long-lived self-hosted runners, and high-level actions that call
setup internally reinstalled the CLI a second time per pipeline.

- Remove the actions/cache step. On self-hosted runners the global install
  already persists between jobs; on hosted runners a clean install is faster
  than restoring a multi-GB cache.
- High-level actions (code-deploy, data-import, job-run, mrt-deploy,
  webdav-upload) pass skip-if-present=true so they reuse an already-installed
  CLI and install only when none is present — no redundant reinstall, no
  unexpected upgrade. The cold path installs the requested spec directly
  (npm resolves tags/ranges) with no registry probe that could fail offline.
- setup called directly stays explicit: it always installs the requested
  version. New skip-if-present input (default false) opts into reuse.
- Harden plugin install: parse `b2c plugins --json` for exact-name matching
  (grep -Fxq, no substring/regex collisions), read the plugins list from an
  env var instead of raw interpolation, and trim whitespace/CR in pure bash
  instead of xargs.

Inputs/outputs are backward compatible; the only behavior change is that a
wrapper action on a self-hosted runner with a pre-existing CLI reuses it.

Author: clavery

.changeset/setup-action-idempotent-install.md

@@ -0,0 +1,5 @@
+---
+'@salesforce/b2c-dx-docs': patch
+---
+
+Document the GitHub Actions install behavior change. The high-level actions (`code-deploy`, `data-import`, `job-run`, `mrt-deploy`, `webdav-upload`) now reuse an already-installed CLI and install one only when none is present — so a deploy that follows a setup step, and repeated operations on a persistent self-hosted runner, no longer trigger a redundant reinstall or an unexpected upgrade. The `setup` action called directly still installs the version you request (a new `skip-if-present` input opts into reuse). The actions no longer cache the npm download directory, which had grown to gigabytes on long-lived self-hosted runners and slowed restores. Plugin installs are skipped by exact name match.

actions/README.md

@@ -113,7 +113,7 @@ Install CLI plugins via the `plugins` input on the `setup` action (one per line)
       sfcc-solutions-share/b2c-plugin-intellij-sfcc-config
 ```
 
-Each entry is an npm package name or GitHub `owner/repo`. Plugins are cached alongside the CLI.
+Each entry is an npm package name or GitHub `owner/repo`. Already-installed plugins are skipped on re-invocation.
 
 ## Logging
 

actions/code-deploy/action.yml

@@ -72,6 +72,8 @@ runs:
       with:
         version: ${{ inputs.version }}
         node-version: ${{ inputs.node-version }}
+        # Reuse an already-installed CLI; only install when none is present.
+        skip-if-present: 'true'
         client-id: ${{ inputs.client-id }}
         client-secret: ${{ inputs.client-secret }}
         server: ${{ inputs.server }}

actions/data-import/action.yml

@@ -61,6 +61,8 @@ runs:
       with:
         version: ${{ inputs.version }}
         node-version: ${{ inputs.node-version }}
+        # Reuse an already-installed CLI; only install when none is present.
+        skip-if-present: 'true'
         client-id: ${{ inputs.client-id }}
         client-secret: ${{ inputs.client-secret }}
         server: ${{ inputs.server }}

actions/job-run/action.yml

@@ -59,6 +59,8 @@ runs:
       with:
         version: ${{ inputs.version }}
         node-version: ${{ inputs.node-version }}
+        # Reuse an already-installed CLI; only install when none is present.
+        skip-if-present: 'true'
         client-id: ${{ inputs.client-id }}
         client-secret: ${{ inputs.client-secret }}
         server: ${{ inputs.server }}

actions/mrt-deploy/action.yml

@@ -51,6 +51,8 @@ runs:
       with:
         version: ${{ inputs.version }}
         node-version: ${{ inputs.node-version }}
+        # Reuse an already-installed CLI; only install when none is present.
+        skip-if-present: 'true'
         mrt-api-key: ${{ inputs.mrt-api-key }}
         mrt-project: ${{ inputs.project }}
         mrt-environment: ${{ inputs.environment }}

actions/setup/action.yml

@@ -9,6 +9,10 @@ inputs:
     description: 'CLI version to install (e.g. "latest", "0.4.1", "nightly")'
     required: false
     default: 'latest'
+  skip-if-present:
+    description: 'Reuse an already-installed CLI instead of installing. When true, the CLI is installed only if none is present (no version check, no upgrade). High-level actions set this so they reuse an existing install; a direct setup call leaves it false and always installs the requested version.'
+    required: false
+    default: 'false'
   node-version:
     description: 'Node.js version to install'
     required: false
@@ -69,20 +73,36 @@ runs:
       with:
         node-version: ${{ inputs.node-version }}
 
-    - name: Cache npm and CLI data
-      uses: actions/cache@v4
-      with:
-        path: |
-          ~/.npm
-          ~/.local/share/b2c
-        key: b2c-cli-${{ runner.os }}-${{ inputs.version }}-${{ inputs.plugins || 'no-plugins' }}
-        restore-keys: |
-          b2c-cli-${{ runner.os }}-${{ inputs.version }}-
-          b2c-cli-${{ runner.os }}-
-
     - name: Install B2C CLI
       shell: bash
-      run: npm install -g @salesforce/b2c-cli@${{ inputs.version }}
+      env:
+        B2C_VERSION: ${{ inputs.version }}
+        B2C_SKIP_IF_PRESENT: ${{ inputs.skip-if-present }}
+      run: |
+        REQUESTED="${B2C_VERSION:-latest}"
+
+        # Is a usable CLI already on PATH? (handles re-invocation within a job and
+        # persistent self-hosted runners where the install survives between jobs)
+        INSTALLED=""
+        if command -v b2c >/dev/null 2>&1; then
+          # Token anchored to the package name so it can never capture the node version
+          # from "@salesforce/b2c-cli/<ver> <platform> node-v<ver>".
+          INSTALLED=$(b2c --version 2>/dev/null | grep -oE '@salesforce/b2c-cli/[^[:space:]]+' | head -n1 | cut -d/ -f3 || true)
+        fi
+
+        if [ "$B2C_SKIP_IF_PRESENT" = "true" ] && [ -n "$INSTALLED" ]; then
+          # "Ensure a CLI is available" mode (used by high-level actions): reuse whatever
+          # is installed; never upgrade and never hit the network. This is what makes a
+          # deploy/import that follows a setup step a no-op instead of a reinstall.
+          echo "B2C CLI ${INSTALLED} already present; reusing it (skip-if-present)"
+        else
+          # Calling setup directly is an explicit request to install the requested
+          # version. Install the spec directly — npm resolves tags ("latest"/"nightly")
+          # and ranges itself, so no registry probe is needed, keeping the path fast and
+          # free of a network call that could fail the step.
+          echo "Installing @salesforce/b2c-cli@${REQUESTED} (currently: ${INSTALLED:-none})"
+          npm install -g "@salesforce/b2c-cli@${REQUESTED}"
+        fi
 
     - name: Set environment variables
       shell: bash
@@ -134,14 +154,45 @@ runs:
     - name: Install plugins
       if: inputs.plugins != ''
       shell: bash
+      env:
+        B2C_PLUGINS: ${{ inputs.plugins }}
       run: |
+        # Installed plugin names, one per line, exactly as the CLI records them
+        # (the published package name — not the GitHub repo slug). Parsed from --json
+        # with node (always present; setup-node ran first) so the match is exact.
+        INSTALLED_PLUGINS=$(b2c plugins --json 2>/dev/null \
+          | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{try{for(const p of JSON.parse(s))if(p&&p.name)console.log(p.name)}catch(e){}})' \
+          || true)
+
         while IFS= read -r plugin; do
-          plugin=$(echo "$plugin" | xargs)
+          # Trim surrounding whitespace (incl. a trailing CR from CRLF-encoded YAML)
+          # with pure bash — avoids `xargs`, which aborts the step on an unbalanced
+          # quote and mangles backslashes.
+          plugin="${plugin#"${plugin%%[![:space:]]*}"}"
+          plugin="${plugin%"${plugin##*[![:space:]]}"}"
           if [ -n "$plugin" ]; then
-            echo "Installing plugin: $plugin"
-            b2c plugins install "$plugin"
+            # Determine the name to match against installed plugins. npm specs (scoped
+            # "@scope/name" or bare "name") are recorded verbatim. For a GitHub
+            # "owner/repo" spec the published package name is unknown ahead of time, so
+            # fall back to the repo basename — which equals the package name for the
+            # common case. Exact, fixed-string line match (grep -Fxq) avoids both
+            # substring false-positives and regex-metacharacter surprises.
+            spec="${plugin%/}"          # drop a trailing slash before deriving the name
+            if [ "${spec:0:1}" = "@" ] || [ "${spec%/*}" = "$spec" ]; then
+              name="$spec"              # scoped npm name, or bare npm name (no slash)
+            else
+              name="${spec##*/}"        # GitHub owner/repo -> repo basename
+            fi
+            # Only skip on a real, non-empty exact match; an empty name must never
+            # match the (possibly empty) installed list and silently skip the install.
+            if [ -n "$name" ] && printf '%s\n' "$INSTALLED_PLUGINS" | grep -Fxq "$name"; then
+              echo "Plugin already installed: $plugin"
+            else
+              echo "Installing plugin: $plugin"
+              b2c plugins install "$plugin"
+            fi
           fi
-        done <<< "${{ inputs.plugins }}"
+        done <<< "$B2C_PLUGINS"
 
     - name: Verify installation
       id: verify

actions/webdav-upload/action.yml

@@ -57,6 +57,8 @@ runs:
       with:
         version: ${{ inputs.version }}
         node-version: ${{ inputs.node-version }}
+        # Reuse an already-installed CLI; only install when none is present.
+        skip-if-present: 'true'
         client-id: ${{ inputs.client-id }}
         client-secret: ${{ inputs.client-secret }}
         server: ${{ inputs.server }}

docs/guide/ci-cd.md

@@ -19,7 +19,7 @@ The actions are available from the `SalesforceCommerceCloud/b2c-developer-toolin
 - **WebDAV uploads** — upload files for data import, content, etc.
 - **Any CLI command** — raw passthrough for operations not covered by high-level actions
 
-All actions are composite YAML — no compiled JavaScript, fully transparent and auditable. They cache the npm install across runs and expose structured JSON outputs for downstream workflow steps.
+All actions are composite YAML — no compiled JavaScript, fully transparent and auditable. The high-level actions (`code-deploy`, `data-import`, `job-run`, `mrt-deploy`, `webdav-upload`) reuse an already-installed CLI and only install one when none is present — so running a deploy after a setup step, or repeated operations on a self-hosted runner, do not trigger a redundant reinstall. The `setup` action called directly is explicit: it installs the version you request. Actions expose structured JSON outputs for downstream workflow steps.
 
 ## Authentication
 
@@ -114,7 +114,7 @@ Combines setup and command execution. Pass a `command` to run a CLI command, or
 uses: SalesforceCommerceCloud/b2c-developer-tooling/actions/setup@v1
 ```
 
-Installs the CLI and writes credentials to environment variables. Use this when you need multiple steps after setup.
+Installs the CLI and writes credentials to environment variables. Use this when you need multiple steps after setup. Called directly, `setup` always installs the requested `version`. Set `skip-if-present: 'true'` to reuse an already-installed CLI and install only when none is present (this is what the high-level actions do internally so they never reinstall on top of an existing CLI).
 
 ```yaml
 - uses: SalesforceCommerceCloud/b2c-developer-tooling/actions/setup@v1
@@ -127,7 +127,7 @@ Installs the CLI and writes credentials to environment variables. Use this when
       sfcc-solutions-share/b2c-plugin-intellij-sfcc-config
 ```
 
-Plugins are installed after the CLI and cached across runs. Each line is an npm package name or GitHub `owner/repo`.
+Plugins are installed after the CLI; already-installed plugins are skipped by exact name match. Each line is an npm package name or GitHub `owner/repo`. For reliable skip-on-reinstall, prefer the published npm package name — when a GitHub `owner/repo` slug differs from the package it publishes, the plugin is reinstalled each run (harmless, just slower).
 
 ### Run
 
@@ -414,7 +414,7 @@ The CLI supports [plugins](/guide/extending) for custom configuration sources, H
       sfcc-solutions-share/b2c-plugin-intellij-sfcc-config
 ```
 
-Each line is an npm package name or GitHub `owner/repo`. Plugins are installed after the CLI and cached across workflow runs.
+Each line is an npm package name or GitHub `owner/repo`. Plugins are installed after the CLI; already-installed plugins are skipped on re-invocation.
 
 ## Logging