chore(shellcheck): add yarn shellcheck script and CI workflow

Adds a deterministic lint gate over every tracked .sh file in the
repository.

- `scripts/shellcheck.sh` enumerates `git ls-files '*.sh'` and runs
  `shellcheck -S warning` over the list, forwarding any extra args
  to the underlying checker. Exits 0 when the list is empty so
  forks or branches that have not yet adopted a shell script stay
  green.
- `yarn shellcheck` wires the wrapper into the root `package.json`
  scripts table.
- `.github/workflows/shellcheck.yml` runs the gate on push to
  master and on any pull_request that touches a `.sh` file (the
  workflow's `paths:` filter). A PR that touches no shell scripts
  does not trigger the workflow at all, matching the maintainer's
  "skip when no .sh in the diff from the base" requirement.

shellcheck ships preinstalled on `ubuntu-latest` runners so no
additional dependency or apt install is needed. Action pins follow
the project's existing zizmor-pedantic posture
(`actions/checkout@de0fac2e...`); the workflow scope grants
`contents: read` and the job runs with `persist-credentials: false`.

Author: endolinbot

.github/workflows/shellcheck.yml

@@ -0,0 +1,44 @@
+name: Shell script lint
+
+# Run shellcheck against every .sh file tracked in the repo. The
+# workflow is gated on path-filter `**/*.sh`, so a PR that touches no
+# shell scripts does not trigger any runs at all (the "skip when no
+# .sh in the diff from the base" behavior).
+#
+# Pushes to master always run (no path-filter), so the gate is
+# authoritative for the master branch.
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    paths:
+      - '**/*.sh'
+      - 'scripts/shellcheck.sh'
+      - '.github/workflows/shellcheck.yml'
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  shellcheck:
+    name: shellcheck
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      # shellcheck ships preinstalled on ubuntu-latest runners. Print
+      # the version so a regression in the image surfaces here rather
+      # than as an unexplained gate flap.
+      - name: Show shellcheck version
+        run: shellcheck --version
+
+      - name: Run yarn shellcheck
+        run: ./scripts/shellcheck.sh

package.json

@@ -55,6 +55,7 @@
     "lint:fix": "yarn lint:eslint -- --fix",
     "lint:workspaces:fix": "yarn workspaces foreach --all run lint-fix",
     "lint:prettier": "prettier --check .github packages",
+    "shellcheck": "scripts/shellcheck.sh",
     "release:npm": "scripts/release-npm.mjs",
     "pack:all": "scripts/pack-all.mjs",
     "smoketest:publish": "scripts/smoketest-publishing.sh",

scripts/shellcheck.sh

@@ -0,0 +1,33 @@
+#!/bin/sh
+# Run shellcheck against every .sh file tracked in the repository.
+#
+# Exits 0 when no .sh files are tracked. Extra arguments are forwarded to
+# the underlying checker, so callers can override severity or exclude
+# codes:
+#
+#   yarn shellcheck                     # default severity warning
+#   yarn shellcheck --severity=error    # tighter gate
+#   yarn shellcheck -- -e SC2086        # exclude a code
+#
+# The list is enumerated via `git ls-files '*.sh'` so untracked scratch
+# scripts and worktree noise are ignored.
+
+set -eu
+
+# Read NUL-delimited paths into a single newline-separated list so the body
+# can branch on emptiness. xargs is not used directly because BSD xargs
+# (macOS) lacks `-r` and runs the command on an empty list, which would
+# invoke `shellcheck` with no positional arguments and read from stdin.
+files=$(git ls-files -z '*.sh' | tr '\0' '\n')
+
+if [ -z "$files" ]; then
+  echo "shellcheck: no .sh files tracked; skipping."
+  exit 0
+fi
+
+# shellcheck disable=SC2086
+# Word splitting on $files is intentional: each line is a separate path
+# and tracked .sh filenames in this repo do not contain whitespace.
+# `git ls-files` would happily emit NULs for whitespace-bearing names; if
+# such a name lands here, switch to xargs -0 with a portability shim.
+echo "$files" | xargs shellcheck -S warning "$@"