forgedock 1.27.0 → 1.29.0

package/scripts/test-map.sh

@@ -0,0 +1,211 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# test-map.sh — deterministic `file glob → check command` map for a repo (forge#4272). No LLM, no network, runs none of
+# the repo's commands: git + jq + awk only (no yq). Codebase-agnostic: node, python, go, make and CI workflow steps.
+#
+# Usage: test-map.sh [--repo-path DIR] [--output FILE | --stdout]
+#   default output <repo>/.forge/test-map.json, rewritten on every run (a regenerable cache; deleting it restores the
+#   pre-PR step's `learned.test_commands` behaviour).
+# Output: {"version":1,"entries":[{"globs":[...],"command","cwd","source"}]}, sorted by source then command; entries
+#   with the same (command, cwd) are merged (globs unioned, first source kept).
+# Sources:
+#   package.json (root + every tracked one outside node_modules): scripts test/lint/typecheck/type-check/check →
+#     `<pm> run <script>` in the package dir (pm from the root lockfile), JS/TS globs under that dir
+#   pytest (pyproject [tool.pytest*], pytest.ini, setup.cfg [tool:pytest], conftest.py) and ruff config → `pytest`,
+#     `ruff check .` (through `uv run` / `poetry run` when that lockfile exists), `**/*.py`
+#   go.mod (dir D) → `go test ./...`, `go vet ./...` in D, `D/**/*.go`, `D/go.mod`, `D/go.sum`
+#   Makefile / GNUmakefile targets test/lint/check/typecheck/vet → `make <target>`, `**`
+#   .github/workflows/*.yml|*.yaml `run:` steps (one command per line of a `|` block, a `>` block is one command;
+#     install/setup lines skipped): globs
+#     from the tool (python/go/shell/js), else the workflow's `paths:` filter, else `**`. A step whose job id, job
+#     name, step name or command matches deploy/publish/release/push/secret is never mapped (forge#4297): the engine
+#     runs these commands before a PR, so only check steps belong here.
+# Exit: 0 ok | 2 usage or bad repo path. bash 3.2 portable.
+set -uo pipefail
+
+die() { echo "test-map: $*" >&2; exit 2; }
+command -v jq >/dev/null 2>&1 || die "jq is required"
+REPO="."; OUT=""; STDOUT=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --repo-path) [ $# -ge 2 ] && [ -n "$2" ] || die "usage: test-map.sh [--repo-path DIR] [--output FILE | --stdout]"; REPO="$2"; shift 2 ;;
+    --output) [ $# -ge 2 ] && [ -n "$2" ] || die "usage: test-map.sh [--repo-path DIR] [--output FILE | --stdout]"; OUT="$2"; shift 2 ;;
+    --stdout) STDOUT=1; shift ;;
+    *) die "unknown option: $1" ;;
+  esac
+done
+[ -d "$REPO" ] || die "repo path not found: $REPO"
+case "$OUT" in ""|/*) ;; *) OUT="$PWD/$OUT" ;; esac
+cd "$REPO" || die "cannot enter $REPO"
+
+T=$(mktemp -d "${TMPDIR:-/tmp}/test-map.XXXXXX") || die "mktemp failed"
+trap 'rm -rf "$T"' EXIT
+if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  # -z and quotepath=off (#4298): non-ASCII and spaced paths come out verbatim, never C-quoted
+  git -c core.quotepath=off ls-files -z --cached --others --exclude-standard | tr '\0' '\n' > "$T/files"
+else
+  find . -type f -not -path './.git/*' | sed 's|^\./||' | sort > "$T/files"
+fi
+: > "$T/rows"
+# row: source TAB cwd TAB command TAB globs separated by US (\037, #4298: a glob may contain spaces)
+US="$(printf '\037')"
+row() { printf '%s\t%s\t%s\t%s\n' "$1" "$2" "$3" "$4" >> "$T/rows"; }
+JS_EXT="js jsx ts tsx mjs cjs"
+# globs for the extensions in $2 under dir $1 ("." = repo root)
+ext_globs() {
+  g=""; pre=""; [ "$1" = "." ] || pre="$1/"
+  for e in $2; do g="$g$US${pre}**/*.$e"; done
+  printf '%s' "${g#"$US"}"
+}
+
+# ---- package.json scripts ----
+PM=npm
+[ -f yarn.lock ] && PM=yarn
+[ -f pnpm-lock.yaml ] && PM=pnpm
+grep -E '(^|/)package\.json$' "$T/files" | grep -v -E '(^|/)node_modules/' | sort | while IFS= read -r pj; do
+  [ -f "$pj" ] || continue
+  d=$(dirname "$pj")
+  globs="$(ext_globs "$d" "$JS_EXT")$US$pj"
+  tag=""
+  if [ -n "$(ls "$d"/vitest.config.* "$d"/jest.config.* 2>/dev/null)" ] || jq -e 'has("jest")' "$pj" >/dev/null 2>&1; then tag=" (vitest/jest config)"; fi
+  jq -r '(.scripts // {}) | to_entries[] | select(.value | type == "string") | .key' "$pj" 2>/dev/null | while IFS= read -r s; do
+    case "$s" in
+      test) row "$pj#scripts.$s$tag" "$d" "$PM run $s" "$globs" ;;
+      lint|typecheck|type-check|check) row "$pj#scripts.$s" "$d" "$PM run $s" "$globs" ;;
+    esac
+  done
+done
+
+# ---- python ----
+RUN=""
+[ -f poetry.lock ] && RUN="poetry run "
+[ -f uv.lock ] && RUN="uv run "
+PY_SRC=""
+if [ -f pyproject.toml ] && grep -qE '^\[tool\.pytest' pyproject.toml; then PY_SRC="pyproject.toml#tool.pytest"
+elif [ -f pytest.ini ]; then PY_SRC="pytest.ini"
+elif [ -f setup.cfg ] && grep -qE '^\[tool:pytest\]' setup.cfg; then PY_SRC="setup.cfg#tool:pytest"
+elif grep -qE '(^|/)conftest\.py$' "$T/files"; then PY_SRC="conftest.py"; fi
+[ -n "$PY_SRC" ] && row "$PY_SRC" "." "${RUN}pytest" "**/*.py$US**/conftest.py"
+RUFF_SRC=""
+if [ -f pyproject.toml ] && grep -qE '^\[tool\.ruff' pyproject.toml; then RUFF_SRC="pyproject.toml#tool.ruff"
+elif [ -f ruff.toml ]; then RUFF_SRC="ruff.toml"
+elif [ -f .ruff.toml ]; then RUFF_SRC=".ruff.toml"; fi
+[ -n "$RUFF_SRC" ] && row "$RUFF_SRC" "." "${RUN}ruff check ." "**/*.py"
+
+# ---- go ----
+grep -E '(^|/)go\.mod$' "$T/files" | grep -v -E '(^|/)vendor/' | sort | while IFS= read -r gm; do
+  d=$(dirname "$gm"); pre=""; [ "$d" = "." ] || pre="$d/"
+  globs="${pre}**/*.go$US${pre}go.mod$US${pre}go.sum"
+  row "$gm" "$d" "go test ./..." "$globs"
+  row "$gm" "$d" "go vet ./..." "$globs"
+done
+
+# ---- Makefile ----
+for mf in Makefile GNUmakefile; do
+  [ -f "$mf" ] || continue
+  grep -oE '^(test|lint|check|typecheck|vet)[[:space:]]*:' "$mf" | sed -E 's/[[:space:]]*:$//' | sort -u | while IFS= read -r t; do
+    row "$mf#$t" "." "make $t" "**"
+  done
+done
+
+# ---- CI workflow run: steps ----
+# Emits: job US jobname US stepname US command (US = \037, so empty names survive `read`), one per command line; and P TAB path for each `paths:` filter item
+# before `jobs:`. A block ends at the first non-blank line not indented past the `run` key (sibling keys such as env:).
+wf_extract() {
+  awk '
+    function indent(s) { match(s, /^ */); return RLENGTH }
+    function unq(s) { sub(/^[ \t]+/, "", s); sub(/[ \t]+$/, "", s); if (s ~ /^".*"$/ || s ~ /^\x27.*\x27$/) s = substr(s, 2, length(s) - 2); return s }
+    function emit(c) { c = unq(c); if (c != "") print job "\037" jname "\037" sname "\037" c }
+    BEGIN { injobs = 0; jind = -1; block = 0; inpaths = 0; job = ""; jname = ""; sname = "" }
+    {
+      line = $0; sub(/\r$/, "", line)
+      if (block) {
+        if (line ~ /^[ \t]*$/) next
+        if (indent(line) > bind) {
+          l = line; sub(/^ +/, "", l)
+          if (fold) { pend = (pend == "" ? l : pend " " l); next }
+          if (pend != "") { l = pend " " l; pend = "" }
+          if (l ~ /\\$/) { pend = substr(l, 1, length(l) - 1); sub(/[ \t]+$/, "", pend); next }
+          emit(l); next
+        }
+        if (pend != "") { emit(pend); pend = "" }
+        block = 0
+      }
+      if (line ~ /^jobs:[ \t]*$/) { injobs = 1; inpaths = 0; next }
+      if (!injobs) {
+        if (line ~ /^[ \t]*paths:[ \t]*$/) { inpaths = 1; pind = indent(line); next }
+        if (inpaths) {
+          if (line ~ /^[ \t]*-[ \t]/ && indent(line) >= pind) { p = line; sub(/^[ \t]*-[ \t]*/, "", p); sub(/[ \t]+#.*$/, "", p); print "P\t" unq(p); next }
+          if (line !~ /^[ \t]*$/ && line !~ /^[ \t]*#/) inpaths = 0
+        }
+        next
+      }
+      if (line ~ /^[^ \t#]/) { injobs = 0; next }
+      if (line ~ /^ +[A-Za-z0-9_-]+:[ \t]*$/ && (jind < 0 || indent(line) == jind)) { jind = indent(line); job = line; sub(/^ +/, "", job); sub(/:.*$/, "", job); jname = ""; sname = ""; next }
+      if (line ~ /^[ \t]*-[ \t]/) sname = ""
+      if (line ~ /^[ \t]*(-[ \t]+)?name:/) {
+        nm = line; sub(/^[ \t]*(-[ \t]+)?name:[ \t]*/, "", nm); sub(/[ \t]+#.*$/, "", nm)
+        if (line !~ /^[ \t]*-[ \t]/ && indent(line) == jind + 2) jname = unq(nm); else sname = unq(nm)
+        next
+      }
+      if (line ~ /^[ \t]*(-[ \t]+)?run:/) {
+        rest = line; sub(/^[ \t]*(-[ \t]+)?run:[ \t]*/, "", rest); sub(/[ \t]+#.*$/, "", rest)
+        # bind = the column of the `run` key: step keys after it (env:, shell:) sit there and end the block
+        if (rest ~ /^[|>][-+0-9]*$/) { block = 1; pend = ""; fold = (rest ~ /^>/); bind = match(line, /run:/) - 1; next }
+        emit(rest)
+      }
+    }
+    END { if (block && pend != "") emit(pend) }
+  ' "$1"
+}
+skip_cmd() {
+  case "$1" in
+    \#*|echo\ *|echo|cd\ *|export\ *|set\ *|if\ *|then|fi|else|for\ *|do|done|\}*|\{*|*'$GITHUB_'*|*'>> $GITHUB'*) return 0 ;;
+    npm\ ci*|npm\ install*|npm\ i|npm\ i\ *|pnpm\ install*|pnpm\ i|yarn|yarn\ install*|pip\ install*|pip3\ install*|python*\ -m\ pip\ install*|uv\ sync*|uv\ pip\ install*|poetry\ install*|go\ mod\ download*|apt-get*|sudo\ *|corepack\ *|brew\ *) return 0 ;;
+  esac
+  return 1
+}
+# forge#4297: deploy, publish, release, push and secret-using steps are never check commands
+deploy_step() {
+  grep -qiE 'deploy|publish|release|push|secret' <<<"$*"
+}
+tool_globs() {
+  c=" $1 "
+  case "$c" in
+    *[\ /]ruff\ *|*[\ /]flake8\ *|*[\ /]pylint\ *|*[\ /]mypy\ *|*[\ /]black\ *|*[\ /]pytest\ *) printf '**/*.py'; return ;;
+    *[\ /]golangci-lint\ *|*[\ /]gofmt\ *|*[\ /]staticcheck\ *|*\ go\ *) printf '**/*.go'; return ;;
+    *[\ /]shellcheck\ *|*\ bash\ *.sh\ *|*\ sh\ *.sh\ *) printf '**/*.sh'; return ;;
+    *[\ /]eslint\ *|*[\ /]tsc\ *|*[\ /]prettier\ *|*[\ /]vitest\ *|*[\ /]jest\ *|*\ node\ --test*|*\ npm\ *|*\ pnpm\ *|*\ yarn\ *|*\ npx\ *) ext_globs . "$JS_EXT"; return ;;
+  esac
+  printf ''
+}
+grep -E '^\.github/workflows/[^/]+\.(yml|yaml)$' "$T/files" | sort | while IFS= read -r wf; do
+  [ -f "$wf" ] || continue
+  wf_extract "$wf" > "$T/wf"
+  paths=$(awk -F'\t' '$1 == "P" { printf "%s\037", $2 }' "$T/wf"); paths=${paths%"$US"}
+  awk -F'\t' '$1 != "P"' "$T/wf" | while IFS="$(printf '\037')" read -r job jname sname cmd; do
+    skip_cmd "$cmd" && continue
+    deploy_step "$job" "$jname" "$sname" "$cmd" && continue
+    g=$(tool_globs "$cmd")
+    [ -n "$g" ] || g="$paths"
+    [ -n "$g" ] || g="**"
+    row "$wf#jobs.$job" "." "$cmd" "$g"
+  done
+done
+
+MAP=$(jq -R -s -c '
+  [split("\n")[] | select(length > 0) | split("\t") | {source: .[0], cwd: .[1], command: .[2], globs: (.[3] | split("\u001f") | map(select(length > 0)))}]
+  | sort_by(.source, .command)
+  | reduce .[] as $e ({order: [], by: {}};
+      ([$e.command, $e.cwd] | tojson) as $k
+      | if .by[$k] then .by[$k].globs += ($e.globs - .by[$k].globs)
+        else .order += [$k] | .by[$k] = {globs: $e.globs, command: $e.command, cwd: $e.cwd, source: $e.source} end)
+  | {version: 1, entries: [.by[.order[]]]}' < "$T/rows") || die "jq failed"
+
+if [ "$STDOUT" = 1 ]; then printf '%s\n' "$MAP"; exit 0; fi
+[ -n "$OUT" ] || OUT=".forge/test-map.json"
+mkdir -p "$(dirname "$OUT")" || die "cannot create $(dirname "$OUT")"
+printf '%s\n' "$MAP" > "$OUT.tmp.$$" && mv "$OUT.tmp.$$" "$OUT" || die "cannot write $OUT"
+echo "$OUT"

package/scripts/test-map.test.sh

@@ -0,0 +1,165 @@
+#!/usr/bin/env bash
+# test-map.test.sh — cases for scripts/test-map.sh over the node, python and go fixtures (forge#4272).
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+set -uo pipefail
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+S="$HERE/test-map.sh"
+SEL="$HERE/../bin/lean/testmap.mjs"
+FIX="$HERE/fixtures/test-map"
+PASS=0; FAILN=0
+TMP="$(mktemp -d "${TMPDIR:-/tmp}/test-map-test.XXXXXX")"; trap 'rm -rf "$TMP"' EXIT
+ok() { PASS=$((PASS+1)); }
+bad() { FAILN=$((FAILN+1)); echo "FAIL: $1"; }
+eq() { if [ "$2" = "$3" ]; then ok; else bad "$1 (got: $2 want: $3)"; fi }
+
+# copy a fixture into a fresh git repo and build its map
+setup() {
+  rm -rf "$TMP/$1"; cp -R "$FIX/$1" "$TMP/$1"; cd "$TMP/$1" || exit 1
+  git init -q -b main; git config user.email t@example.com; git config user.name t; git config commit.gpgsign false
+  git add -A; git commit -qm init
+  OUTP="$(bash "$S")"; RC=$?
+}
+# selected commands for changed files, sorted, joined by |
+sel() { node "$SEL" --map .forge/test-map.json --select "$@" | LC_ALL=C sort | paste -sd'|' -; }
+
+# ---- 1. node: root scripts for root files, workspace scripts for package files ----
+setup node
+eq "node rc" "$RC" 0
+eq "node output path" "$OUTP" ".forge/test-map.json"
+eq "schema" "$(jq -c '[.version, (.entries | length > 0), (.entries | all(has("globs") and has("command") and has("cwd") and has("source")))]' .forge/test-map.json)" '[1,true,true]'
+eq "non-check script ignored" "$(jq '[.entries[] | select(.command | test("build"))] | length' .forge/test-map.json)" 0
+eq "root file" "$(sel src/a.ts)" "pnpm run lint|pnpm run test"
+eq "package file" "$(sel packages/ui/src/button.tsx)" "cd packages/ui && pnpm run test|cd packages/ui && pnpm run typecheck|pnpm run lint|pnpm run test"
+eq "vitest config noted" "$(jq -r '.entries[] | select(.cwd == "." and .command == "pnpm run test") | .source' .forge/test-map.json)" "package.json#scripts.test (vitest/jest config)"
+eq "unrelated file" "$(sel README.md)" ""
+
+# ---- 2. python: pytest + ruff through uv ----
+setup python
+eq "python rc" "$RC" 0
+eq "python file" "$(sel pkg/mod.py)" "uv run pytest|uv run ruff check ."
+eq "python test file" "$(sel tests/test_mod.py)" "uv run pytest|uv run ruff check ."
+eq "python non-py" "$(sel uv.lock)" ""
+
+# ---- 3. go: go.mod, Makefile and CI workflow steps; CI-only lint step; install lines skipped ----
+setup go
+eq "go rc" "$RC" 0
+eq "go file" "$(sel main.go)" "./scripts/check-docs|go test ./...|go vet ./...|golangci-lint run ./...|make test"
+eq "nested go file" "$(sel internal/util/util.go)" "./scripts/check-docs|go test ./...|go vet ./...|golangci-lint run ./...|make test"
+eq "ci-only lint source" "$(jq -r '.entries[] | select(.command == "golangci-lint run ./...") | .source' .forge/test-map.json)" ".github/workflows/ci.yml#jobs.lint"
+eq "install line skipped" "$(jq '[.entries[] | select(.command | test("mod download"))] | length' .forge/test-map.json)" 0
+eq "paths filter fallback" "$(jq -c '.entries[] | select(.command == "./scripts/check-docs") | .globs' .forge/test-map.json)" '["**.go","go.mod"]'
+eq "docs file" "$(sel README.md)" "make test"
+eq "go.sum" "$(sel go.sum)" "go test ./...|go vet ./...|make test"
+
+# ---- 4. regenerable: a rerun is byte-identical; --stdout writes nothing; --output ----
+cp .forge/test-map.json "$TMP/first.json"
+bash "$S" >/dev/null
+if cmp -s .forge/test-map.json "$TMP/first.json"; then ok; else bad "rerun not byte-identical"; fi
+rm -rf .forge; OUTS="$(bash "$S" --stdout)"
+eq "stdout same map" "$OUTS" "$(cat "$TMP/first.json")"
+eq "stdout writes nothing" "$([ -e .forge ] && echo yes || echo no)" no
+bash "$S" --repo-path "$TMP/go" --output "$TMP/out/map.json" >/dev/null
+if cmp -s "$TMP/out/map.json" "$TMP/first.json"; then ok; else bad "--output differs"; fi
+
+# ---- 5. block runs, continuation lines, setup lines, workflow without paths ----
+mkdir -p "$TMP/wf/.github/workflows"; cd "$TMP/wf" || exit 1
+git init -q -b main
+cat > .github/workflows/lint.yaml <<'EOF'
+on: push
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    steps:
+      - run: npm ci
+      - run: "shellcheck scripts/*.sh"
+      - run: >-
+          ruff check
+          --fix
+      - run: |
+          echo hi
+          bash scripts/verify.sh \
+            --strict
+          ./custom-check
+EOF
+git add -A
+OUTS="$(bash "$S" --stdout)"
+eq "wf commands" "$(printf '%s' "$OUTS" | jq -r '[.entries[].command] | sort | join("|")')" "./custom-check|bash scripts/verify.sh --strict|ruff check --fix|shellcheck scripts/*.sh"
+eq "wf globs" "$(printf '%s' "$OUTS" | jq -c '[.entries[] | {(.command): .globs}] | add')" '{"./custom-check":["**"],"bash scripts/verify.sh --strict":["**/*.sh"],"ruff check --fix":["**/*.py"],"shellcheck scripts/*.sh":["**/*.sh"]}'
+
+# ---- 5b. forge#4297: `- run: |` then env:/shell: ends the block; deploy/publish/release/push/secret steps dropped ----
+mkdir -p "$TMP/wf2/.github/workflows"; cd "$TMP/wf2" || exit 1
+git init -q -b main
+cat > .github/workflows/ci.yml <<'EOF'
+on:
+  push:
+    branches: [main]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - run: |
+          npm test
+        env:
+          CI: true
+        shell: bash
+      - name: Lint
+        run: |
+          npm run lint
+        working-directory: .
+      - name: Publish to npm
+        run: npm run ship
+      - run: ./scripts/release.sh
+      - run: git push origin HEAD
+      - run: curl -H "token ${{ secrets.TOKEN }}" https://x
+      - run: >-
+          tsc
+          --noEmit
+        shell: bash
+  deploy:
+    name: Ship it
+    runs-on: ubuntu-latest
+    steps:
+      - run: ./ship.sh
+  site:
+    name: Deploy site
+    runs-on: ubuntu-latest
+    steps:
+      - run: ./build-site.sh
+EOF
+git add -A
+OUTS="$(bash "$S" --stdout)"
+eq "wf2 commands" "$(printf '%s' "$OUTS" | jq -r '[.entries[].command] | sort | join("|")')" "npm run lint|npm test|tsc --noEmit"
+
+# ---- 5c. forge#4298: a package dir with a space and a non-ASCII name keeps whole globs; workflow paths with spaces ----
+mkdir -p "$TMP/sp/web app" "$TMP/sp/pkg/ü/src" "$TMP/sp/.github/workflows"; cd "$TMP/sp" || exit 1
+git init -q -b main
+echo '{"name":"root","private":true}' > package.json
+echo '{"name":"web","scripts":{"test":"vitest run"}}' > "web app/package.json"
+echo '{"name":"u","scripts":{"lint":"eslint ."}}' > "pkg/ü/package.json"
+echo 'x' > "pkg/ü/src/a.ts"
+cat > .github/workflows/ci.yml <<'EOF'
+on:
+  push:
+    paths:
+      - "docs site/**"
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - run: ./build-docs.sh
+EOF
+git add -A
+OUTS="$(bash "$S" --stdout)"
+eq "spaced package globs" "$(printf '%s' "$OUTS" | jq -c '[.entries[] | select(.cwd == "web app") | .globs[]] | map(select(endswith("package.json") or endswith(".js")))')" '["web app/**/*.js","web app/package.json"]'
+eq "non-ASCII package dir" "$(printf '%s' "$OUTS" | jq -r '[.entries[] | select(.command == "npm run lint") | .cwd] | join("|")')" "pkg/ü"
+eq "spaced workflow path filter" "$(printf '%s' "$OUTS" | jq -c '[.entries[] | select(.command == "./build-docs.sh") | .globs]')" '[["docs site/**"]]'
+printf '%s' "$OUTS" > "$TMP/sp-map.json"
+eq "spaced changed file selects its package test" "$(node "$SEL" --map "$TMP/sp-map.json" --select "web app/src/x.js")" "cd 'web app' && npm run test"
+
+# ---- 6. usage ----
+bash "$S" --repo-path "$TMP/missing" >/dev/null 2>&1; eq "bad repo path" "$?" 2
+bash "$S" --nope >/dev/null 2>&1; eq "unknown option" "$?" 2
+
+echo "test-map.test.sh: $PASS passed, $FAILN failed"
+[ "$FAILN" -eq 0 ]

package/scripts/wait-ci-green.sh

@@ -4,7 +4,11 @@
 #
 # wait-ci-green.sh — CI gate every autonomous merge must pass first.
 #
-# Usage: wait-ci-green.sh <pr-number> -R <owner/repo> [--timeout SECONDS] [--interval SECONDS]
+# Usage: wait-ci-green.sh <pr-number> -R <owner/repo> [--timeout SECONDS] [--interval SECONDS] [--ignore-check NAME]...
+#
+# --ignore-check NAME (repeatable): drop checks with exactly that name before deciding. `forgedock/verify` (forge#4270,
+# the lean engine's report-only gate summary) is always ignored, so every caller of this gate treats it the same
+# (forge#4298); requiring it is the repository's branch-protection choice.
 #
 # Waits until every check on the PR has finished, then decides. Fails closed: a merge may
 # proceed ONLY on exit 0. Field test: pipeline agents merged PRs to staging while checks were
@@ -40,17 +44,18 @@ set -uo pipefail
 _TEL="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/lib/telemetry.sh"; [ -f "$_TEL" ] && . "$_TEL" 2>/dev/null
 type forge_emit >/dev/null 2>&1 || forge_emit() { :; }
 
-PR=""; REPO=""
+PR=""; REPO=""; IGNORE='["forgedock/verify"]'
 TIMEOUT="${FORGE_CI_TIMEOUT:-540}"; INTERVAL="${FORGE_CI_INTERVAL:-20}"; SETTLE="${FORGE_CI_SETTLE:-45}"
 GRACE="${FORGE_CI_NO_CHECKS_GRACE:-120}"; REQUIRE="${FORGE_CI_REQUIRE_CHECKS:-0}"
-usage() { echo "CI_GATE: ERROR"; echo "CI_GATE_HEAD: unknown"; echo "usage: wait-ci-green.sh <pr> -R <owner/repo> [--timeout S] [--interval S]" >&2; exit 2; }
+usage() { echo "CI_GATE: ERROR"; echo "CI_GATE_HEAD: unknown"; echo "usage: wait-ci-green.sh <pr> -R <owner/repo> [--timeout S] [--interval S] [--ignore-check NAME]..." >&2; exit 2; }
 while [ $# -gt 0 ]; do
   case "$1" in
     -R) [ $# -ge 2 ] || usage; REPO="$2"; shift 2 ;;
     -R*) REPO="${1#-R}"; REPO="${REPO# }"; shift ;;
     --timeout) [ $# -ge 2 ] || usage; TIMEOUT="$2"; shift 2 ;;
     --interval) [ $# -ge 2 ] || usage; INTERVAL="$2"; shift 2 ;;
-    -h|--help) sed -n '5,32p' "$0"; exit 0 ;;
+    --ignore-check) [ $# -ge 2 ] || usage; IGNORE="$(jq -c --arg n "$2" '. + [$n]' <<<"$IGNORE")"; shift 2 ;;
+    -h|--help) sed -n '5,37p' "$0"; exit 0 ;;
     *) [ -z "$PR" ] || usage; PR="$1"; shift ;;
   esac
 done
