@biffo/cli 0.177.1 → 0.177.2

package/_skeletons/plugin-template/.github/workflows/ci.yml

@@ -148,4 +148,14 @@ jobs:
         with:
           enable-cache: true
       - run: uv sync --all-groups
-      - run: uv run pip-audit
+      # Fails on a real advisory, but treats an unreachable PyPI/OSV as
+      # INCONCLUSIVE rather than reddening a required check for an
+      # infrastructure hiccup (#591, #743). The raw `uv run pip-audit` this
+      # replaces exits non-zero identically whether it found a vulnerability or
+      # simply could not reach the advisory database.
+      #
+      # The script is byte-identical to biffo-template's copy and to every other
+      # satellite's, distributed by that repo's shared-sync.sh. Do not edit it
+      # here; edit it upstream.
+      - name: Dependency audit
+        run: sh scripts/py-dependency-audit.sh

package/_skeletons/plugin-template/scripts/js-dependency-audit.sh

@@ -0,0 +1,133 @@
+#!/bin/sh
+#
+# JS dependency audit that fails the build on a real high/critical advisory but
+# NOT on a broken audit registry (#591).
+#
+# `pnpm audit --audit-level=high` exits non-zero identically whether it found a
+# vulnerability OR simply couldn't parse the registry's response — and the npm
+# audit endpoint intermittently returns a non-JSON/gzip body pnpm chokes on
+# ("Unexpected token, is not valid JSON"), which then fails the required JS check
+# on every open PR at once, blocking the whole merge queue for an infrastructure
+# hiccup that has nothing to do with the PR.
+#
+# `pnpm audit --json` disambiguates: a real run yields `.metadata.vulnerabilities`
+# (counts by severity); a registry/parse failure yields `.error`. So we fail only
+# on a genuine high+critical finding, retry a transient registry error a few
+# times, and treat a persistent one as INCONCLUSIVE (warn, don't block) rather
+# than as a vulnerability. "Couldn't run the check" and "the check found a
+# problem" must not be the same signal on a required gate.
+#
+# ## Skeleton lockfiles are audited too (#644)
+#
+# `_skeletons/**/` are scaffolding trees: `biffo sibling create` / `plugin
+# create` copy them verbatim into a brand-new repo. They sit OUTSIDE the pnpm
+# workspace, so `pnpm install` never installs them and a workspace-scoped audit
+# never sees them — which meant every sibling scaffolded from this template was
+# born with four high-severity advisories nobody could see. Dependabot found
+# them; the required JS gate could not, by construction.
+#
+# That is the fail-open shape this file already exists to fight, one level up:
+# the gate was green because it was not looking, and "we checked and it is
+# clean" read identically to "we never checked".
+#
+# ## This file is distributed verbatim (#743)
+#
+# Both skeletons and every existing sibling/plugin repo hold a BYTE-IDENTICAL
+# copy, listed in `shared-files.json` and pushed by `scripts/shared-sync.sh`.
+# Until then the hardening above lived in this repo only, while both skeletons
+# shipped the raw `pnpm audit --audit-level=high` that #591 was filed about — so
+# every satellite was born with the original defect and reddened its required JS
+# check on any registry hiccup.
+#
+# It therefore takes its target from the CURRENT WORKING DIRECTORY — the CI
+# job's `working-directory` — rather than assuming a repo layout: `.` is the
+# root workspace here, `apps/frontend` in a sibling, and the `_skeletons/**`
+# sweep below simply finds nothing outside this repo. Keep it layout-agnostic,
+# or the copies stop being interchangeable and `shared-sync.sh --check` starts
+# reporting drift that is really divergence.
+#
+# POSIX sh (the CI step runs `sh scripts/...`, i.e. dash) — no `pipefail`.
+set -u
+
+# jq is the parser this whole distinction rests on. Without it EVERY response
+# reads as unparseable, so the script reports INCONCLUSIVE on every invocation
+# and the gate goes green while scanning nothing — the exact fail-open shape it
+# exists to prevent, and precisely what the dash `echo` defect did until #717. A
+# missing jq is a deterministic environment defect, not a transient registry
+# hiccup, so it fails loudly instead of degrading into a permanent pass.
+if ! command -v jq >/dev/null 2>&1; then
+  echo "::error::jq is not installed on this runner. The dependency audit cannot tell a clean run from an unparseable one without it, and would report INCONCLUSIVE forever — a gate that is green because it never ran. Install jq."
+  exit 1
+fi
+
+attempts=3
+inconclusive=0
+failed=0
+
+# Audit one directory. Returns 0 if clean or inconclusive, 1 on a real finding.
+# `$1` is the directory, `$2` a human label, `$3` extra pnpm flags.
+audit_dir() {
+  dir="$1"
+  label="$2"
+  extra="$3"
+
+  for attempt in $(seq 1 "$attempts"); do
+    # printf, never echo: the CI step runs `sh scripts/...` i.e. dash, whose
+    # `echo` interprets backslash escapes. Advisory payloads contain them, so
+    # `echo "$out" | jq` mangles the JSON and jq rejects it — the run then reads
+    # as "the registry returned junk" and reports INCONCLUSIVE. That is this
+    # gate failing open inside the very fix that exists to stop it failing open
+    # (#591): green, every time, while scanning nothing.
+    #
+    # The flag differs by tree, and both directions matter:
+    #   - skeletons need --ignore-workspace, or pnpm walks up, finds this repo's
+    #     workspace root and audits THAT instead — reporting a clean result for
+    #     a tree it never looked at, which is the failure this step closes.
+    #   - the workspace must NOT have it, or pnpm has no project to audit and
+    #     every run reports INCONCLUSIVE. That fails open: the gate goes green
+    #     forever while scanning nothing. (Caught by running this script before
+    #     trusting it — the workspace audit had silently stopped working.)
+    # shellcheck disable=SC2086
+    out="$(cd "$dir" 2>/dev/null && pnpm audit --json $extra 2>/dev/null)"
+
+    if printf '%s' "$out" | jq -e '.metadata.vulnerabilities' >/dev/null 2>&1; then
+      high="$(printf '%s' "$out" | jq '.metadata.vulnerabilities.high // 0')"
+      crit="$(printf '%s' "$out" | jq '.metadata.vulnerabilities.critical // 0')"
+      if [ "$((high + crit))" -gt 0 ]; then
+        echo "::error::${label}: ${crit} critical + ${high} high advisory(ies)."
+        printf '%s' "$out" | jq '.advisories // .metadata.vulnerabilities' 2>/dev/null | head -c 4000
+        return 1
+      fi
+      echo "${label}: no high/critical advisories."
+      return 0
+    fi
+
+    msg="$(printf '%s' "$out" | jq -r '.error.message // "no parseable audit output"' 2>/dev/null | head -c 200)"
+    echo "${label}: attempt ${attempt}/${attempts} could not run: ${msg}"
+    [ "$attempt" -lt "$attempts" ] && sleep "$((attempt * 3))"
+  done
+
+  echo "::warning::${label}: audit could not run after ${attempts} attempts (the registry returned a non-JSON/error response); treating as INCONCLUSIVE and not blocking. Advisory scanning was NOT performed for this tree — see #591."
+  inconclusive=$((inconclusive + 1))
+  return 0
+}
+
+# The workspace itself.
+audit_dir "." "pnpm audit (workspace)" "" || failed=1
+
+# Every scaffolding tree with its own lockfile. Discovered rather than listed,
+# so a new skeleton is covered the day it lands instead of the day someone
+# remembers to add it here.
+for lock in $(find _skeletons -name pnpm-lock.yaml -not -path '*/node_modules/*' 2>/dev/null | sort); do
+  audit_dir "$(dirname "$lock")" "pnpm audit ($(dirname "$lock"))" "--ignore-workspace" || failed=1
+done
+
+if [ "$failed" -ne 0 ]; then
+  exit 1
+fi
+
+if [ "$inconclusive" -ne 0 ]; then
+  echo "${inconclusive} tree(s) could not be audited; see warnings above."
+fi
+
+exit 0

