@jenga-ai/agent 1.2.3 → 1.3.0

package/skills/publish/scripts/npm_stage_pipeline.sh

@@ -0,0 +1,427 @@
+#!/usr/bin/env bash
+# npm_stage_pipeline.sh — `/publish stage publish`: submit a version to npm's
+# staged-publishing area, gated by the mandatory build/test pre-deploy gates.
+#
+# Six ordered phases — the order is the point, since gates that ran after
+# staging would be verifying nothing:
+#   1. validate — validate_npm_stage_env.sh (T01); abort on non-zero
+#   2. gates    — run_gates.sh pre <target> <config> [--non-interactive]
+#                 (build/test are mandatory, global, non-disableable)
+#   3. pack     — resolve <name>@<version>, confirm unless --non-interactive
+#   4. stage    — for `npm` targets: `npm stage publish --tag ... --access
+#                 ... [--otp ...]` run locally. For `npm-ci` targets,
+#                 `--provenance` needs a GitHub Actions OIDC token that only
+#                 exists inside an Actions run, so this phase instead
+#                 dispatches the `stage` job of the target's generated
+#                 workflow (see npm_ci_pipeline.sh) via `gh workflow run
+#                 ... -f mode=stage` and waits on it with `gh run watch`.
+#   5. capture  — parse the stage id, falling back to `npm stage list --json`
+#   6. ledger   — write_ledger_entry.sh ... staged ... --stage-id <id> --dist-tag <tag>
+#
+# Usage:
+#   npm_stage_pipeline.sh <target> <path-to-publish.json> [--dry-run] [--non-interactive] [--otp <otp>]
+#
+# Exit codes:
+#   0  success (staged, or --dry-run completed cleanly)
+#   1  user declined the pack confirmation prompt (or no tty was available)
+#   2  a mandatory pre-deploy gate failed; nothing was staged
+#   3  staging failed (locally for `npm`, or the dispatched GitHub Actions
+#      run for `npm-ci`), or the stage id could not be captured
+#   4  validation failed (validate_npm_stage_env.sh's own exit code, or bad
+#      args/config)
+#
+# Security note: --otp is placed into the exec argv passed directly to `npm`
+# and nowhere else — never interpolated into a printed or logged string. If
+# command tracing (`set -x`) is active when this script starts — inherited
+# via SHELLOPTS/BASH_ENV, or the caller ran `bash -x npm_stage_pipeline.sh
+# ... --otp <otp>` — and an --otp value is present in argv, tracing is
+# disabled before OTP is ever assigned to a variable and stays disabled for
+# the rest of the run (see the "OTP tracing guard" block below for why this
+# has to be the whole run, not just the npm invocation). The captured output
+# of the stage invocation is additionally scrubbed of the literal OTP value
+# defensively, before it is ever printed.
+
+set -euo pipefail
+
+EXIT_ABORTED=1
+EXIT_GATE_FAILURE=2
+EXIT_STAGE_FAILURE=3
+EXIT_ENV_INVALID=4
+
+DEFAULT_REGISTRY="https://registry.npmjs.org"
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+if REPO_ROOT="$(git -C "${SCRIPT_DIR}" rev-parse --show-toplevel 2>/dev/null)"; then
+  :
+else
+  REPO_ROOT="$(cd "${SCRIPT_DIR}/../../.." && pwd)"
+fi
+
+# shellcheck source=publish_common.sh
+source "${SCRIPT_DIR}/publish_common.sh"
+
+VALIDATE_SCRIPT="${SCRIPT_DIR}/validate_npm_stage_env.sh"
+RUN_GATES_SCRIPT="${SCRIPT_DIR}/run_gates.sh"
+WRITE_LEDGER_SCRIPT="${SCRIPT_DIR}/write_ledger_entry.sh"
+
+usage() {
+  cat <<'USAGE'
+Usage: npm_stage_pipeline.sh <target> <path-to-publish.json> [--dry-run] [--non-interactive] [--otp <otp>]
+
+Phases (in order): validate, gates, pack, stage, capture, ledger.
+USAGE
+}
+
+fail_usage() {
+  usage >&2
+  printf 'npm stage pipeline error: %s\n' "$1" >&2
+  exit "${EXIT_ENV_INVALID}"
+}
+
+log_info() {
+  printf '→ %s\n' "$1"
+}
+
+log_warn() {
+  printf '⚠ %s\n' "$1" >&2
+}
+
+# ---------------------------------------------------------------------------
+# OTP tracing guard — must run before argv is parsed, i.e. before OTP is
+# ever assigned to a variable. If the caller invoked this script with
+# command tracing already enabled (`set -x`, inherited via SHELLOPTS/
+# BASH_ENV, or `bash -x npm_stage_pipeline.sh ... --otp <otp>`) and an
+# --otp value is present anywhere in argv, tracing is disabled immediately
+# and stays disabled for the remainder of this run.
+#
+# A narrower window — e.g. suspending tracing only around the `npm stage
+# publish` call itself and restoring it afterward — is NOT sufficient:
+# bash's xtrace prints the *expanded* value of $OTP for every subsequent
+# line that so much as references the variable. A plain truthiness check
+# like `[[ -n "$OTP" ]]` is traced as `+ [[ -n 123456 ]]`, leaking the code
+# just as surely as printing it directly. The only reliable guard is to
+# suspend tracing before the first assignment and never re-enable it for
+# the rest of the run.
+# ---------------------------------------------------------------------------
+OTP_PRESENT_IN_ARGV=0
+for _arg in "$@"; do
+  case "${_arg}" in
+    --otp|--otp=*)
+      OTP_PRESENT_IN_ARGV=1
+      ;;
+  esac
+done
+unset _arg
+if (( OTP_PRESENT_IN_ARGV )); then
+  case "$-" in
+    *x*) set +x ;;
+  esac
+fi
+
+# ---------------------------------------------------------------------------
+# Arg parsing
+# ---------------------------------------------------------------------------
+DRY_RUN=0
+NON_INTERACTIVE=0
+OTP=""
+
+POSITIONAL=()
+while (( $# )); do
+  case "$1" in
+    --dry-run)
+      DRY_RUN=1
+      shift
+      ;;
+    --non-interactive)
+      NON_INTERACTIVE=1
+      shift
+      ;;
+    --otp)
+      [[ $# -ge 2 ]] || fail_usage "--otp requires a value"
+      OTP="$2"
+      shift 2
+      ;;
+    --otp=*)
+      OTP="${1#*=}"
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    --)
+      shift
+      while (( $# )); do
+        POSITIONAL+=("$1")
+        shift
+      done
+      ;;
+    -*)
+      fail_usage "unknown option: $1"
+      ;;
+    *)
+      POSITIONAL+=("$1")
+      shift
+      ;;
+  esac
+done
+
+[[ ${#POSITIONAL[@]} -ge 1 ]] || fail_usage "<target> is required"
+TARGET_NAME="${POSITIONAL[0]}"
+[[ ${#POSITIONAL[@]} -ge 2 ]] || fail_usage "<path-to-publish.json> is required"
+CONFIG_PATH_ARG="${POSITIONAL[1]}"
+[[ ${#POSITIONAL[@]} -le 2 ]] || fail_usage "unexpected extra positional arguments"
+
+command -v jq >/dev/null 2>&1 || fail_usage "jq is required but not found on PATH"
+command -v npm >/dev/null 2>&1 || fail_usage "npm is required but not found on PATH"
+
+CONFIG_PATH="$(publish_normalize_path "${CONFIG_PATH_ARG}")"
+[[ -f "${CONFIG_PATH}" ]] || fail_usage "publish config not found at '${CONFIG_PATH}'"
+
+# ---------------------------------------------------------------------------
+# Phase 1: validate
+# ---------------------------------------------------------------------------
+log_info "[validate] checking staging environment for target '${TARGET_NAME}'..."
+
+VALIDATE_STATUS=0
+bash "${VALIDATE_SCRIPT}" "${TARGET_NAME}" "${CONFIG_PATH}" || VALIDATE_STATUS=$?
+if [[ ${VALIDATE_STATUS} -ne 0 ]]; then
+  printf 'npm stage pipeline: environment validation failed (exit %s); nothing staged.\n' "${VALIDATE_STATUS}" >&2
+  exit "${VALIDATE_STATUS}"
+fi
+
+# ---------------------------------------------------------------------------
+# Phase 2: gates — build/test are mandatory global pre-deploy gates for
+# npm/npm-ci targets (enforced inside run_gates.sh itself; not repeated or
+# re-implemented here) and cannot be disabled via target config.
+# ---------------------------------------------------------------------------
+log_info "[gates] running mandatory pre-deploy gates (build, test) for target '${TARGET_NAME}'..."
+
+GATES_CMD=(bash "${RUN_GATES_SCRIPT}" pre "${TARGET_NAME}" "${CONFIG_PATH}")
+(( NON_INTERACTIVE )) && GATES_CMD+=(--non-interactive)
+
+GATES_STATUS=0
+"${GATES_CMD[@]}" || GATES_STATUS=$?
+if [[ ${GATES_STATUS} -ne 0 ]]; then
+  printf 'npm stage pipeline: pre-deploy gates failed; nothing staged.\n' >&2
+  exit "${EXIT_GATE_FAILURE}"
+fi
+
+# ---------------------------------------------------------------------------
+# Phase 3: pack — resolve <name>@<version> and confirm
+# ---------------------------------------------------------------------------
+TARGET_JSON="$(jq -c --arg t "${TARGET_NAME}" '.targets[]? | select(.name == $t)' "${CONFIG_PATH}")"
+[[ -n "${TARGET_JSON}" ]] || fail_usage "target '${TARGET_NAME}' was not found in '${CONFIG_PATH}'"
+
+TARGET_TYPE="$(printf '%s' "${TARGET_JSON}" | jq -r '.type // empty')"
+if [[ "${TARGET_TYPE}" != "npm" && "${TARGET_TYPE}" != "npm-ci" ]]; then
+  fail_usage "target '${TARGET_NAME}' has type '${TARGET_TYPE}'; staging only supports 'npm' and 'npm-ci'"
+fi
+
+PACKAGE_NAME="$(printf '%s' "${TARGET_JSON}" | jq -r '.npm.package_name // empty')"
+[[ -n "${PACKAGE_NAME}" ]] || fail_usage "target '${TARGET_NAME}' is missing required field 'npm.package_name'"
+
+NPM_ACCESS="$(printf '%s' "${TARGET_JSON}" | jq -r '.npm.access // empty')"
+[[ -n "${NPM_ACCESS}" ]] || fail_usage "target '${TARGET_NAME}' is missing required field 'npm.access'"
+
+DIST_TAG="$(printf '%s' "${TARGET_JSON}" | jq -r '.npm.dist_tag // "latest"')"
+REGISTRY="$(printf '%s' "${TARGET_JSON}" | jq -r --arg d "${DEFAULT_REGISTRY}" '.npm.registry // $d')"
+
+PACKAGE_JSON="${REPO_ROOT}/package.json"
+[[ -f "${PACKAGE_JSON}" ]] || fail_usage "package.json not found at '${PACKAGE_JSON}'"
+
+PACKAGE_VERSION="$(jq -r '.version // empty' "${PACKAGE_JSON}")"
+[[ -n "${PACKAGE_VERSION}" ]] || fail_usage "package.json is missing a 'version' field"
+
+PACKAGE_SPEC="${PACKAGE_NAME}@${PACKAGE_VERSION}"
+
+echo "========== NPM STAGE PIPELINE =========="
+printf 'Target:   %s (%s)\n' "${TARGET_NAME}" "${TARGET_TYPE}"
+printf 'Package:  %s\n' "${PACKAGE_SPEC}"
+printf 'Dist tag: %s\n' "${DIST_TAG}"
+printf 'Access:   %s\n' "${NPM_ACCESS}"
+printf 'Registry: %s\n' "${REGISTRY}"
+printf 'Mode:     %s\n' "$( (( DRY_RUN )) && echo 'dry-run' || echo 'live stage' )"
+echo "=========================================="
+
+if (( NON_INTERACTIVE == 0 )); then
+  PACK_CONFIRM_FD=""
+  if [[ -t 0 ]] && exec 3</dev/tty 2>/dev/null; then
+    PACK_CONFIRM_FD=3
+  fi
+
+  if [[ -z "${PACK_CONFIRM_FD}" ]]; then
+    log_warn "no interactive tty available for pack confirmation; treating as declined. Pass --non-interactive to bypass."
+    PACK_RESPONSE=""
+  else
+    printf 'Stage %s to target "%s"? [y/N] ' "${PACKAGE_SPEC}" "${TARGET_NAME}" >&2
+    if ! IFS= read -r -u "${PACK_CONFIRM_FD}" PACK_RESPONSE; then
+      PACK_RESPONSE=""
+    fi
+    exec 3<&- 2>/dev/null || true
+  fi
+
+  case "${PACK_RESPONSE:-}" in
+    y|Y|yes|YES)
+      : ;;
+    *)
+      printf 'npm stage pipeline: pack confirmation declined; nothing staged.\n' >&2
+      exit "${EXIT_ABORTED}"
+      ;;
+  esac
+else
+  log_info "[pack] --non-interactive: skipping confirmation prompt for ${PACKAGE_SPEC}"
+fi
+
+# ---------------------------------------------------------------------------
+# Phase 4: stage
+#
+# `npm` targets stage locally via `npm stage publish`. `npm-ci` targets pass
+# `--provenance`, which requires a GitHub Actions OIDC token that only
+# exists inside an Actions run — there is no local equivalent — so instead
+# this dispatches the `stage` job of the target's generated workflow (the
+# same workflow file/OIDC Trusted Publisher link `npm_ci_pipeline.sh` uses
+# for `/publish deploy`) via `gh workflow run ... -f mode=stage` and waits
+# for it with `gh run watch`.
+# ---------------------------------------------------------------------------
+STAGE_OUTPUT=""
+STAGE_STATUS=0
+
+if [[ "${TARGET_TYPE}" == "npm-ci" ]]; then
+  command -v gh >/dev/null 2>&1 || fail_usage "'gh' CLI is required to stage an 'npm-ci' target (staging is dispatched as a GitHub Actions workflow run) but was not found on PATH"
+
+  GITHUB_REPO="$(printf '%s' "${TARGET_JSON}" | jq -r '.github_repo // empty')"
+  [[ -n "${GITHUB_REPO}" ]] || fail_usage "target '${TARGET_NAME}' is missing required field 'github_repo' (needed to dispatch the stage job)"
+
+  WORKFLOW_PATH="$(printf '%s' "${TARGET_JSON}" | jq -r '.workflow_path // ".github/workflows/npm-publish.yml"')"
+  WORKFLOW_FILENAME="$(basename "${WORKFLOW_PATH}")"
+
+  if (( DRY_RUN )); then
+    log_info "[dry-run] would dispatch: gh workflow run ${WORKFLOW_FILENAME} --repo ${GITHUB_REPO} -f mode=stage (tag=${DIST_TAG}, access=${NPM_ACCESS})"
+    log_info "[dry-run] no workflow run triggered; no ledger entry written, no registry-mutating call made."
+    exit 0
+  fi
+
+  log_info "[stage] dispatching 'stage' job of ${WORKFLOW_FILENAME} on ${GITHUB_REPO}..."
+  if ! gh workflow run "${WORKFLOW_FILENAME}" --repo "${GITHUB_REPO}" -f mode=stage; then
+    printf 'npm stage pipeline: gh workflow run failed; nothing staged.\n' >&2
+    exit "${EXIT_STAGE_FAILURE}"
+  fi
+
+  RUN_ID="$(gh run list --workflow "${WORKFLOW_FILENAME}" --repo "${GITHUB_REPO}" --limit 1 --json databaseId --jq '.[0].databaseId')"
+  [[ -n "${RUN_ID}" ]] || fail_usage "dispatched the stage workflow but could not resolve its run id via 'gh run list'"
+
+  log_info "[stage] waiting on run ${RUN_ID}..."
+  gh run watch "${RUN_ID}" --repo "${GITHUB_REPO}" --exit-status || STAGE_STATUS=$?
+
+  RUN_URL="$(gh run view "${RUN_ID}" --repo "${GITHUB_REPO}" --json url --jq '.url' 2>/dev/null || true)"
+  STAGE_OUTPUT="staged via GitHub Actions workflow run: ${RUN_URL}"
+else
+  STAGE_CMD_BASE=(npm stage publish --tag "${DIST_TAG}" --access "${NPM_ACCESS}")
+  [[ -n "${REGISTRY}" ]] && STAGE_CMD_BASE+=(--registry "${REGISTRY}")
+
+  DISPLAY_CMD=("${STAGE_CMD_BASE[@]}")
+  (( DRY_RUN )) && DISPLAY_CMD+=(--dry-run)
+  [[ -n "${OTP}" ]] && DISPLAY_CMD+=(--otp '********')
+
+  log_info "[stage] resolved command: $(printf '%q ' "${DISPLAY_CMD[@]}")"
+
+  EXEC_CMD=("${STAGE_CMD_BASE[@]}")
+  (( DRY_RUN )) && EXEC_CMD+=(--dry-run)
+  # Tracing was already suspended for the rest of this run (if it was
+  # active) by the "OTP tracing guard" above, the moment argv was found to
+  # contain --otp — before OTP was ever assigned to a variable. Nothing
+  # further to do here.
+  [[ -n "${OTP}" ]] && EXEC_CMD+=(--otp "${OTP}")
+
+  STAGE_OUTPUT="$(cd "${REPO_ROOT}" && "${EXEC_CMD[@]}" 2>&1)" || STAGE_STATUS=$?
+
+  # Defensive redaction: strip the literal OTP from captured output before
+  # it is ever printed, in case npm echoed the argv back in an error
+  # message. Quoting the pattern operand of ${var//pattern/repl} forces a
+  # literal (non-glob) match, so this is safe even if the OTP happens to
+  # contain characters that are special to bash's extglob pattern matching.
+  if [[ -n "${OTP}" ]]; then
+    STAGE_OUTPUT="${STAGE_OUTPUT//"${OTP}"/********}"
+  fi
+fi
+
+printf '%s\n' "${STAGE_OUTPUT}"
+
+if [[ ${STAGE_STATUS} -ne 0 ]]; then
+  printf 'npm stage pipeline: staging failed (exit %s); nothing staged.\n' "${STAGE_STATUS}" >&2
+  exit "${EXIT_STAGE_FAILURE}"
+fi
+
+if (( DRY_RUN )); then
+  log_info "[dry-run] npm stage publish --dry-run completed; no ledger entry written, no registry-mutating call made."
+  exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Phase 5: capture — parse the stage id
+# ---------------------------------------------------------------------------
+log_info "[capture] parsing stage id from stage output..."
+
+STAGE_ID=""
+
+# Attempt 1: direct-output parsing. Tolerant of label variants npm may use
+# ("stage id:", "stageId:", "stage_id="), case-insensitive.
+STAGE_ID="$(printf '%s\n' "${STAGE_OUTPUT}" \
+  | grep -Eio '\bstage[ _-]?id["'"'"']?[[:space:]]*[:=][[:space:]]*["'"'"']?[A-Za-z0-9._-]+' \
+  | head -n 1 \
+  | grep -Eo '[A-Za-z0-9._-]+$' || true)"
+
+# Attempt 2: the captured output is itself JSON (e.g. if npm's stage publish
+# supports --json the way `npm publish --json` does).
+if [[ -z "${STAGE_ID}" ]] && printf '%s' "${STAGE_OUTPUT}" | jq -e . >/dev/null 2>&1; then
+  STAGE_ID="$(printf '%s' "${STAGE_OUTPUT}" | jq -r '.id // .stageId // .stage_id // empty' 2>/dev/null || true)"
+fi
+
+# Attempt 3: fall back to `npm stage list <package>@<version> --json` and
+# extract the most recent matching entry's id.
+if [[ -z "${STAGE_ID}" ]]; then
+  log_warn "could not parse a stage id directly from stage output; falling back to 'npm stage list --json'..."
+
+  LIST_STATUS=0
+  LIST_OUTPUT="$(npm stage list "${PACKAGE_SPEC}" --json 2>&1)" || LIST_STATUS=$?
+
+  if [[ ${LIST_STATUS} -ne 0 ]]; then
+    printf '%s\n' "${LIST_OUTPUT}" >&2
+    printf 'npm stage pipeline: staged successfully but stage id capture failed (npm stage list also exited %s).\n' "${LIST_STATUS}" >&2
+    exit "${EXIT_STAGE_FAILURE}"
+  fi
+
+  if printf '%s' "${LIST_OUTPUT}" | jq -e . >/dev/null 2>&1; then
+    STAGE_ID="$(printf '%s' "${LIST_OUTPUT}" | jq -r --arg pkg "${PACKAGE_NAME}" --arg ver "${PACKAGE_VERSION}" '
+      ( if (type == "array") then . else (.stages? // .items? // []) end ) as $entries
+      | [ $entries[]? | select(((.name // .package // "") == $pkg) and ((.version // "") == $ver)) ]
+      | sort_by(.stagedAt // .staged_at // .created // .createdAt // "")
+      | last
+      | (.id // .stageId // .stage_id // empty)
+    ' 2>/dev/null || true)"
+  fi
+fi
+
+if [[ -z "${STAGE_ID}" ]]; then
+  printf 'npm stage pipeline: staged successfully but the stage id could not be captured from either the direct output or "npm stage list --json". Run "npm stage list %s --json" manually to recover it.\n' "${PACKAGE_SPEC}" >&2
+  exit "${EXIT_STAGE_FAILURE}"
+fi
+
+echo ""
+echo "=========================================="
+printf ' STAGE ID: %s\n' "${STAGE_ID}"
+echo "=========================================="
+echo ""
+
+# ---------------------------------------------------------------------------
+# Phase 6: ledger — record the staged entry
+# ---------------------------------------------------------------------------
+log_info "[ledger] recording 'staged' ledger entry for ${PACKAGE_SPEC}..."
+
+LEDGER_CMD=(bash "${WRITE_LEDGER_SCRIPT}" "${TARGET_NAME}" "${TARGET_TYPE}" staged "" \
+  --version "${PACKAGE_VERSION}" --config "${CONFIG_PATH}" --stage-id "${STAGE_ID}" --dist-tag "${DIST_TAG}")
+"${LEDGER_CMD[@]}"
+
+log_info "[done] ${PACKAGE_SPEC} staged as ${STAGE_ID} (dist-tag: ${DIST_TAG}). Awaiting 'npm_stage_inspect.sh test' and approval."

package/skills/publish/scripts/publish_common.sh

@@ -167,6 +167,22 @@ publish_history_has_version() {
   jq -e --arg version "$version" 'type == "array" and any(.[]?; (.version? // "") == $version)' "$history_file" >/dev/null 2>&1
 }
 
+# publish_history_has_passing_stage_test <history_file> <stage_id>
+#
+# True (exit 0) when the ledger contains at least one `stage_tested` entry
+# for the exact given stage id with result == "pass". Used by the
+# npm_stage_inspect.sh `approve` interlock. A missing/unreadable history
+# file is treated as "no passing test on record" (exit 1), not an error —
+# the caller decides how to report that.
+publish_history_has_passing_stage_test() {
+  local history_file="$1"
+  local stage_id="$2"
+  [[ -f "$history_file" ]] || return 1
+  jq -e --arg id "$stage_id" \
+    'type == "array" and any(.[]?; (.platform_state? // "") == "stage_tested" and (.stage_id? // "") == $id and (.result? // "") == "pass")' \
+    "$history_file" >/dev/null 2>&1
+}
+
 publish_resolve_last_publish_tag() {
   local history_file="$1"
   local ref="${2:-HEAD}"

package/skills/publish/scripts/show_history.sh

@@ -87,9 +87,16 @@ if (( JSON_OUTPUT )); then
   exit 0
 fi
 
-printf '%-10s %-20s %-20s %-10s %s\n' 'Version' 'Target' 'Date' 'State' 'Tag'
-printf '%-10s %-20s %-20s %-10s %s\n' '-------' '------' '----' '-----' '---'
-printf '%s\n' "$FILTERED_JSON" | jq -r '.[] | [(.version // "-"), (.target // "-"), (.timestamp // .completed_at // .started_at // "-"), (.platform_state // .state // "-"), (.git_tag // .version // "-")] | @tsv' | \
-while IFS=$'\t' read -r version target date state tag; do
-  printf '%-10s %-20s %-20s %-10s %s\n' "$version" "$target" "$date" "$state" "$tag"
+# Staged-publishing states (`staged`, `stage_tested`) are NOT published — a
+# version sitting there must never read as released. The State column
+# already carries a distinct value for each (vs. `uploaded` for a real
+# release), and the Stage ID column below makes a staged/tested/approved/
+# rejected row visibly distinct at a glance even without reading the State
+# column closely: only staged-publishing entries ever have a non-"-" stage
+# id.
+printf '%-10s %-20s %-20s %-14s %-24s %s\n' 'Version' 'Target' 'Date' 'State' 'Stage ID' 'Tag'
+printf '%-10s %-20s %-20s %-14s %-24s %s\n' '-------' '------' '----' '-----' '--------' '---'
+printf '%s\n' "$FILTERED_JSON" | jq -r '.[] | [(.version // "-"), (.target // "-"), (.timestamp // .completed_at // .started_at // "-"), (.platform_state // .state // "-"), (.stage_id // "-"), (.git_tag // .version // "-")] | @tsv' | \
+while IFS=$'\t' read -r version target date state stage_id tag; do
+  printf '%-10s %-20s %-20s %-14s %-24s %s\n' "$version" "$target" "$date" "$state" "$stage_id" "$tag"
 done

package/skills/publish/scripts/validate_npm_stage_env.sh

@@ -0,0 +1,184 @@
+#!/usr/bin/env bash
+# validate_npm_stage_env.sh — Preflight gate for `/publish stage`.
+#
+# npm's staged-publishing workflow (npm CLI >= 11.15.0, Node >= 22.14.0) only exists on
+# recent toolchains, only applies to `npm`/`npm-ci` targets, and only works for a package
+# that has already had at least one non-staged publish. This script checks all four
+# preconditions up front so the rest of the `/publish stage` pipeline never has to discover
+# one of them has failed midway through a staging attempt.
+#
+# Usage:
+#   validate_npm_stage_env.sh <target> <path-to-publish.json>
+#
+# Exit codes:
+#   0  all four preflight checks passed
+#   4  one of the checks failed (config/environment invalid), matching
+#      skills/publish/assets/ci-contract.md
+#
+# Security note: the registry probe (check 4) never prints npm's raw stdout/stderr. Only
+# messages composed by this script are emitted, so nothing npm writes — which could in
+# principle include auth-related registry response detail — reaches stdout, stderr, or any
+# log this script's caller might capture.
+
+set -u
+
+EXIT_ENV_INVALID=4
+
+NPM_MIN_VERSION="11.15.0"
+NODE_MIN_VERSION="22.14.0"
+DEFAULT_REGISTRY="https://registry.npmjs.org"
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# ---------------------------------------------------------------------------
+# Shared helpers (repo-root resolution, path normalization) — reused rather
+# than re-implemented, per the repo-root-then-project/configs/ convention
+# already established in publish_common.sh.
+# ---------------------------------------------------------------------------
+# shellcheck source=publish_common.sh
+source "${SCRIPT_DIR}/publish_common.sh"
+
+fail() {
+  printf 'stage env validation failed: %s\n' "$1" >&2
+  exit "${EXIT_ENV_INVALID}"
+}
+
+usage() {
+  cat <<'USAGE'
+Usage: validate_npm_stage_env.sh <target> <path-to-publish.json>
+USAGE
+}
+
+# ---------------------------------------------------------------------------
+# Semver comparison — component-wise numeric compare, boundary inclusive.
+# A naive string or float compare gets "11.9.0 < 11.15.0" backwards (float
+# compare would read 11.9 > 11.15); comparing each dotted component as a
+# base-10 integer gets it right regardless of leading zeros.
+# ---------------------------------------------------------------------------
+version_ge() {
+  local version="$1" min="$2"
+  local -a v_parts m_parts
+  IFS='.' read -r -a v_parts <<< "$version"
+  IFS='.' read -r -a m_parts <<< "$min"
+
+  local i v m
+  for i in 0 1 2; do
+    v="${v_parts[i]:-0}"
+    m="${m_parts[i]:-0}"
+    # Strip any non-digit suffix (pre-release/build metadata) so `10#` never
+    # trips over a stray character; default to 0 if nothing numeric remains.
+    v="${v//[!0-9]/}"
+    m="${m//[!0-9]/}"
+    v="${v:-0}"
+    m="${m:-0}"
+    if ((10#$v > 10#$m)); then
+      return 0
+    elif ((10#$v < 10#$m)); then
+      return 1
+    fi
+  done
+  return 0
+}
+
+# ---------------------------------------------------------------------------
+# Argument & dependency sanity checks
+# ---------------------------------------------------------------------------
+TARGET_NAME="${1:-}"
+CONFIG_PATH_ARG="${2:-}"
+
+if [[ -z "${TARGET_NAME}" ]]; then
+  usage >&2
+  fail "missing target name argument"
+fi
+
+command -v jq >/dev/null 2>&1 || fail "jq is required but not found on PATH"
+command -v npm >/dev/null 2>&1 || fail "'npm' was not found on PATH. Install Node.js (which provides npm) from https://nodejs.org/ or via your package manager, then re-run."
+command -v node >/dev/null 2>&1 || fail "'node' was not found on PATH. Install Node.js from https://nodejs.org/ or via your package manager, then re-run."
+
+# Resolve the config path: normalize a supplied relative/absolute path via
+# publish_common.sh, or fall back to the repo-root-then-project/configs/
+# search already used elsewhere in this skill.
+if [[ -n "${CONFIG_PATH_ARG}" ]]; then
+  CONFIG_PATH="$(publish_normalize_path "${CONFIG_PATH_ARG}")"
+elif [[ -f "${PUBLISH_REPO_ROOT}/publish.json" ]]; then
+  CONFIG_PATH="${PUBLISH_REPO_ROOT}/publish.json"
+elif [[ -f "${PUBLISH_DEFAULT_CONFIG_FILE}" ]]; then
+  CONFIG_PATH="${PUBLISH_DEFAULT_CONFIG_FILE}"
+else
+  usage >&2
+  fail "missing publish.json path argument, and no default config found at '${PUBLISH_REPO_ROOT}/publish.json' or '${PUBLISH_DEFAULT_CONFIG_FILE}'"
+fi
+
+[[ -f "${CONFIG_PATH}" ]] || fail "publish config not found at '${CONFIG_PATH}'"
+jq -e . "${CONFIG_PATH}" >/dev/null 2>&1 || fail "publish config at '${CONFIG_PATH}' is not valid JSON"
+
+# ---------------------------------------------------------------------------
+# Check 1 — npm CLI version >= 11.15.0
+# ---------------------------------------------------------------------------
+NPM_VERSION_RAW="$(npm --version 2>/dev/null)"
+NPM_VERSION="${NPM_VERSION_RAW#v}"
+if [[ -z "${NPM_VERSION}" ]]; then
+  fail "could not determine npm CLI version ('npm --version' produced no output)"
+fi
+if ! version_ge "${NPM_VERSION}" "${NPM_MIN_VERSION}"; then
+  fail "npm CLI version ${NPM_VERSION} is below the minimum required for staged publishing (${NPM_MIN_VERSION}). Upgrade with 'npm install -g npm@latest' (or any npm >= ${NPM_MIN_VERSION}) and re-run."
+fi
+
+# ---------------------------------------------------------------------------
+# Check 2 — Node version >= 22.14.0
+# ---------------------------------------------------------------------------
+NODE_VERSION_RAW="$(node --version 2>/dev/null)"
+NODE_VERSION="${NODE_VERSION_RAW#v}"
+if [[ -z "${NODE_VERSION}" ]]; then
+  fail "could not determine Node.js version ('node --version' produced no output)"
+fi
+if ! version_ge "${NODE_VERSION}" "${NODE_MIN_VERSION}"; then
+  fail "Node.js version ${NODE_VERSION} is below the minimum required for staged publishing (${NODE_MIN_VERSION}). Upgrade Node.js to ${NODE_MIN_VERSION} or newer (https://nodejs.org/) and re-run."
+fi
+
+# ---------------------------------------------------------------------------
+# Check 3 — target exists and its type is `npm` or `npm-ci`
+# ---------------------------------------------------------------------------
+TARGET_JSON="$(jq -c --arg t "${TARGET_NAME}" '.targets[]? | select(.name == $t)' "${CONFIG_PATH}")"
+if [[ -z "${TARGET_JSON}" ]]; then
+  fail "target '${TARGET_NAME}' was not found in '${CONFIG_PATH}'"
+fi
+
+TARGET_TYPE="$(printf '%s' "${TARGET_JSON}" | jq -r '.type // empty')"
+if [[ "${TARGET_TYPE}" != "npm" && "${TARGET_TYPE}" != "npm-ci" ]]; then
+  if [[ -z "${TARGET_TYPE}" ]]; then
+    fail "target '${TARGET_NAME}' is missing a type. Staging is only supported for target types 'npm' and 'npm-ci'."
+  fi
+  fail "target '${TARGET_NAME}' has type '${TARGET_TYPE}'. Staging is only supported for target types 'npm' and 'npm-ci' — use '/publish deploy' for other target types."
+fi
+
+# ---------------------------------------------------------------------------
+# Check 4 — the package already exists on the registry
+# ---------------------------------------------------------------------------
+PACKAGE_NAME="$(printf '%s' "${TARGET_JSON}" | jq -r '.npm.package_name // empty')"
+if [[ -z "${PACKAGE_NAME}" ]]; then
+  fail "target '${TARGET_NAME}' is missing required field 'npm.package_name'"
+fi
+
+REGISTRY="$(printf '%s' "${TARGET_JSON}" | jq -r --arg d "${DEFAULT_REGISTRY}" '.npm.registry // $d')"
+
+# Capture npm's output but never print it — it is not needed for the
+# messages below, and not printing it is a hard guarantee against ever
+# leaking anything npm's registry client writes (including, in principle,
+# auth-related response detail) into this script's own stdout/stderr.
+REGISTRY_PROBE_OUTPUT="$(npm view "${PACKAGE_NAME}" version --registry "${REGISTRY}" 2>&1)"
+REGISTRY_PROBE_EXIT=$?
+
+if [[ ${REGISTRY_PROBE_EXIT} -ne 0 ]]; then
+  if printf '%s' "${REGISTRY_PROBE_OUTPUT}" | grep -qi 'E404\|404 Not Found\|is not in this registry'; then
+    fail "package '${PACKAGE_NAME}' was not found on registry '${REGISTRY}' (404). npm cannot stage a package that has never been published — run '/publish deploy' for the first release; staging becomes available from the second release onward."
+  fi
+  fail "could not verify that package '${PACKAGE_NAME}' exists on registry '${REGISTRY}' (npm view exited ${REGISTRY_PROBE_EXIT}). Check network connectivity and registry configuration, then re-run."
+fi
+
+# ---------------------------------------------------------------------------
+# All checks passed
+# ---------------------------------------------------------------------------
+printf '[validate] stage environment OK — npm %s, node %s, target "%s" (%s), package "%s" resolves on %s\n' \
+  "${NPM_VERSION}" "${NODE_VERSION}" "${TARGET_NAME}" "${TARGET_TYPE}" "${PACKAGE_NAME}" "${REGISTRY}"
+exit 0