@@ -132,6 +137,7 @@ while :; do
     fi
   fi
   errors=0; limited=0; transient=0
+  [ "$IGNORE" = '[]' ] || JSON="$(printf '%s' "$JSON" | jq -c --argjson ig "$IGNORE" '[.[] | select(.name as $n | $ig | index($n) | not)]')"
   cur="$(head_sha)"
   if [ -n "$cur" ] && [ "$cur" != "$START_SHA" ]; then emit ERROR; echo "PR head moved during the wait ($START_SHA -> $cur); re-review the new head"; exit 2; fi
   total=$(printf '%s' "$JSON" | jq 'length')

package/scripts/wait-ci-green.test.sh

@@ -55,6 +55,15 @@ expect "pending then pass" "0|CI_GATE: PASS" "$(run "$(mk pend '[{"name":"a","bu
 expect "pending then fail" "1|CI_GATE: FAIL" "$(run "$(mk pendfail '[{"name":"a","bucket":"pending"}]' '[{"name":"a","bucket":"fail"}]')")"
 expect "pending past timeout" "3|CI_GATE: TIMEOUT" "$(run "$(mk slow '[{"name":"a","bucket":"pending"}]')" --timeout 2)"
 expect "fail wins over pending" "1|CI_GATE: FAIL" "$(run "$(mk mixed '[{"name":"a","bucket":"pending"},{"name":"b","bucket":"fail"}]')")"
+# forge#4270: --ignore-check drops the named check (the lane's own report-only forgedock/verify) before deciding.
+OWN='[{"name":"a","bucket":"pass"},{"name":"forgedock/verify","bucket":"fail"}]'
+# forge#4298: forgedock/verify is ignored by default, so every caller (legacy engine, review-finalize, spec gates) agrees.
+expect "own verify check failing is ignored by default" "0|CI_GATE: PASS" "$(run "$(mk ownfail "$OWN")")"
+expect "default ignore keeps other failures" "1|CI_GATE: FAIL" "$(run "$(mk owndef '[{"name":"b","bucket":"fail"},{"name":"forgedock/verify","bucket":"fail"}]')")"
+expect "usage text lists --ignore-check" "1" "$(bash "$GATE" 2>&1 >/dev/null | grep -c -- '--ignore-check NAME')"
+expect "--ignore-check drops the named failing check" "0|CI_GATE: PASS" "$(run "$(mk ownign "$OWN")" --ignore-check forgedock/verify)"
+expect "--ignore-check keeps other failures" "1|CI_GATE: FAIL" "$(run "$(mk ownother '[{"name":"b","bucket":"fail"},{"name":"forgedock/verify","bucket":"pass"}]')" --ignore-check forgedock/verify)"
+expect "--ignore-check without a name is a usage error" "2|CI_GATE: ERROR" "$(run "$(mk ownusage "$P")" --ignore-check)"
 expect "transient outage then pass" "0|CI_GATE: PASS" "$(run "$(mk blip ERR "$P")")"
 expect "persistent unclassified failure is an ERROR" "2|CI_GATE: ERROR" "$(run "$(mk down ERRX)" --timeout 60)"
 # Rate-limit / 5xx classification: retried, never an ERROR; a window that only saw them ends RATE_LIMITED (rc 4).

package/templates/bootstrap/interview.md

@@ -0,0 +1,34 @@
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+# /bootstrap interview question bank
+
+Ask conversationally and keep it short: skip any aspect the user's free text or docs already answer. Every aspect left
+unanswered gets the **Default** and its rationale, tied to what the user did say, in the "Here's what I assumed" summary.
+Aspects marked **Doubt** change architecture or cost. When the answer is unclear, ask them as multiple-choice questions
+(at most 4 per batch, each with a recommended option). All other aspects default silently.
+
+| # | Aspect | Question | Default (rationale pattern) | Doubt? |
+|---|--------|----------|-----------------------------|--------|
+| 1 | Users and segments | Who uses it, and which segments differ in what they need? | One primary segment from the pitch; admins as a second role (most products need an operator view) | no |
+| 2 | Core jobs and features | What must a user be able to do on day one? | The jobs named in the pitch, each as a feature with its happy path | no |
+| 3 | Scope | MVP first, or the full product? | MVP, full product as later milestones (cheapest path to feedback) | yes, when the pitch lists many features |
+| 4 | Platforms | Web, mobile, desktop? | Responsive web (one codebase covers phones) | yes: mobile native vs PWA |
+| 5 | Stack | Any language, framework or hosting preferences? | The closest preset in `stack-profiles.md` | no, unless the user names conflicting stacks |
+| 6 | Auth | How do users sign in? | Email magic link + Google sign-in (lowest friction, no password storage) | no |
+| 7 | Data and tenancy | Is data shared between organisations? | Postgres + row-level security for multi-tenant SaaS; single-tenant otherwise | yes: self-host vs managed DB |
+| 8 | Integrations | Which external services? | A mock provider per credentialed integration so dev and CI stay green | no |
+| 9 | Payments | Do you charge, and how? | Stripe subscriptions behind a mock in dev (most common, test mode is free) | yes, when pricing is unclear |
+| 10 | i18n | Which languages and locales? | English with i18n-ready strings (cheap now, expensive later) | no |
+| 11 | Compliance and residency | Any regulation (GDPR, HIPAA, DPDP) or data-residency rule? | Privacy by default (minimal PII, encrypted at rest); region of the primary market | yes: data residency |
+| 12 | Design ambition and UI libraries | Polished brand or functional? Any UI library? | Accessible component library (e.g. shadcn/ui) plus a design-token theme; hero surfaces go to `/design` | no |
+| 13 | Deployment target | VPS, Cloudflare or a cloud provider? | The stack preset's target with a staging-branch flow (staging -> main) | yes: when the cost profile differs |
+| 14 | Scale | Users and data in year one? | Small (hundreds of users): one region, one DB, a scale path in the spike | no |
+| 15 | Budget | Monthly infra budget? | Free or hobby tiers until launch | no |
+| 16 | Team | Who builds and reviews? | A solo builder with ForgeDock agents | no |
+| 17 | Timeline | Any hard date? | None: milestones in build order | no |
+
+Always a doubt: the **product name** and the **repo owner** (user or org; the owner must be covered by the ForgeDock
+GitHub App installation).
+
+Guardrails and domain rules (e.g. "no auto-send", "India-only data residency") go into the plan's `guardrails` and
+`domainRules`. bootstrap-create.mjs copies them into every issue's Context.

package/templates/bootstrap/issue-body.md

@@ -0,0 +1,42 @@
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+<!-- /bootstrap build-issue body (Pipeline Issue Template). Copy from "## Problem" down; drop the UI block for
+non-UI issues and the hero line for non-hero issues. Plan flags: "ui": true needs the full design spec, "hero": true
+needs the /design line (scripts/bootstrap-validate.mjs). Reference other plan issues as #{{KEY}}. -->
+## Problem
+
+{what this issue delivers and for whom, one paragraph}
+
+## Root Cause (if known)
+
+Greenfield: not built yet. {spike section this implements}
+
+## Affected Files
+
+1. `{planned/path/file.ext}` — new
+2. `{planned/path/other.ext}` — new
+
+## Acceptance Criteria
+
+- [ ] {observable behaviour} [type:unit]
+- [ ] {API or integration behaviour} [type:api]
+- [ ] {user-visible flow} [type:e2e]
+
+### Design spec (UI issues)
+
+- **Breakpoints**: {mobile 360, tablet 768, desktop 1280: layout at each}
+- **States**: empty state {copy and action}; loading state {skeleton}; error state {message and retry}; offline state {cached view or banner}
+- **Motion**: {transitions and durations; respects prefers-reduced-motion}
+- **Accessibility**: {WCAG 2.2 AA: focus order, labels, contrast, keyboard paths}
+- **Dark mode**: {token mapping; verified in both themes}
+- **Hero surface**: route the visual design to `/design` before building this page.
+
+## Context
+
+**Parent**: #{{SPIKE}}
+Spike: `docs/engineering/technical-spike.md` § {section}
+{real credentials: see #{{NEEDS_HUMAN_KEY}}; until then the mock provider is used, so this issue never depends on it}
+
+## Dependencies
+
+Depends on #{{DEP_KEY}} — {why}

package/templates/bootstrap/needs-human-issue.md

@@ -0,0 +1,45 @@
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+<!-- /bootstrap needs-human issue: one per credential, account or external input (OAuth client, cloud or DNS account,
+payment keys, API keys, legal review). Label it needs-human and set "needsHuman": true in the plan. Code issues
+reference it (#{{KEY}}) but never list it under Dependencies; their mocks keep dev and CI green. Copy from "## Problem" down. -->
+## Problem
+
+{which credential, account or external input is needed, and which issues use it}
+
+### Setup steps
+
+1. {exact console URL and the clicks to create it}
+2. {settings to choose: redirect URIs, scopes, region}
+3. {store the values as deploy secrets (repository or environment secrets)}
+
+### Environment variables
+
+- `{SERVICE_CLIENT_ID}` — {what it is}
+- `{SERVICE_CLIENT_SECRET}` — {what it is}
+
+### Secret handling
+
+Never commit these values or paste them into issues. Store them only as deploy/CI secrets and a local untracked
+`.env`. Rotate them if exposed. Until they exist, dev and CI use the mock provider.
+
+## Root Cause (if known)
+
+Greenfield: an external input agents cannot create.
+
+## Affected Files
+
+1. `docs/setup/{service}.md` — new
+
+## Acceptance Criteria
+
+- [ ] Credentials created and stored as deploy secrets [type:manual]
+- [ ] The real provider replaces the mock in staging [type:manual]
+
+## Context
+
+**Parent**: #{{SPIKE}}
+
+## Dependencies
+
+None.

package/templates/bootstrap/stack-profiles.md

@@ -0,0 +1,34 @@
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+# /bootstrap stack-profile presets
+
+Pick the preset closest to the interview and record the choice and its rationale in the spike's Stack section. A
+preset only fills blanks: anything the user said wins. Domain labels go into the plan's `labels`.
+
+## Next.js + shadcn SaaS
+- **Stack**: TypeScript, Next.js (App Router), shadcn/ui + Tailwind, Postgres (Prisma or Drizzle) with row-level security, Auth.js.
+- **Repo layout**: `apps/web/`, `packages/db/`, `packages/ui/`, `packages/config/`, `docs/engineering/`.
+- **Deployment**: Vercel or a VPS with Docker; managed Postgres; preview deployments per branch.
+- **Quality gates**: `tsc --noEmit`, ESLint, Vitest, Playwright smoke test, Lighthouse budget on hero pages.
+- **Domain labels**: `frontend`, `backend`, `infra`, `design`.
+
+## Python API
+- **Stack**: Python 3.12, FastAPI, SQLAlchemy + Alembic, Postgres, Pydantic settings, uv.
+- **Repo layout**: `src/<app>/api/`, `src/<app>/models/`, `src/<app>/services/`, `migrations/`, `tests/`, `docs/engineering/`.
+- **Deployment**: a container on a VPS or Cloud Run; managed Postgres.
+- **Quality gates**: ruff, mypy, pytest with coverage, an OpenAPI schema diff check.
+- **Domain labels**: `backend`, `infra`, `api`.
+
+## Mobile (Expo / React Native)
+- **Stack**: TypeScript, Expo + React Native, Expo Router, a backend from one of the presets above (or Supabase).
+- **Repo layout**: `apps/mobile/`, `apps/api/` (when a custom backend exists), `packages/shared/`, `docs/engineering/`.
+- **Deployment**: EAS Build and Submit; OTA updates for JS-only changes.
+- **Quality gates**: `tsc --noEmit`, ESLint, Jest, a Maestro or Detox smoke flow.
+- **Domain labels**: `mobile`, `backend`, `infra`, `design`.
+
+## Go service
+- **Stack**: Go, chi or net/http, sqlc + Postgres, Docker.
+- **Repo layout**: `cmd/<app>/`, `internal/`, `migrations/`, `docs/engineering/`.
+- **Deployment**: a single static binary in a container on a VPS or Fly.io.
+- **Quality gates**: `go vet`, golangci-lint, `go test -race`.
+- **Domain labels**: `backend`, `infra`.