package/_skeletons/plugin-template/scripts/py-dependency-audit.sh

@@ -0,0 +1,145 @@
+#!/bin/sh
+#
+# Python dependency audit that fails the build on a real advisory but NOT on a
+# broken registry/network response (#591) — same class of flake as the JS
+# dependency audit (scripts/js-dependency-audit.sh), applied preventively here
+# since pip-audit queries PyPI/OSV over the network per dependency and is
+# subject to the same kind of transient hiccup.
+#
+# `pip-audit -f json` emits a `{"dependencies": [{"name", "version", "vulns"},
+# ...]}` shape on a real run; a network/parse failure produces no parseable
+# JSON at all (traceback on stderr, non-zero exit, empty/partial stdout). So we
+# fail only when the parsed output actually contains a vulnerability, retry a
+# few times on an unparseable run, and treat a persistent failure as
+# INCONCLUSIVE (warn, don't block) rather than as a vulnerability.
+# "Couldn't run the check" and "the check found a problem" must not be the same
+# signal on a required gate.
+#
+# ## Skeleton lockfiles are audited too (#719)
+#
+# `_skeletons/**/` are scaffolding trees: `biffo sibling create` / `plugin
+# create` copy them verbatim into a brand-new repo. They are NOT part of this
+# repo's uv project, so `uv sync` never installs them and a workspace-scoped
+# `uv run pip-audit` never saw them — which meant the Python half of every
+# scaffolded sibling came from a lockfile no CI gate had ever looked at.
+#
+# #644 closed exactly this hole for the JS skeleton lockfile, where it had
+# already cost four unseen high-severity advisories; this is the same hole one
+# language over. It is the fail-open shape this file already exists to fight,
+# one level up: the gate was green because it was not looking, and "we checked
+# and it is clean" read identically to "we never checked".
+#
+# Unlike `pnpm audit --ignore-workspace`, pip-audit cannot simply be run inside
+# a skeleton directory: the skeleton is not an installed environment, and
+# pip-audit's default mode audits an environment. So we export `--frozen`
+# requirements from the skeleton's own lockfile (a read of the committed lock,
+# no re-resolution) and audit those with `-r`, from the workspace, which is
+# where pip-audit is actually installed.
+#
+# ## This file is distributed verbatim (#743)
+#
+# Both skeletons and every existing sibling/plugin repo hold a BYTE-IDENTICAL
+# copy, listed in `shared-files.json` and pushed by `scripts/shared-sync.sh`.
+# Until then the hardening above lived in this repo only, while both skeletons
+# shipped a raw `uv run pip-audit` — so every satellite was born with the
+# original defect and reddened a required check on any PyPI/OSV hiccup.
+#
+# It therefore takes its target from the CURRENT WORKING DIRECTORY — the CI
+# job's `working-directory` — rather than assuming a repo layout: `.` is the
+# root project here and in a plugin repo, `services/api` in a sibling, and the
+# `_skeletons/**` sweep below simply finds nothing outside this repo. Keep it
+# layout-agnostic, or the copies stop being interchangeable and
+# `shared-sync.sh --check` starts reporting drift that is really divergence.
+#
+# POSIX sh (the CI step runs `sh scripts/...`, i.e. dash) — no `pipefail`.
+set -u
+
+# jq is the parser this whole distinction rests on. Without it EVERY response
+# reads as unparseable, so the script reports INCONCLUSIVE on every invocation
+# and the gate goes green while scanning nothing — the exact fail-open shape it
+# exists to prevent, and precisely what the dash `echo` defect did until #717. A
+# missing jq is a deterministic environment defect, not a transient network
+# hiccup, so it fails loudly instead of degrading into a permanent pass.
+if ! command -v jq >/dev/null 2>&1; then
+  echo "::error::jq is not installed on this runner. The dependency audit cannot tell a clean run from an unparseable one without it, and would report INCONCLUSIVE forever — a gate that is green because it never ran. Install jq."
+  exit 1
+fi
+
+attempts=3
+inconclusive=0
+failed=0
+
+# Audit one dependency set. Returns 0 if clean or inconclusive, 1 on a real
+# finding. `$1` is a human label, `$2` the extra pip-audit flags that select
+# what to audit — empty for this workspace's installed environment, or
+# `-r <file>` for a requirements file exported from a skeleton lockfile.
+audit_deps() {
+  label="$1"
+  extra="$2"
+
+  for attempt in $(seq 1 "$attempts"); do
+    # shellcheck disable=SC2086
+    out="$(uv run pip-audit -f json $extra 2>/dev/null)"
+
+    # printf, never echo: the CI step runs `sh scripts/...` i.e. dash, whose
+    # `echo` interprets backslash escapes. Advisory payloads contain them, so
+    # `echo "$out" | jq` mangles the JSON and jq rejects it — the run then reads
+    # as "the registry returned junk" and reports INCONCLUSIVE. That is this
+    # gate failing open inside the very fix that exists to stop it failing open
+    # (#591): green, every time, while scanning nothing. #644 found the JS gate
+    # had been doing exactly that on every run.
+    if printf '%s' "$out" | jq -e '.dependencies' >/dev/null 2>&1; then
+      vuln_count="$(printf '%s' "$out" | jq '[.dependencies[].vulns[]?] | length')"
+      if [ "$vuln_count" -gt 0 ]; then
+        echo "::error::${label}: ${vuln_count} vulnerability(ies)."
+        printf '%s' "$out" | jq '[.dependencies[] | select(.vulns | length > 0)]' 2>/dev/null | head -c 4000
+        return 1
+      fi
+      echo "${label}: no vulnerabilities found."
+      return 0
+    fi
+
+    echo "${label}: attempt ${attempt}/${attempts} produced no parseable JSON output."
+    [ "$attempt" -lt "$attempts" ] && sleep "$((attempt * 3))"
+  done
+
+  echo "::warning::${label}: could not produce parseable output after ${attempts} attempts (a transient network/registry error); treating as INCONCLUSIVE and not blocking. Advisory scanning was NOT performed for this tree — see #591."
+  inconclusive=$((inconclusive + 1))
+  return 0
+}
+
+# The workspace itself.
+audit_deps "pip-audit (workspace)" "" || failed=1
+
+# Every scaffolding tree with its own lockfile. Discovered rather than listed,
+# so a new skeleton is covered the day it lands instead of the day someone
+# remembers to add it here.
+for lock in $(find _skeletons -name uv.lock -not -path '*/node_modules/*' 2>/dev/null | sort); do
+  dir="$(dirname "$lock")"
+  reqs="$(mktemp)"
+
+  # `--frozen` reads the committed lock verbatim instead of re-resolving, so
+  # what gets audited is exactly what a scaffolded sibling would be born with.
+  # `--no-emit-project` drops the skeleton package itself (nothing published to
+  # audit); `--no-dev` keeps the audit to what actually ships.
+  if (cd "$dir" && uv export --frozen --no-dev --no-emit-project) >"$reqs" 2>/dev/null && [ -s "$reqs" ]; then
+    audit_deps "pip-audit (${dir})" "-r $reqs" || failed=1
+  else
+    # An export failure is "couldn't run", not "clean" — same discipline as a
+    # transient pip-audit error, and it must never read as a pass.
+    echo "::warning::pip-audit (${dir}): could not export requirements from ${lock}; treating as INCONCLUSIVE and not blocking. Advisory scanning was NOT performed for this tree — see #719."
+    inconclusive=$((inconclusive + 1))
+  fi
+
+  rm -f "$reqs"
+done
+
+if [ "$failed" -ne 0 ]; then
+  exit 1
+fi
+
+if [ "$inconclusive" -ne 0 ]; then
+  echo "${inconclusive} tree(s) could not be audited; see warnings above."
+fi
+
+exit 0

