@sebastienrousseau/dotfiles 0.2.500 → 0.2.502

package/scripts/ci/check-deps-dev.sh

@@ -0,0 +1,236 @@
+#!/usr/bin/env bash
+# Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+# =============================================================================
+# check-deps-dev.sh — Validate direct dependencies against the deps.dev
+# Insights API. Catches supply-chain risk a Grype-only scan misses:
+# stale-but-CVE-free packages, unattested artifacts, and packages with
+# advisories that haven't yet been mapped to a CVE.
+#
+# Scans:
+#   * `package.json` — direct `dependencies` + `devDependencies` (npm).
+#   * `pyproject.toml` — direct `[project.dependencies]` (Python).
+#   * `.github/workflows/*.yml` — `uses:` action references (GitHub Actions).
+#
+# Skips ecosystems with no matching manifest.
+#
+# Exit codes:
+#   0  no advisories found (or all under threshold).
+#   1  one or more direct deps have advisories at or above the threshold.
+#   2  prerequisites missing (jq / curl / python3).
+#
+# Closes part of #877.
+# =============================================================================
+
+set -uo pipefail
+
+REPO_ROOT="${REPO_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+THRESHOLD="${DEPS_DEV_SEVERITY_THRESHOLD:-HIGH}" # LOW | MEDIUM | HIGH | CRITICAL
+DEPS_DEV_BASE="${DEPS_DEV_BASE:-https://api.deps.dev/v3}"
+EXCEPTIONS_FILE="$REPO_ROOT/docs/security/DEPS_DEV_EXCEPTIONS.md"
+SARIF_OUT="${DEPS_DEV_SARIF_OUT:-}"
+
+# Strict mode: bail on prerequisites.
+for cmd in jq curl python3; do
+  if ! command -v "$cmd" >/dev/null 2>&1; then
+    echo "::warning::check-deps-dev: $cmd not available — skipping." >&2
+    exit 0
+  fi
+done
+
+# -----------------------------------------------------------------------------
+# Helpers
+# -----------------------------------------------------------------------------
+
+# severity_rank — map deps.dev severity strings to integers so we can
+# compare against THRESHOLD numerically.
+severity_rank() {
+  case "${1:-}" in
+    CRITICAL) echo 4 ;;
+    HIGH) echo 3 ;;
+    MEDIUM | MODERATE) echo 2 ;;
+    LOW) echo 1 ;;
+    *) echo 0 ;;
+  esac
+}
+
+THRESHOLD_RANK=$(severity_rank "$THRESHOLD")
+
+# is_excepted — check if a (system, name) pair has an active exception
+# entry in DEPS_DEV_EXCEPTIONS.md. Exceptions look like:
+#   `npm:lodash` (expires 2026-12-31): <reason>
+is_excepted() {
+  local system="$1" name="$2"
+  [[ -f "$EXCEPTIONS_FILE" ]] || return 1
+  grep -Eq "^\s*\`${system}:${name}\`" "$EXCEPTIONS_FILE"
+}
+
+# fetch_advisories — query deps.dev for advisories on a (system, name,
+# version) triple. Prints one advisory-key per line; empty if none.
+fetch_advisories() {
+  local system="$1" name="$2" version="$3"
+  local encoded_name
+  encoded_name=$(python3 -c 'import urllib.parse, sys; print(urllib.parse.quote(sys.argv[1], safe=""))' "$name")
+  local url="$DEPS_DEV_BASE/systems/$system/packages/$encoded_name/versions/$version"
+  curl -fsSL --max-time 15 "$url" 2>/dev/null |
+    jq -r '.advisoryKeys[]?.id // empty' 2>/dev/null ||
+    true
+}
+
+# fetch_advisory_severity — given an advisory ID, return its highest
+# severity rating. Returns empty string when the API doesn't expose
+# severity (older advisories sometimes lack it).
+fetch_advisory_severity() {
+  local advisory_id="$1"
+  local encoded
+  encoded=$(python3 -c 'import urllib.parse, sys; print(urllib.parse.quote(sys.argv[1], safe=""))' "$advisory_id")
+  curl -fsSL --max-time 15 "$DEPS_DEV_BASE/advisories/$encoded" 2>/dev/null |
+    jq -r '.severity[]?.type // empty' 2>/dev/null |
+    head -1 ||
+    true
+}
+
+# -----------------------------------------------------------------------------
+# Manifest readers
+# -----------------------------------------------------------------------------
+
+# Each reader prints one "system\tname\tversion" line per direct dep.
+
+read_npm() {
+  local pkg="$REPO_ROOT/package.json"
+  [[ -f "$pkg" ]] || return 0
+  jq -r '
+    [.dependencies // {}, .devDependencies // {}]
+    | add // {}
+    | to_entries[]
+    | "NPM\t\(.key)\t\(.value | sub("^[~^>=<]+"; ""))"
+  ' "$pkg"
+}
+
+read_pypi() {
+  local pyproj="$REPO_ROOT/pyproject.toml"
+  [[ -f "$pyproj" ]] || return 0
+  python3 - "$pyproj" <<'PY'
+import sys
+try:
+    import tomllib
+except ImportError:
+    try:
+        import tomli as tomllib  # type: ignore
+    except ImportError:
+        sys.exit(0)
+data = tomllib.load(open(sys.argv[1], "rb"))
+deps = data.get("project", {}).get("dependencies", [])
+for spec in deps:
+    # spec is like "requests>=2.28.0"; pull name + version.
+    name = spec.split("[")[0].split(">")[0].split("<")[0].split("=")[0].strip()
+    version = ""
+    for op in (">=", "<=", "==", ">", "<"):
+        if op in spec:
+            version = spec.split(op, 1)[1].strip().split(",")[0]
+            break
+    print(f"PYPI\t{name}\t{version}")
+PY
+}
+
+read_actions() {
+  local f
+  for f in "$REPO_ROOT"/.github/workflows/*.yml; do
+    [[ -f "$f" ]] || continue
+    # Match `uses: owner/repo@<40-hex-sha> # vX.Y.Z`
+    grep -Eo 'uses:[[:space:]]+[a-zA-Z0-9._-]+/[a-zA-Z0-9._/-]+@[a-f0-9]{40}[[:space:]]*#[[:space:]]*v[0-9.]+' "$f" |
+      sed -E 's/uses:[[:space:]]+([^@]+)@[a-f0-9]{40}[[:space:]]+#[[:space:]]+v([0-9.]+).*/GITHUB_ACTIONS\t\1\t\2/' ||
+      true
+  done | sort -u
+}
+
+# -----------------------------------------------------------------------------
+# Main scan
+# -----------------------------------------------------------------------------
+
+findings=()
+total_scanned=0
+
+scan_one() {
+  local system="$1" name="$2" version="$3"
+  [[ -z "$name" || -z "$version" ]] && return 0
+  total_scanned=$((total_scanned + 1))
+
+  if is_excepted "$system" "$name"; then
+    echo "  - skip $system:$name@$version (excepted)" >&2
+    return 0
+  fi
+
+  local advs
+  advs=$(fetch_advisories "$system" "$name" "$version")
+  [[ -z "$advs" ]] && return 0
+
+  while IFS= read -r adv; do
+    [[ -z "$adv" ]] && continue
+    local sev
+    sev=$(fetch_advisory_severity "$adv")
+    local rank
+    rank=$(severity_rank "$sev")
+    if ((rank >= THRESHOLD_RANK)); then
+      findings+=("$system:$name@$version :: $adv ($sev)")
+      echo "::warning::deps.dev advisory $sev: $system $name $version → $adv" >&2
+    fi
+  done <<<"$advs"
+}
+
+echo "Scanning manifests under $REPO_ROOT ..." >&2
+
+# 1. npm
+while IFS=$'\t' read -r system name version; do
+  scan_one "$system" "$name" "$version"
+done < <(read_npm)
+
+# 2. pypi
+while IFS=$'\t' read -r system name version; do
+  scan_one "$system" "$name" "$version"
+done < <(read_pypi)
+
+# 3. GitHub Actions (best-effort — deps.dev coverage is partial)
+while IFS=$'\t' read -r system name version; do
+  scan_one "$system" "$name" "$version"
+done < <(read_actions)
+
+echo "Scanned $total_scanned direct dependencies." >&2
+
+# Optional SARIF emission for Code Scanning upload.
+if [[ -n "$SARIF_OUT" ]]; then
+  python3 - "$SARIF_OUT" "${findings[@]+"${findings[@]}"}" <<'PY'
+import json, sys
+out = sys.argv[1]
+findings = sys.argv[2:]
+runs = [{
+    "tool": {"driver": {
+        "name": "check-deps-dev",
+        "version": "1.0.0",
+        "informationUri": "https://deps.dev",
+    }},
+    "results": [
+        {
+            "ruleId": "deps-dev-advisory",
+            "level": "error",
+            "message": {"text": f},
+        }
+        for f in findings
+    ],
+}]
+with open(out, "w") as fp:
+    json.dump({"version": "2.1.0", "$schema": "https://json.schemastore.org/sarif-2.1.0.json", "runs": runs}, fp)
+print(f"SARIF written: {out}")
+PY
+fi
+
+if [[ "${#findings[@]}" -gt 0 ]]; then
+  echo "" >&2
+  echo "::error::${#findings[@]} dep(s) flagged at or above ${THRESHOLD}." >&2
+  printf '  %s\n' "${findings[@]}" >&2
+  echo "" >&2
+  echo "Document exceptions at docs/security/DEPS_DEV_EXCEPTIONS.md with expiry dates." >&2
+  exit 1
+fi
+
+echo "deps.dev validation: clean." >&2
+exit 0

package/scripts/ci/check-insecure-tls.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+# Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+# =============================================================================
+# check-insecure-tls.sh — block `curl -k` / `curl --insecure` /
+# `wget --no-check-certificate` patterns from landing.
+#
+# Invoked as a pre-commit local hook (no filename args; scans the repo).
+# Extracted from `config/pre-commit-config.yaml` under #866 so the line
+# is yamllint-clean and the matcher can be tested in isolation.
+#
+# Matcher uses awk for proper tokenization (the previous inline grep
+# regex false-positive'd `-k` inside package names like `-keyring`).
+# =============================================================================
+
+set -euo pipefail
+
+ROOT="${1:-.}"
+
+# Awk body intentionally lives in a variable. The $i / $NF / FILENAME /
+# NR references inside are awk's own field/record variables — NOT shell
+# variables — so the whole body must stay literal (single-quoted). The
+# SC2016 suppression is the canonical signal to readers + linters that
+# this is intentional.
+# shellcheck disable=SC2016
+AWK_BODY='
+  # Each input line tokenized on whitespace. Flag if the line uses
+  # curl/wget and a known insecure flag appears as a standalone token.
+  {
+    has_curl = 0; has_wget = 0
+    bad = ""
+    for (i = 1; i <= NF; i++) {
+      tok = $i
+      if (tok == "curl") has_curl = 1
+      if (tok == "wget") has_wget = 1
+      if (has_curl && (tok == "-k" || tok == "--insecure" || tok ~ /^--insecure=/)) {
+        bad = tok
+      }
+      if (has_wget && (tok == "--no-check-certificate" || tok ~ /^--no-check-certificate=/)) {
+        bad = tok
+      }
+    }
+    if (bad != "") printf "%s:%d:%s\n", FILENAME, NR, bad
+  }
+'
+
+matches=$(
+  grep -rln \
+    --include='*.sh' --include='*.bash' --include='*.zsh' --include='*.tmpl' \
+    --exclude-dir='.git' \
+    --exclude='check-insecure-tls.sh' \
+    -E '\b(curl|wget)\b' \
+    "$ROOT" 2>/dev/null |
+    xargs -I{} awk "$AWK_BODY" {} 2>/dev/null
+)
+
+if [[ -n "$matches" ]]; then
+  echo "ERROR: Insecure TLS patterns found." >&2
+  echo "$matches" >&2
+  echo "Remove the flag or, if absolutely required, pin the cert and document the why." >&2
+  exit 1
+fi

package/scripts/ci/check-regression-traceability.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+# =============================================================================
+# check-regression-traceability.sh — enforce a `# Regression for:` header on
+# every file under `tests/regression/`, with one of three accepted forms:
+#
+#   # Regression for: GH-1234
+#   # Regression for: <7-or-more-char-sha-prefix>
+#   # Regression for: pre-history
+#
+# The first two are required for any test introduced as part of fixing a
+# known issue or shipping a known commit. The third is an explicit "we
+# couldn't trace it" marker — still trackable, just not auto-resolvable.
+#
+# Invocation:
+#   * pre-commit local hook (files passed as args)
+#   * standalone: ./scripts/ci/check-regression-traceability.sh
+# =============================================================================
+
+set -euo pipefail
+
+PATTERN='^# *Regression for: *(GH-[0-9]+|[0-9a-f]{7,40}|pre-history)\b'
+
+check_one() {
+  local f="$1"
+  [[ -f "$f" ]] || return 0
+
+  # Only check files under tests/regression/
+  case "$f" in
+    tests/regression/*) ;;
+    */tests/regression/*) ;;
+    *) return 0 ;;
+  esac
+
+  if ! head -15 "$f" | grep -Eq "$PATTERN"; then
+    echo "MISSING trace header: $f"
+    return 1
+  fi
+}
+
+fail=0
+if [[ $# -gt 0 ]]; then
+  for f in "$@"; do
+    check_one "$f" || fail=1
+  done
+else
+  while IFS= read -r f; do
+    check_one "$f" || fail=1
+  done < <(git ls-files "tests/regression/*.sh")
+fi
+
+if [[ $fail -ne 0 ]]; then
+  cat >&2 <<'MSG'
+
+Every file under tests/regression/ must include a trace header within
+the first 15 lines, in one of these forms:
+
+  # Regression for: GH-1234            (preferred — link to GitHub issue)
+  # Regression for: <sha-prefix>       (link to introducing commit)
+  # Regression for: pre-history        (no traceable origin)
+
+Why: regressions pinned years ago without context are forensic dead-ends
+when they fire. See docs/operations/TESTING.md and #868.
+
+MSG
+  exit 1
+fi

package/scripts/ci/check-shell-preamble.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+# Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+# =============================================================================
+# check-shell-preamble.sh — Enforce `set -euo pipefail` (bash) / `set -eu` (sh)
+# on every executable shell script in the repo.
+#
+# Skip-rules:
+#   * Sourced libraries that declare themselves as such via a "Sourced by ..."
+#     header comment in the first 15 lines.
+#   * Explicit opt-out via `# preamble:skip` marker in the first 15 lines
+#     (used by completion files, init fragments, and other library code that
+#     is loaded into the caller's shell context).
+#   * Files under tests/ (the test runner sets shell options for its children).
+#
+# Invocation:
+#   * pre-commit local hook (files passed as args)
+#   * standalone: ./scripts/ci/check-shell-preamble.sh           # full repo
+#                 ./scripts/ci/check-shell-preamble.sh file.sh   # explicit
+# =============================================================================
+
+set -euo pipefail
+
+check_one() {
+  local f="$1"
+
+  [[ -f "$f" ]] || return 0
+
+  local shebang
+  shebang="$(head -1 "$f" 2>/dev/null || true)"
+
+  # Only check files with a bash or sh shebang.
+  case "$shebang" in
+    *bash*) ;;
+    *sh) ;;
+    *) return 0 ;;
+  esac
+
+  # Skip files declaring themselves as sourced libraries or opting out.
+  if head -15 "$f" | grep -Eq '^# *(Sourced by |preamble:skip|shellcheck source-only)'; then
+    return 0
+  fi
+
+  # Skip the test suite — tests are sourced by tests/framework/test_runner.sh
+  # which manages shell options for its children.
+  case "$f" in
+    tests/*) return 0 ;;
+    # Bulk-sourced fragments. These directories contain hundreds of
+    # alias / function / PATH snippets that are sourced into the
+    # caller's shell context — adding `set -e` locally would corrupt
+    # the caller. Path-skipped en masse rather than annotated per-file
+    # (would be 300+ marker comments).
+    .chezmoitemplates/aliases/*) return 0 ;;
+    .chezmoitemplates/functions/*) return 0 ;;
+    .chezmoitemplates/paths/*) return 0 ;;
+    # dot_config/shell/* and scripts/dot/lib/* are also sourced but
+    # have explicit `# Sourced by` headers as of #854 (defense in
+    # depth — the lint also accepts them on header alone).
+    dot_local/bin/executable_dot_completion) return 0 ;; # zsh completion, sourced into shell
+  esac
+
+  # Required preamble lives within the first 50 lines (after optional docstring).
+  local preamble_re
+  case "$shebang" in
+    *bash*)
+      preamble_re='^[[:space:]]*set[[:space:]]+-([eu]+o[[:space:]]+pipefail|euo[[:space:]]+pipefail|eu[[:space:]]*$)'
+      ;;
+    *sh)
+      preamble_re='^[[:space:]]*set[[:space:]]+-eu[o]?'
+      ;;
+  esac
+
+  if ! head -50 "$f" | grep -Eq "$preamble_re"; then
+    echo "MISSING preamble: $f"
+    return 1
+  fi
+}
+
+fail=0
+if [[ $# -gt 0 ]]; then
+  for f in "$@"; do
+    check_one "$f" || fail=1
+  done
+else
+  # Full-repo scan
+  while IFS= read -r f; do
+    check_one "$f" || fail=1
+  done < <(git ls-files | grep -E '\.sh$|^dot_local/bin/executable_|^scripts/.+\.sh$')
+fi
+
+if [[ $fail -ne 0 ]]; then
+  cat >&2 <<'MSG'
+
+Some shell scripts are missing the safety preamble.
+  * bash → `set -euo pipefail`
+  * sh   → `set -eu`
+
+If the file is a sourced library, add this header to its first 15 lines:
+  # Sourced by <parent>.sh; inherits set -euo pipefail
+
+If the file is a shell init fragment / completion that must NOT enforce its own
+options on the caller, add this marker instead:
+  # preamble:skip
+
+MSG
+  exit 1
+fi

package/scripts/ci/dot-cli-startup-bench.sh

@@ -0,0 +1,126 @@
+#!/usr/bin/env bash
+# Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+#
+# scripts/ci/dot-cli-startup-bench.sh
+#
+# Sub-100ms cold-start gate for the `dot` CLI dispatcher.
+#
+# The §3 audit roadmap calls for measuring `dot help` / `dot version`
+# cold-start time and gating PRs on a regression budget. This script
+# runs the dispatcher N times under a clean shell, computes the median
+# elapsed time, and exits non-zero when the median exceeds the budget.
+#
+# Usage:
+#   bash scripts/ci/dot-cli-startup-bench.sh [--budget-ms <n>] [--runs <n>] [--cmd <argv>]
+#
+# Env overrides:
+#   DOT_BENCH_BUDGET_MS   Default budget in ms (default: 250).
+#   DOT_BENCH_RUNS        Number of runs (default: 11; median-of-N).
+#   DOT_BENCH_CMD         Argv passed to `dot` (default: "version").
+#
+# The default budget is 250ms — looser than the §3 aspirational 100ms
+# while we lazy-load mise/asdf/etc. CI ratchets this number down as
+# improvements land. Bench *failure* is a hard build failure; bench
+# *regression* (median > previous baseline + 15%) is a warning.
+
+set -euo pipefail
+
+BUDGET_MS="${DOT_BENCH_BUDGET_MS:-250}"
+RUNS="${DOT_BENCH_RUNS:-11}"
+DOT_ARGV_RAW="${DOT_BENCH_CMD:-version}"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --budget-ms)
+      BUDGET_MS="$2"
+      shift 2
+      ;;
+    --runs)
+      RUNS="$2"
+      shift 2
+      ;;
+    --cmd)
+      DOT_ARGV_RAW="$2"
+      shift 2
+      ;;
+    -h | --help)
+      sed -n '5,25p' "${BASH_SOURCE[0]}"
+      exit 0
+      ;;
+    *)
+      echo "Unknown arg: $1" >&2
+      exit 2
+      ;;
+  esac
+done
+
+# Locate the dot dispatcher binary. Prefer the repo-local copy so a
+# user-installed `dot` on PATH can't sneak in.
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+DOT_BIN="$REPO_ROOT/dot_local/bin/executable_dot"
+if [[ ! -x "$DOT_BIN" ]] && command -v dot >/dev/null 2>&1; then
+  DOT_BIN="$(command -v dot)"
+fi
+if [[ ! -f "$DOT_BIN" ]]; then
+  echo "::error::dot binary not found at $DOT_BIN" >&2
+  exit 2
+fi
+
+# Portable wall-clock to ms. macOS bash 3.2 has no $EPOCHREALTIME.
+_now_ms() {
+  if [[ -n "${EPOCHREALTIME:-}" ]]; then
+    # zsh / bash 5+: floating-point seconds.
+    awk -v t="$EPOCHREALTIME" 'BEGIN{printf "%d\n", t*1000}'
+  elif date +%s%N 2>/dev/null | grep -qE '^[0-9]+$'; then
+    # GNU date: nanoseconds.
+    echo $(($(date +%s%N) / 1000000))
+  elif command -v python3 >/dev/null 2>&1; then
+    python3 -c 'import time; print(int(time.time()*1000))'
+  else
+    # Fall back to seconds × 1000 (low resolution; warn).
+    echo "::warning::no high-resolution clock; using whole-second precision" >&2
+    echo $(($(date +%s) * 1000))
+  fi
+}
+
+# Parse argv string (space-separated).
+read -r -a DOT_ARGV <<<"$DOT_ARGV_RAW"
+
+echo "dot CLI cold-start benchmark"
+echo "  binary : $DOT_BIN"
+echo "  argv   : ${DOT_ARGV[*]}"
+echo "  runs   : $RUNS"
+echo "  budget : ${BUDGET_MS}ms"
+echo
+
+samples=()
+for ((i = 1; i <= RUNS; i++)); do
+  start_ms="$(_now_ms)"
+  # `env -i` strips inherited cached state so we measure cold-start, not
+  # warm-cache. Keep PATH so the dispatcher can find git/awk/etc.
+  env -i HOME="$HOME" PATH="$PATH" "$DOT_BIN" "${DOT_ARGV[@]}" >/dev/null 2>&1 || true
+  end_ms="$(_now_ms)"
+  elapsed=$((end_ms - start_ms))
+  samples+=("$elapsed")
+  printf '  run %2d: %dms\n' "$i" "$elapsed"
+done
+
+# Median of samples (odd RUNS → middle value).
+median="$(printf '%s\n' "${samples[@]}" | sort -n | awk -v n="$RUNS" 'NR==int(n/2)+1{print; exit}')"
+echo
+echo "median: ${median}ms  budget: ${BUDGET_MS}ms"
+
+# Optional baseline record for trend tracking.
+baseline_file="${DOT_BENCH_BASELINE:-$REPO_ROOT/.cache/dot-cli-startup-baseline.txt}"
+mkdir -p "$(dirname "$baseline_file")" 2>/dev/null || true
+printf '%s\n' "$median" >"$baseline_file"
+
+if ((median > BUDGET_MS)); then
+  echo "::error::dot CLI cold-start regression: median ${median}ms > budget ${BUDGET_MS}ms" >&2
+  echo "  Possible causes: a slow source-time helper in dot_local/bin/executable_dot," >&2
+  echo "  an unconditional ${BUDGET_MS}ms+ tool init at top of a sourced lib, or" >&2
+  echo "  unnecessary jq/awk calls before the dispatcher case statement." >&2
+  exit 1
+fi
+
+echo "✓ dot CLI cold-start within budget"

package/scripts/ci/install-chezmoi-verified.sh

@@ -26,7 +26,10 @@ case "$ARCH" in
   x86_64 | amd64) ARCH="amd64" ;;
   arm64 | aarch64) ARCH="arm64" ;;
   *)
-    echo "Unsupported architecture: $ARCH" >&2
+    # chezmoi ships amd64 + arm64 builds only. Other architectures
+    # (ppc64le, s390x, riscv64, armv7) would need a source build.
+    echo "Unsupported architecture: $ARCH (only x86_64/amd64 and arm64/aarch64 are supported)" >&2
+    echo "See https://github.com/twpayne/chezmoi/releases for the full asset list." >&2
     exit 1
     ;;
 esac

package/scripts/ci/lint-reusable-pins.sh

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+# Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+# shellcheck disable=SC2155
+#
+# lint-reusable-pins.sh — fail if any workflow references a reusable
+# workflow via a mutable ref (relative path, branch name, tag).
+#
+# Closes the lint-rule half of #855. Acceptable form for a reusable
+# workflow reference:
+#
+#     uses: sebastienrousseau/dotfiles/.github/workflows/reusable-X.yml@<40-hex-sha>
+#
+# Rejected forms:
+#
+#     uses: ./.github/workflows/reusable-X.yml                  # relative path → mutable
+#     uses: org/repo/.github/workflows/reusable-X.yml@master    # branch ref → mutable
+#     uses: org/repo/.github/workflows/reusable-X.yml@v1        # tag ref → mutable
+#
+# The full-SHA constraint is what prevents a TOCTOU swap where a
+# malicious push to the reusable's branch redirects the calling
+# workflow at run time.
+
+set -euo pipefail
+
+REPO_ROOT="${REPO_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+cd "$REPO_ROOT"
+
+WORKFLOWS_DIR=".github/workflows"
+fail_count=0
+checked_count=0
+
+if [[ ! -d "$WORKFLOWS_DIR" ]]; then
+  echo "::error::workflows directory not found at $WORKFLOWS_DIR"
+  exit 1
+fi
+
+# Walk every .yml under .github/workflows/ and inspect each `uses:`
+# line whose target ends with `reusable-*.yml`.
+while IFS= read -r workflow; do
+  while IFS=: read -r line_no _; do
+    line=$(sed -n "${line_no}p" "$workflow")
+    # Extract the ref expression after `uses:`.
+    # Acceptable: <owner>/<repo>/.github/workflows/reusable-X.yml@<40-hex>
+    if echo "$line" | grep -qE '^\s*uses:\s*\./'; then
+      echo "::error file=$workflow,line=$line_no::reusable workflow referenced by relative path (mutable). Pin to <owner>/<repo>/.github/workflows/<file>@<40-hex-sha>."
+      echo "    $line"
+      fail_count=$((fail_count + 1))
+      continue
+    fi
+    if echo "$line" | grep -qE 'reusable-[a-z0-9-]+\.yml@[0-9a-f]{40}\b'; then
+      checked_count=$((checked_count + 1))
+      continue
+    fi
+    if echo "$line" | grep -qE 'reusable-[a-z0-9-]+\.yml@'; then
+      ref=$(echo "$line" | sed -E 's|.*reusable-[a-z0-9-]+\.yml@([^ #]+).*|\1|')
+      echo "::error file=$workflow,line=$line_no::reusable workflow pinned to mutable ref '$ref'. Pin to a 40-hex commit SHA instead."
+      echo "    $line"
+      fail_count=$((fail_count + 1))
+      continue
+    fi
+  done < <(grep -nE 'reusable-[a-z0-9-]+\.yml' "$workflow" || true)
+done < <(find "$WORKFLOWS_DIR" -maxdepth 1 -type f -name '*.yml')
+
+echo "reusable-pin lint: checked $checked_count call site(s), $fail_count failure(s)"
+
+if [[ "$fail_count" -gt 0 ]]; then
+  echo ""
+  echo "Refresh pinned SHAs with:"
+  echo "  git fetch origin master"
+  echo "  PIN=\$(git rev-parse origin/master)"
+  echo "  # Apply per call site, then verify:"
+  echo "  bash scripts/ci/lint-reusable-pins.sh"
+  echo ""
+  echo "Policy: docs/security/CI_PINNING.md"
+  exit 1
+fi
+
+exit 0