feat(exec): wire real npm publish (dry-run) through secrets-engine exec

scripts/npm-publish-demo.sh boots a throwaway OpenBao, applies + provisions the
whynot-design lane, and runs `npm publish --dry-run` via `secrets-engine exec`
against a scratch package. npm resolves its auth token from the injected temp
.npmrc and builds/announces the tarball; the parent shell never holds the token
and the temp config is cleaned up. Documented in docs/cli.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/cli.md

@@ -59,6 +59,19 @@ Boots a throwaway in-memory OpenBao dev server and runs the whole pilot chain:
 plan → apply → provision → verify(+/-) → exec (npm-config injection) → route →
 revoke. Nothing is persisted; the token is a throwaway local string.
 
+## npm publish wiring (dry-run)
+
+```bash
+bash scripts/npm-publish-demo.sh
+```
+
+Boots a throwaway OpenBao, applies + provisions the lane with a *fake* token, and
+runs a **real `npm publish --dry-run`** through `secrets-engine exec` against a
+scratch package. Proves npm in the child resolves its auth token from the temp
+`.npmrc` secrets-engine injected, builds the tarball, and reaches the publish
+step — while the parent shell never holds the token. For a real publish,
+provision a real npm automation token the same way and drop `--dry-run`.
+
 ## Pilot: whynot-design npm publish
 
 ```bash

scripts/npm-publish-demo.sh

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+# Wire up a REAL `npm publish` through secrets-engine exec — in dry-run, so the
+# tarball is built and the publish path is exercised end to end WITHOUT actually
+# uploading to the registry.
+#
+# Chain: boot throwaway OpenBao -> apply lane -> provision a (fake) token ->
+#        `secrets-engine exec --catalog ... -- npm publish --dry-run`.
+#
+# Proves: npm in the child resolves its auth token from the temp .npmrc that
+# secrets-engine injected; the parent shell never holds the token.
+set -euo pipefail
+
+REPO="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$REPO"
+# shellcheck disable=SC1091
+source .venv/bin/activate
+
+BAO_BIN="$(command -v bao)"
+WORK="$(mktemp -d)"
+export BAO_ADDR="http://127.0.0.1:8271"
+export BAO_TOKEN="se-npm-demo-root"
+export SECRETS_ENGINE_HUB_URL=""          # offline; uses local decision fixture
+TOKENFILE="$WORK/whynot.token"
+PKG="$WORK/pkg"
+
+cleanup() {
+  set +e
+  [[ -n "${BAO_PID:-}" ]] && kill "$BAO_PID" 2>/dev/null
+  rm -rf "$WORK"
+}
+trap cleanup EXIT
+
+echo "### boot throwaway OpenBao"
+"$BAO_BIN" server -dev -dev-root-token-id="$BAO_TOKEN" \
+  -dev-listen-address="127.0.0.1:8271" >"$WORK/bao.log" 2>&1 &
+BAO_PID=$!
+for _ in $(seq 1 30); do
+  "$BAO_BIN" status -address="$BAO_ADDR" >/dev/null 2>&1 && break; sleep 0.2
+done
+
+echo "### apply lane metadata + provision a (fake) npm token"
+secrets-engine apply whynot-design-npm-publish --stage prod >/dev/null
+printf 'npm_FAKEtokenFORdryRUNonly1234567890' > "$TOKENFILE"
+chmod 600 "$TOKENFILE"
+secrets-engine provision whynot-design-npm-publish --stage prod \
+  --field npm_token --from-file "$TOKENFILE" >/dev/null
+echo "    lane ready: $(secrets-engine route whynot-design-npm-publish --json | python3 -c 'import sys,json;print("ready="+str(json.load(sys.stdin)["ready"]))')"
+
+echo "### create a scratch npm package"
+mkdir -p "$PKG"
+cat > "$PKG/package.json" <<'EOF'
+{
+  "name": "@whynot-design/se-pilot-scratch",
+  "version": "0.0.1",
+  "description": "Scratch package proving secrets-engine exec -> npm publish wiring (dry-run).",
+  "license": "MIT",
+  "publishConfig": { "access": "public" }
+}
+EOF
+echo 'module.exports = () => "secrets-engine pilot";' > "$PKG/index.js"
+
+echo "### run npm publish --dry-run THROUGH secrets-engine exec"
+echo "    (token injected into the npm child via a temp .npmrc; parent never sees it)"
+cd "$PKG"
+# A small wrapper proves the child resolved the auth token, then runs the real
+# npm publish --dry-run. The token value itself is never printed.
+cat > "$WORK/npm-wrapped.sh" <<'EOF'
+#!/usr/bin/env bash
+set -e
+# secrets-engine pointed npm at a temp userconfig holding the auth token.
+# (npm itself hides _authToken from `npm config get`, so check the file npm uses.)
+if [[ -n "${NPM_CONFIG_USERCONFIG:-}" ]] && grep -q '_authToken' "$NPM_CONFIG_USERCONFIG"; then
+  echo "    [child] npm userconfig injected with an auth token: yes (value hidden)"
+  echo "    [child] config file: $NPM_CONFIG_USERCONFIG"
+else
+  echo "    [child] npm has NO injected auth token"; exit 1
+fi
+exec npm publish --dry-run
+EOF
+chmod +x "$WORK/npm-wrapped.sh"
+secrets-engine exec --catalog whynot-design-npm-publish -- "$WORK/npm-wrapped.sh"
+
+echo
+echo "### confirm parent shell never held the token"
+echo "    SE_NPM_TOKEN in parent: '${SE_NPM_TOKEN:-<unset>}'"
+echo "    NPM_CONFIG_USERCONFIG in parent: '${NPM_CONFIG_USERCONFIG:-<unset>}'"
+echo
+echo "### DONE — npm publish (dry-run) ran with the token injected by secrets-engine."
+echo "    For a REAL publish, provision a real npm automation token the same way"
+echo "    and drop --dry-run from the wrapped command."