package/_skeletons/sibling-template/.github/workflows/ci.yml

@@ -82,7 +82,19 @@ jobs:
         run: pnpm run build
       - name: Dependency audit
         if: ${{ !cancelled() }}
-        run: pnpm audit --audit-level=high
+        # Fails on a real high/critical advisory, but treats a broken audit
+        # registry as INCONCLUSIVE rather than reddening a required check for an
+        # infrastructure hiccup (#591, #743). The raw `pnpm audit
+        # --audit-level=high` this replaces exits non-zero identically whether it
+        # found a vulnerability or simply could not parse the registry's
+        # response, so any npm blip failed this job on every open PR at once.
+        #
+        # The relative path is deliberate. This job's working-directory is
+        # apps/frontend, which is exactly the tree to audit, and the script
+        # audits its own cwd — it is byte-identical to biffo-template's copy and
+        # to every other satellite's, distributed by that repo's shared-sync.sh,
+        # so it cannot assume a layout. Do not edit it here; edit it upstream.
+        run: sh ../../scripts/js-dependency-audit.sh
 
   python:
     name: Python (lint, types, test, security)
@@ -124,7 +136,11 @@ jobs:
           path: services/api/bandit-report.json
       - name: Dependency audit
         if: ${{ !cancelled() }}
-        run: uv run pip-audit
+        # Same treatment as the JS job's Dependency audit above: fails on a real
+        # advisory, INCONCLUSIVE on an unreachable PyPI/OSV (#591, #743). cwd is
+        # services/api, which is the environment `uv sync` installed and so the
+        # one to audit.
+        run: sh ../../scripts/py-dependency-audit.sh
 
   security-secrets:
     name: Secret Scan

package/_skeletons/sibling-template/scripts/js-dependency-audit.sh

@@ -0,0 +1,133 @@
+#!/bin/sh
+#
+# JS dependency audit that fails the build on a real high/critical advisory but
+# NOT on a broken audit registry (#591).
+#
+# `pnpm audit --audit-level=high` exits non-zero identically whether it found a
+# vulnerability OR simply couldn't parse the registry's response — and the npm
+# audit endpoint intermittently returns a non-JSON/gzip body pnpm chokes on
+# ("Unexpected token, is not valid JSON"), which then fails the required JS check
+# on every open PR at once, blocking the whole merge queue for an infrastructure
+# hiccup that has nothing to do with the PR.
+#
+# `pnpm audit --json` disambiguates: a real run yields `.metadata.vulnerabilities`
+# (counts by severity); a registry/parse failure yields `.error`. So we fail only
+# on a genuine high+critical finding, retry a transient registry error a few
+# times, and treat a persistent one as INCONCLUSIVE (warn, don't block) rather
+# than as a vulnerability. "Couldn't run the check" and "the check found a
+# problem" must not be the same signal on a required gate.
+#
+# ## Skeleton lockfiles are audited too (#644)
+#
+# `_skeletons/**/` are scaffolding trees: `biffo sibling create` / `plugin
+# create` copy them verbatim into a brand-new repo. They sit OUTSIDE the pnpm
+# workspace, so `pnpm install` never installs them and a workspace-scoped audit
+# never sees them — which meant every sibling scaffolded from this template was
+# born with four high-severity advisories nobody could see. Dependabot found
+# them; the required JS gate could not, by construction.
+#
+# That is the fail-open shape this file already exists to fight, one level up:
+# the gate was green because it was not looking, and "we checked and it is
+# clean" read identically to "we never checked".
+#
+# ## This file is distributed verbatim (#743)
+#
+# Both skeletons and every existing sibling/plugin repo hold a BYTE-IDENTICAL
+# copy, listed in `shared-files.json` and pushed by `scripts/shared-sync.sh`.
+# Until then the hardening above lived in this repo only, while both skeletons
+# shipped the raw `pnpm audit --audit-level=high` that #591 was filed about — so
+# every satellite was born with the original defect and reddened its required JS
+# check on any registry hiccup.
+#
+# It therefore takes its target from the CURRENT WORKING DIRECTORY — the CI
+# job's `working-directory` — rather than assuming a repo layout: `.` is the
+# root workspace here, `apps/frontend` in a sibling, and the `_skeletons/**`
+# sweep below simply finds nothing outside this repo. Keep it layout-agnostic,
+# or the copies stop being interchangeable and `shared-sync.sh --check` starts
+# reporting drift that is really divergence.
+#
+# POSIX sh (the CI step runs `sh scripts/...`, i.e. dash) — no `pipefail`.
+set -u
+
+# jq is the parser this whole distinction rests on. Without it EVERY response
+# reads as unparseable, so the script reports INCONCLUSIVE on every invocation
+# and the gate goes green while scanning nothing — the exact fail-open shape it
+# exists to prevent, and precisely what the dash `echo` defect did until #717. A
+# missing jq is a deterministic environment defect, not a transient registry
+# hiccup, so it fails loudly instead of degrading into a permanent pass.
+if ! command -v jq >/dev/null 2>&1; then
+  echo "::error::jq is not installed on this runner. The dependency audit cannot tell a clean run from an unparseable one without it, and would report INCONCLUSIVE forever — a gate that is green because it never ran. Install jq."
+  exit 1
+fi
+
+attempts=3
+inconclusive=0
+failed=0
+
+# Audit one directory. Returns 0 if clean or inconclusive, 1 on a real finding.
+# `$1` is the directory, `$2` a human label, `$3` extra pnpm flags.
+audit_dir() {
+  dir="$1"
+  label="$2"
+  extra="$3"
+
+  for attempt in $(seq 1 "$attempts"); do
+    # printf, never echo: the CI step runs `sh scripts/...` i.e. dash, whose
+    # `echo` interprets backslash escapes. Advisory payloads contain them, so
+    # `echo "$out" | jq` mangles the JSON and jq rejects it — the run then reads
+    # as "the registry returned junk" and reports INCONCLUSIVE. That is this
+    # gate failing open inside the very fix that exists to stop it failing open
+    # (#591): green, every time, while scanning nothing.
+    #
+    # The flag differs by tree, and both directions matter:
+    #   - skeletons need --ignore-workspace, or pnpm walks up, finds this repo's
+    #     workspace root and audits THAT instead — reporting a clean result for
+    #     a tree it never looked at, which is the failure this step closes.
+    #   - the workspace must NOT have it, or pnpm has no project to audit and
+    #     every run reports INCONCLUSIVE. That fails open: the gate goes green
+    #     forever while scanning nothing. (Caught by running this script before
+    #     trusting it — the workspace audit had silently stopped working.)
+    # shellcheck disable=SC2086
+    out="$(cd "$dir" 2>/dev/null && pnpm audit --json $extra 2>/dev/null)"
+
+    if printf '%s' "$out" | jq -e '.metadata.vulnerabilities' >/dev/null 2>&1; then
+      high="$(printf '%s' "$out" | jq '.metadata.vulnerabilities.high // 0')"
+      crit="$(printf '%s' "$out" | jq '.metadata.vulnerabilities.critical // 0')"
+      if [ "$((high + crit))" -gt 0 ]; then
+        echo "::error::${label}: ${crit} critical + ${high} high advisory(ies)."
+        printf '%s' "$out" | jq '.advisories // .metadata.vulnerabilities' 2>/dev/null | head -c 4000
+        return 1
+      fi
+      echo "${label}: no high/critical advisories."
+      return 0
+    fi
+
+    msg="$(printf '%s' "$out" | jq -r '.error.message // "no parseable audit output"' 2>/dev/null | head -c 200)"
+    echo "${label}: attempt ${attempt}/${attempts} could not run: ${msg}"
+    [ "$attempt" -lt "$attempts" ] && sleep "$((attempt * 3))"
+  done
+
+  echo "::warning::${label}: audit could not run after ${attempts} attempts (the registry returned a non-JSON/error response); treating as INCONCLUSIVE and not blocking. Advisory scanning was NOT performed for this tree — see #591."
+  inconclusive=$((inconclusive + 1))
+  return 0
+}
+
+# The workspace itself.
+audit_dir "." "pnpm audit (workspace)" "" || failed=1
+
+# Every scaffolding tree with its own lockfile. Discovered rather than listed,
+# so a new skeleton is covered the day it lands instead of the day someone
+# remembers to add it here.
+for lock in $(find _skeletons -name pnpm-lock.yaml -not -path '*/node_modules/*' 2>/dev/null | sort); do
+  audit_dir "$(dirname "$lock")" "pnpm audit ($(dirname "$lock"))" "--ignore-workspace" || failed=1
+done
+
+if [ "$failed" -ne 0 ]; then
+  exit 1
+fi
+
+if [ "$inconclusive" -ne 0 ]; then
+  echo "${inconclusive} tree(s) could not be audited; see warnings above."
+fi
+
+exit 0

package/_skeletons/sibling-template/scripts/py-dependency-audit.sh

@@ -0,0 +1,145 @@
+#!/bin/sh
+#
+# Python dependency audit that fails the build on a real advisory but NOT on a
+# broken registry/network response (#591) — same class of flake as the JS
+# dependency audit (scripts/js-dependency-audit.sh), applied preventively here
+# since pip-audit queries PyPI/OSV over the network per dependency and is
+# subject to the same kind of transient hiccup.
+#
+# `pip-audit -f json` emits a `{"dependencies": [{"name", "version", "vulns"},
+# ...]}` shape on a real run; a network/parse failure produces no parseable
+# JSON at all (traceback on stderr, non-zero exit, empty/partial stdout). So we
+# fail only when the parsed output actually contains a vulnerability, retry a
+# few times on an unparseable run, and treat a persistent failure as
+# INCONCLUSIVE (warn, don't block) rather than as a vulnerability.
+# "Couldn't run the check" and "the check found a problem" must not be the same
+# signal on a required gate.
+#
+# ## Skeleton lockfiles are audited too (#719)
+#
+# `_skeletons/**/` are scaffolding trees: `biffo sibling create` / `plugin
+# create` copy them verbatim into a brand-new repo. They are NOT part of this
+# repo's uv project, so `uv sync` never installs them and a workspace-scoped
+# `uv run pip-audit` never saw them — which meant the Python half of every
+# scaffolded sibling came from a lockfile no CI gate had ever looked at.
+#
+# #644 closed exactly this hole for the JS skeleton lockfile, where it had
+# already cost four unseen high-severity advisories; this is the same hole one
+# language over. It is the fail-open shape this file already exists to fight,
+# one level up: the gate was green because it was not looking, and "we checked
+# and it is clean" read identically to "we never checked".
+#
+# Unlike `pnpm audit --ignore-workspace`, pip-audit cannot simply be run inside
+# a skeleton directory: the skeleton is not an installed environment, and
+# pip-audit's default mode audits an environment. So we export `--frozen`
+# requirements from the skeleton's own lockfile (a read of the committed lock,
+# no re-resolution) and audit those with `-r`, from the workspace, which is
+# where pip-audit is actually installed.
+#
+# ## This file is distributed verbatim (#743)
+#
+# Both skeletons and every existing sibling/plugin repo hold a BYTE-IDENTICAL
+# copy, listed in `shared-files.json` and pushed by `scripts/shared-sync.sh`.
+# Until then the hardening above lived in this repo only, while both skeletons
+# shipped a raw `uv run pip-audit` — so every satellite was born with the
+# original defect and reddened a required check on any PyPI/OSV hiccup.
+#
+# It therefore takes its target from the CURRENT WORKING DIRECTORY — the CI
+# job's `working-directory` — rather than assuming a repo layout: `.` is the
+# root project here and in a plugin repo, `services/api` in a sibling, and the
+# `_skeletons/**` sweep below simply finds nothing outside this repo. Keep it
+# layout-agnostic, or the copies stop being interchangeable and
+# `shared-sync.sh --check` starts reporting drift that is really divergence.
+#
+# POSIX sh (the CI step runs `sh scripts/...`, i.e. dash) — no `pipefail`.
+set -u
+
+# jq is the parser this whole distinction rests on. Without it EVERY response
+# reads as unparseable, so the script reports INCONCLUSIVE on every invocation
+# and the gate goes green while scanning nothing — the exact fail-open shape it
+# exists to prevent, and precisely what the dash `echo` defect did until #717. A
+# missing jq is a deterministic environment defect, not a transient network
+# hiccup, so it fails loudly instead of degrading into a permanent pass.
+if ! command -v jq >/dev/null 2>&1; then
+  echo "::error::jq is not installed on this runner. The dependency audit cannot tell a clean run from an unparseable one without it, and would report INCONCLUSIVE forever — a gate that is green because it never ran. Install jq."
+  exit 1
+fi
+
+attempts=3
+inconclusive=0
+failed=0
+
+# Audit one dependency set. Returns 0 if clean or inconclusive, 1 on a real
+# finding. `$1` is a human label, `$2` the extra pip-audit flags that select
+# what to audit — empty for this workspace's installed environment, or
+# `-r <file>` for a requirements file exported from a skeleton lockfile.
+audit_deps() {
+  label="$1"
+  extra="$2"
+
+  for attempt in $(seq 1 "$attempts"); do
+    # shellcheck disable=SC2086
+    out="$(uv run pip-audit -f json $extra 2>/dev/null)"
+
+    # printf, never echo: the CI step runs `sh scripts/...` i.e. dash, whose
+    # `echo` interprets backslash escapes. Advisory payloads contain them, so
+    # `echo "$out" | jq` mangles the JSON and jq rejects it — the run then reads
+    # as "the registry returned junk" and reports INCONCLUSIVE. That is this
+    # gate failing open inside the very fix that exists to stop it failing open
+    # (#591): green, every time, while scanning nothing. #644 found the JS gate
+    # had been doing exactly that on every run.
+    if printf '%s' "$out" | jq -e '.dependencies' >/dev/null 2>&1; then
+      vuln_count="$(printf '%s' "$out" | jq '[.dependencies[].vulns[]?] | length')"
+      if [ "$vuln_count" -gt 0 ]; then
+        echo "::error::${label}: ${vuln_count} vulnerability(ies)."
+        printf '%s' "$out" | jq '[.dependencies[] | select(.vulns | length > 0)]' 2>/dev/null | head -c 4000
+        return 1
+      fi
+      echo "${label}: no vulnerabilities found."
+      return 0
+    fi
+
+    echo "${label}: attempt ${attempt}/${attempts} produced no parseable JSON output."
+    [ "$attempt" -lt "$attempts" ] && sleep "$((attempt * 3))"
+  done
+
+  echo "::warning::${label}: could not produce parseable output after ${attempts} attempts (a transient network/registry error); treating as INCONCLUSIVE and not blocking. Advisory scanning was NOT performed for this tree — see #591."
+  inconclusive=$((inconclusive + 1))
+  return 0
+}
+
+# The workspace itself.
+audit_deps "pip-audit (workspace)" "" || failed=1
+
+# Every scaffolding tree with its own lockfile. Discovered rather than listed,
+# so a new skeleton is covered the day it lands instead of the day someone
+# remembers to add it here.
+for lock in $(find _skeletons -name uv.lock -not -path '*/node_modules/*' 2>/dev/null | sort); do
+  dir="$(dirname "$lock")"
+  reqs="$(mktemp)"
+
+  # `--frozen` reads the committed lock verbatim instead of re-resolving, so
+  # what gets audited is exactly what a scaffolded sibling would be born with.
+  # `--no-emit-project` drops the skeleton package itself (nothing published to
+  # audit); `--no-dev` keeps the audit to what actually ships.
+  if (cd "$dir" && uv export --frozen --no-dev --no-emit-project) >"$reqs" 2>/dev/null && [ -s "$reqs" ]; then
+    audit_deps "pip-audit (${dir})" "-r $reqs" || failed=1
+  else
+    # An export failure is "couldn't run", not "clean" — same discipline as a
+    # transient pip-audit error, and it must never read as a pass.
+    echo "::warning::pip-audit (${dir}): could not export requirements from ${lock}; treating as INCONCLUSIVE and not blocking. Advisory scanning was NOT performed for this tree — see #719."
+    inconclusive=$((inconclusive + 1))
+  fi
+
+  rm -f "$reqs"
+done
+
+if [ "$failed" -ne 0 ]; then
+  exit 1
+fi
+
+if [ "$inconclusive" -ne 0 ]; then
+  echo "${inconclusive} tree(s) could not be audited; see warnings above."
+fi
+
+exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@biffo/cli",
-  "version": "0.177.1",
+  "version": "0.177.2",
   "description": "Biffo project scaffolding CLI",
   "license": "MIT",
   "type": "module",