forgedock 1.26.0 → 1.28.0

package/scripts/issue-create.sh

@@ -0,0 +1,197 @@
+#!/usr/bin/env bash
+# issue-create.sh — deterministic /issue create path (forge#4164): parse, integrity check, dedup, section repair,
+# REST create with token read-back, milestone, project board. commands/issue.md calls it once.
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# Usage: issue-create.sh --title T (--body B | --body-file F) [--label L]... [--milestone M] [--exclude N,N]
+#                        [--dry-run] [--repo OWNER/NAME] [--config forge.yaml]
+#        issue-create.sh --args "<raw \$ARGUMENTS string>" [--repo ...] [--config ...]
+# --args is tokenized quote-aware by xargs (never eval: $(...), backticks, ; and | in caller text are never run, #2094).
+# Repo: --repo, else yq .project.owner/.project.repo of --config (default ${FORGE_CONFIG:-forge.yaml}).
+#
+# Output: exactly one stdout line per run
+#   ISSUE_CREATE_RESULT:CREATED number=N url=U   exit 0
+#   ISSUE_CREATE_RESULT:DRY_RUN                  exit 0 (draft printed, nothing created)
+#   ISSUE_CREATE_RESULT:DEDUP number=N           exit 1 (an open near-duplicate exists; nothing created)
+#   ISSUE_CREATE_RESULT:USAGE                    exit 2 (bad flags, body or integrity marker, dedup usage error)
+#   ISSUE_CREATE_RESULT:ERROR                    exit 3 (GitHub rejected the create or a read-back failed)
+# Diagnostics go to stderr. Bash 3.2 portable: no mapfile, no assoc arrays, no ${arr[@]} under set -u.
+set -o pipefail
+
+usage() { echo "ERROR: $*" >&2; echo "ISSUE_CREATE_RESULT:USAGE"; exit 2; }
+fail() { echo "ERROR: $*" >&2; echo "ISSUE_CREATE_RESULT:ERROR"; exit 3; }
+
+SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TITLE=""; BODY=""; BODY_FILE=""; HAVE_BODY=false; MILESTONE=""; EXCLUDE=""; DRY_RUN=false
+REPO=""; CONFIG="${FORGE_CONFIG:-forge.yaml}"; RAW_ARGS=""; HAVE_RAW=false
+LABELS=()
+
+# --- tokenize --args (quote-aware, never executed) ---------------------------
+TOKENS=()
+take_tokens() { # tokenize $1 into TOKENS via a temp file so the real xargs exit status is seen
+  local tmp tok
+  case "$1" in *[![:space:]]*) ;; *) return 0 ;; esac
+  tmp=$(mktemp "${TMPDIR:-/tmp}/issue-create-args.XXXXXX") || usage "mktemp failed"
+  if ! printf '%s' "$1" | xargs -n1 printf '%s\0' > "$tmp"; then
+    rm -f "$tmp"
+    usage "failed to tokenize the arguments (unbalanced quote, or a token over xargs's limit; use --body-file for large content)"
+  fi
+  while IFS= read -r -d '' tok; do TOKENS+=("$tok"); done < "$tmp"
+  rm -f "$tmp"
+}
+
+# Outer argv: --args/--repo/--config, or the flags themselves.
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --args) [ $# -ge 2 ] || usage "--args requires a value"; RAW_ARGS="$2"; HAVE_RAW=true; shift 2 ;;
+    --repo) [ $# -ge 2 ] || usage "--repo requires a value"; REPO="$2"; shift 2 ;;
+    --config) [ $# -ge 2 ] || usage "--config requires a value"; CONFIG="$2"; shift 2 ;;
+    *) TOKENS+=("$1"); shift ;;
+  esac
+done
+[ "$HAVE_RAW" = true ] && take_tokens "$RAW_ARGS"
+
+# Flag mode only when a token is exactly a known flag: free text that mentions "--verbose" is not a flag typo.
+FLAG_MODE=false
+for t in ${TOKENS[@]+"${TOKENS[@]}"}; do
+  case "$t" in --dry-run|--greenfield|--spike|--title|--body|--body-file|--label|--milestone|--exclude) FLAG_MODE=true; break ;; esac
+done
+[ "$FLAG_MODE" = true ] || usage "no recognised flag: free-text /issue requests are drafted interactively (commands/issue.md), not by this script"
+
+i=0; n=${#TOKENS[@]}
+while [ "$i" -lt "$n" ]; do
+  arg="${TOKENS[$i]}"
+  case "$arg" in
+    --dry-run) DRY_RUN=true ;;
+    --greenfield) ;;   # interactive draft validation only (forge#4172); accepted, no effect on a programmatic create
+    --title|--body|--body-file|--label|--milestone|--exclude|--spike)
+      [ $((i + 1)) -lt "$n" ] || usage "$arg requires a value"
+      i=$((i + 1)); v="${TOKENS[$i]}"
+      case "$arg" in
+        --title) TITLE="$v" ;;
+        --body) BODY="$v"; HAVE_BODY=true ;;
+        --body-file) BODY_FILE="$v" ;;
+        --label) LABELS+=("$v") ;;
+        --milestone) MILESTONE="$v" ;;
+        --exclude) EXCLUDE="$v" ;;
+        --spike) ;;   # see --greenfield
+      esac ;;
+    --*) usage "unrecognized flag: $arg" ;;
+    *) ;;   # stray words are ignored, as in the spec's flag loop
+  esac
+  i=$((i + 1))
+done
+
+# --- body and integrity marker ------------------------------------------------
+[ -n "$TITLE" ] || usage "programmatic mode requires --title"
+if [ "$HAVE_BODY" = true ] && [ -n "$BODY_FILE" ]; then
+  usage "programmatic mode requires exactly one of --body or --body-file (both given)"
+elif [ "$HAVE_BODY" != true ] && [ -z "$BODY_FILE" ]; then
+  usage "programmatic mode requires exactly one of --body or --body-file (neither given)"
+fi
+MARKER=""
+if [ -n "$BODY_FILE" ]; then
+  [ -f "$BODY_FILE" ] && [ -r "$BODY_FILE" ] || usage "--body-file '$BODY_FILE' is missing or unreadable"
+  BODY=$(cat "$BODY_FILE") || usage "--body-file '$BODY_FILE' is missing or unreadable"
+  MARKERS=$(printf '%s' "$BODY" | grep -oE '<!-- FORGE:BODY-INTEGRITY:[^>]+ -->' || true)
+  count=0; [ -n "$MARKERS" ] && count=$(printf '%s\n' "$MARKERS" | wc -l | tr -d ' ')
+  [ "$count" -eq 1 ] || usage "--body-file must contain exactly one FORGE:BODY-INTEGRITY marker (found $count)"
+  MARKER="$MARKERS"
+fi
+
+# --- repository ----------------------------------------------------------------
+if [ -z "$REPO" ] && [ -f "$CONFIG" ] && command -v yq >/dev/null 2>&1; then
+  REPO=$(yq '.project.owner + "/" + .project.repo' "$CONFIG" 2>/dev/null | tr -d '"')
+fi
+case "$REPO" in ?*/?*) ;; *) usage "no target repository: pass --repo OWNER/NAME or a forge.yaml with project.owner/project.repo" ;; esac
+
+# --- dedup (helper resolved from this script's own install, never the cwd) ---
+DEDUP_SCRIPT="$SELF_DIR/issue-dedup.sh"
+[ -f "$DEDUP_SCRIPT" ] || fail "issue-dedup.sh not found next to issue-create.sh ($SELF_DIR)"
+DEDUP_ARGS=("$TITLE" -R "$REPO")
+[ -n "$EXCLUDE" ] && DEDUP_ARGS+=(--exclude "$EXCLUDE")
+DEDUP_RESULT=$(bash "$DEDUP_SCRIPT" "${DEDUP_ARGS[@]}" 2>&1); DEDUP_EXIT=$?
+if [ "$DEDUP_EXIT" -eq 1 ]; then
+  echo "Near-duplicate detected: $DEDUP_RESULT" >&2
+  DEDUP_NUMBER=$(printf '%s\n' "$DEDUP_RESULT" | grep -oE '#[0-9]+' | head -1 | tr -d '#')
+  [ -n "$DEDUP_NUMBER" ] || usage "dedup STOP returned no issue number"
+  echo "ISSUE_CREATE_RESULT:DEDUP number=${DEDUP_NUMBER}"
+  exit 1
+elif [ "$DEDUP_EXIT" -ne 0 ]; then
+  usage "dedup check usage error: $DEDUP_RESULT"
+fi
+
+# --- mandatory sections (repair, never block) ----------------------------------
+section_repair() { # body -> text to append for missing sections
+  local b="$1" add=""
+  printf '%s\n' "$b" | grep -q "^## Problem" || add="$add
+## Problem
+
+Root cause unknown — investigation needed."
+  printf '%s\n' "$b" | grep -q "^## Affected Files" || add="$add
+## Affected Files
+
+Files to be identified during investigation."
+  printf '%s\n' "$b" | grep -q "^## Acceptance Criteria" || add="$add
+## Acceptance Criteria
+
+- [ ] Fix confirmed during investigation."
+  printf '%s' "$add"
+}
+APPEND=$(section_repair "$BODY")
+if [ -n "$APPEND" ]; then
+  BODY="${BODY}${APPEND}"
+  echo "WARNING: body was missing mandatory sections; placeholders added before creation" >&2
+fi
+
+if [ "$DRY_RUN" = true ]; then
+  LABEL_TEXT=""; for l in ${LABELS[@]+"${LABELS[@]}"}; do LABEL_TEXT="${LABEL_TEXT:+$LABEL_TEXT, }$l"; done
+  printf '## Issue Draft (--dry-run — not created)\n\n**Repo**: %s\n**Title**: %s\n**Labels**: %s\n**Milestone**: %s\n\n---\n\n%s\n\n---\n\nRe-run without --dry-run to create this issue.\n' \
+    "$REPO" "$TITLE" "${LABEL_TEXT:-none}" "${MILESTONE:-none}" "$BODY" >&2
+  echo "ISSUE_CREATE_RESULT:DRY_RUN"
+  exit 0
+fi
+
+# --- REST create + create-token read-back (never gh issue create: it can swallow a 403) ---
+CREATE_TOKEN="forge-create-$(date -u +%Y%m%dT%H%M%SZ)-$$-$RANDOM"
+CREATE_BODY="${BODY}
+
+<!-- issue-create-token:${CREATE_TOKEN} -->"
+API_LABELS=()
+for l in ${LABELS[@]+"${LABELS[@]}"}; do API_LABELS+=(-f "labels[]=$l"); done
+CREATE_RESPONSE=$(gh api "repos/${REPO}/issues" --method POST -f title="$TITLE" -f body="$CREATE_BODY" ${API_LABELS[@]+"${API_LABELS[@]}"}) \
+  || fail "GitHub rejected issue creation; no issue was created."
+NEW_NUMBER=$(printf '%s' "$CREATE_RESPONSE" | jq -r '.number // empty' 2>/dev/null)
+case "$NEW_NUMBER" in ''|*[!0-9]*) fail "issue creation returned no issue number." ;; esac
+ISSUE_URL=$(printf '%s' "$CREATE_RESPONSE" | jq -r '.html_url // empty' 2>/dev/null)
+CREATED_BODY=$(gh issue view "$NEW_NUMBER" -R "$REPO" --json body --jq '.body') || fail "could not read back issue #${NEW_NUMBER}."
+printf '%s' "$CREATED_BODY" | grep -qF "issue-create-token:${CREATE_TOKEN}" \
+  || fail "issue #${NEW_NUMBER} did not contain this create token; refusing to report success."
+if [ -n "$MARKER" ] && ! printf '%s\n' "$CREATED_BODY" | grep -Fqx "$MARKER"; then
+  fail "created issue #${NEW_NUMBER} body is missing expected integrity marker $MARKER"
+fi
+
+if [ -n "$MILESTONE" ]; then
+  gh issue edit "$NEW_NUMBER" -R "$REPO" --milestone "$MILESTONE" >&2 || fail "could not set milestone '$MILESTONE' on #${NEW_NUMBER}."
+fi
+
+# Post-create safety net: GitHub or a transform may have altered the body; extend, never replace.
+APPEND=$(section_repair "$CREATED_BODY")
+if [ -n "$APPEND" ]; then
+  gh issue edit "$NEW_NUMBER" -R "$REPO" --body "${CREATED_BODY}${APPEND}" >&2 || echo "WARNING: could not append missing sections to #${NEW_NUMBER}" >&2
+fi
+
+# Project board (best effort), from forge.yaml project_board.
+if [ -f "$CONFIG" ] && command -v yq >/dev/null 2>&1; then
+  PROJECT_NUMBER=$(yq '.project_board.project_number // ""' "$CONFIG" 2>/dev/null | tr -d '"')
+  PROJECT_OWNER=$(yq '.project_board.owner // .project.owner' "$CONFIG" 2>/dev/null | tr -d '"')
+  if [ -n "$PROJECT_NUMBER" ] && [ "$PROJECT_NUMBER" != "null" ] && [ -n "$ISSUE_URL" ]; then
+    gh project item-add "$PROJECT_NUMBER" --owner "$PROJECT_OWNER" --url "$ISSUE_URL" >/dev/null 2>&1 || true
+  fi
+fi
+
+[ -n "$ISSUE_URL" ] || ISSUE_URL="https://github.com/${REPO}/issues/${NEW_NUMBER}"
+echo "Created: ${ISSUE_URL}" >&2
+echo "ISSUE_CREATE_RESULT:CREATED number=${NEW_NUMBER} url=${ISSUE_URL}"
+exit 0

package/scripts/issue-create.test.sh

@@ -0,0 +1,166 @@
+#!/usr/bin/env bash
+# issue-create.test.sh — cases for scripts/issue-create.sh (forge#4164). Hermetic: mock gh and yq on PATH, the real
+# scripts/issue-dedup.sh beside the script under test, no network. Bash 3.2 compatible.
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+set -uo pipefail
+S="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/issue-create.sh"
+PASS=0; FAILN=0
+TMP="$(mktemp -d "${TMPDIR:-/tmp}/issue-create-test.XXXXXX")"; trap 'rm -rf "$TMP"' EXIT
+ok() { PASS=$((PASS+1)); }
+bad() { FAILN=$((FAILN+1)); echo "FAIL: $1"; }
+mkdir -p "$TMP/bin" "$TMP/work/scripts" "$TMP/state"
+
+# Mock gh. Logs every call to $TMP/state/log (one line per call, args joined by |).
+#   issue list            -> $MOCK_CANDIDATES (tsv "number\ttitle") when set
+#   api .../issues POST   -> stores the body field, answers {"number":901,...}; MOCK_POST_FAIL=1 fails, MOCK_NO_NUMBER=1 omits it
+#   issue view --json body-> stored body; MOCK_READBACK=no-token|no-marker|missing-sections alters it
+#   issue edit / project  -> logged, exit 0
+cat > "$TMP/bin/gh" <<'MOCK'
+#!/usr/bin/env bash
+ST="$MOCK_STATE"
+line=""; for a in "$@"; do line="$line|$a"; done; printf '%s\n' "$line" >> "$ST/log"
+if [ "$1" = issue ] && [ "$2" = list ]; then
+  [ -n "${MOCK_CANDIDATES:-}" ] && cat "$MOCK_CANDIDATES"; exit 0
+fi
+if [ "$1" = api ]; then
+  [ "${MOCK_POST_FAIL:-}" = 1 ] && { echo "HTTP 403: secondary rate limit" >&2; exit 1; }
+  prev=""; for a in "$@"; do
+    if [ "$prev" = "-f" ]; then case "$a" in body=*) printf '%s' "${a#body=}" > "$ST/body" ;; esac; fi
+    prev="$a"
+  done
+  if [ "${MOCK_NO_NUMBER:-}" = 1 ]; then echo '{}'; else echo '{"number":901,"html_url":"https://github.com/o/r/issues/901"}'; fi
+  exit 0
+fi
+if [ "$1" = issue ] && [ "$2" = view ]; then
+  b=$(cat "$ST/body")
+  case "${MOCK_READBACK:-}" in
+    no-token) b=$(printf '%s\n' "$b" | grep -v 'issue-create-token:') ;;
+    no-marker) b=$(printf '%s\n' "$b" | grep -v 'FORGE:BODY-INTEGRITY') ;;
+    missing-sections) b=$(printf '%s\n' "$b" | grep -v '^## Problem') ;;
+  esac
+  printf '%s\n' "$b"; exit 0
+fi
+exit 0
+MOCK
+# Mock yq: answers the three expressions issue-create.sh asks of forge.yaml.
+cat > "$TMP/bin/yq" <<'MOCK'
+#!/usr/bin/env bash
+case "$1" in
+  *project.repo*) echo "cfg-owner/cfg-repo" ;;
+  *project_number*) echo "${MOCK_PROJECT:-}" ;;
+  *project_board.owner*) echo "cfg-owner" ;;
+esac
+MOCK
+chmod +x "$TMP/bin/gh" "$TMP/bin/yq"
+export PATH="$TMP/bin:$PATH" MOCK_STATE="$TMP/state"
+
+GOOD="$TMP/body.md"
+printf '## Problem\n\np\n\n## Affected Files\n\n- a\n\n## Acceptance Criteria\n\n- [ ] x\n<!-- FORGE:BODY-INTEGRITY:42_review_t1 -->\n' > "$GOOD"
+
+run() { # name want_rc args...  (cwd = $TMP/work, which has no forge.yaml unless a case writes one)
+  local name="$1" want="$2"; shift 2
+  : > "$TMP/state/log"; rm -f "$TMP/state/body"
+  (cd "$TMP/work" && bash "$S" "$@") >"$TMP/out" 2>"$TMP/err"
+  local rc=$?
+  if [ "$rc" = "$want" ]; then ok; else bad "$name (rc=$rc want $want)"; sed 's/^/  err: /' "$TMP/err"; fi
+}
+out_has() { grep -qF -- "$2" "$TMP/out" && ok || bad "$1 (stdout lacks: $2)"; }
+log_has() { grep -qF -- "$2" "$TMP/state/log" && ok || bad "$1 (gh log lacks: $2)"; }
+log_lacks() { grep -qF -- "$2" "$TMP/state/log" && bad "$1 (gh log has: $2)" || ok; }
+one_result() { [ "$(grep -c '^ISSUE_CREATE_RESULT:' "$TMP/out")" = 1 ] && ok || bad "$1 (not exactly one result line)"; }
+
+# --- created ----------------------------------------------------------------
+run "create exits 0" 0 --repo o/r --title "fix: billing crash" --body-file "$GOOD" --label bug --label "priority:P2"
+out_has "CREATED line" "ISSUE_CREATE_RESULT:CREATED number=901 url=https://github.com/o/r/issues/901"
+one_result "create prints one result line"
+log_has "REST create, not gh issue create" "|api|repos/o/r/issues|--method|POST|"
+log_lacks "never gh issue create" "|issue|create|"
+log_has "labels are distinct fields" "|-f|labels[]=bug|-f|labels[]=priority:P2"
+grep -q 'issue-create-token:forge-create-' "$TMP/state/body" && ok || bad "create token appended to the body"
+log_lacks "no milestone edit when none given" "--milestone"
+
+run "argv --body works" 0 --repo o/r --title "fix: a" --body "## Problem
+x"
+grep -q '^## Affected Files' "$TMP/state/body" && grep -q '^## Acceptance Criteria' "$TMP/state/body" && ok || bad "missing sections repaired before POST"
+grep -q '^## Problem' "$TMP/state/body" && [ "$(grep -c '^## Problem' "$TMP/state/body")" = 1 ] && ok || bad "present section not duplicated"
+
+run "milestone edit" 0 --repo o/r --title "fix: a" --body-file "$GOOD" --milestone "v2"
+log_has "milestone set on the new issue" "|issue|edit|901|-R|o/r|--milestone|v2"
+
+# --- --args: the raw $ARGUMENTS string from the skill --------------------------
+run "--args quoted title" 0 --repo o/r --args "--title \"fix: billing page crash\" --body-file \"$GOOD\" --label bug"
+log_has "multi-word title is one token" "|-f|title=fix: billing page crash|"
+rm -f "$TMP/work/pwned"
+run "--args never executes" 0 --repo o/r --args "--title 'fix: \$(touch pwned) \`touch pwned\`; touch pwned' --body-file \"$GOOD\""
+[ -e "$TMP/work/pwned" ] && bad "command substitution in --args was executed" || ok
+log_has "metacharacters kept literally" 'title=fix: $(touch pwned) `touch pwned`; touch pwned'
+run "unbalanced quote is a usage error" 2 --repo o/r --args "--title \"fix: oops --body x"
+out_has "usage result" "ISSUE_CREATE_RESULT:USAGE"
+
+# --- repo from forge.yaml ---------------------------------------------------------
+: > "$TMP/work/forge.yaml"
+run "repo from forge.yaml" 0 --title "fix: a" --body-file "$GOOD"
+log_has "config repo used" "|api|repos/cfg-owner/cfg-repo/issues|"
+MOCK_PROJECT=7 run "project board add" 0 --title "fix: a" --body-file "$GOOD"
+log_has "issue added to the board" "|project|item-add|7|--owner|cfg-owner|--url|https://github.com/o/r/issues/901"
+rm -f "$TMP/work/forge.yaml"
+run "no repo is a usage error" 2 --title "fix: a" --body-file "$GOOD"
+
+# --- greenfield flags (forge#4172) are accepted, not unrecognized ---------------------
+run "--greenfield/--spike accepted" 0 --repo o/r --args "--greenfield --spike docs/spike.md --title \"fix: a\" --body-file \"$GOOD\""
+run "--spike without a value" 2 --repo o/r --title "fix: a" --body-file "$GOOD" --spike
+
+# --- usage errors: nothing created ---------------------------------------------
+run "--title without a value" 2 --repo o/r --body-file "$GOOD" --title
+log_lacks "no POST on usage error" "|api|"
+run "unrecognized flag" 2 --repo o/r --titel "fix: a" --title "fix: a" --body-file "$GOOD"
+run "both bodies" 2 --repo o/r --title "fix: a" --body "x" --body-file "$GOOD"
+run "neither body" 2 --repo o/r --title "fix: a"
+run "unreadable body file" 2 --repo o/r --title "fix: a" --body-file "$TMP/nope.md"
+log_lacks "no gh call before body checks pass" "|"
+printf '## Problem\nno marker\n' > "$TMP/nomark.md"
+run "body file without marker" 2 --repo o/r --title "fix: a" --body-file "$TMP/nomark.md"
+printf '<!-- FORGE:BODY-INTEGRITY:a_b_c -->\n<!-- FORGE:BODY-INTEGRITY:d_e_f -->\n' > "$TMP/twomark.md"
+run "body file with two markers" 2 --repo o/r --title "fix: a" --body-file "$TMP/twomark.md"
+run "free text is not handled here" 2 --repo o/r --args "the billing page crashes when using --verbose"
+run "no title" 2 --repo o/r --body-file "$GOOD" --label bug
+
+# --- dedup STOP (real issue-dedup.sh) -------------------------------------------
+printf '777\tfix: billing crash when credits reach zero\n' > "$TMP/cands.tsv"
+MOCK_CANDIDATES="$TMP/cands.tsv" run "dedup STOP exits 1" 1 --repo o/r --title "fix: billing crash when credits reach zero" --body-file "$GOOD"
+out_has "DEDUP line" "ISSUE_CREATE_RESULT:DEDUP number=777"
+one_result "dedup prints one result line"
+log_lacks "no POST after dedup STOP" "|api|"
+MOCK_CANDIDATES="$TMP/cands.tsv" run "dedup STOP holds under --dry-run" 1 --repo o/r --dry-run --title "fix: billing crash when credits reach zero" --body-file "$GOOD"
+MOCK_CANDIDATES="$TMP/cands.tsv" run "--exclude narrows the candidate set" 0 --repo o/r --exclude 777 --title "fix: billing crash when credits reach zero" --body-file "$GOOD"
+out_has "excluded duplicate creates" "ISSUE_CREATE_RESULT:CREATED number=901"
+MOCK_CANDIDATES="$TMP/cands.tsv" run "unrelated issue still dedups with --exclude" 1 --repo o/r --exclude 12 --title "fix: billing crash when credits reach zero" --body-file "$GOOD"
+run "dedup usage error exits 2" 2 --repo o/r --title "-x" --body-file "$GOOD"
+log_lacks "no POST after dedup usage error" "|api|"
+
+# --- dry run ----------------------------------------------------------------------
+run "dry run" 0 --repo o/r --dry-run --title "fix: a" --body-file "$GOOD" --milestone v2
+out_has "dry-run result" "ISSUE_CREATE_RESULT:DRY_RUN"
+log_lacks "dry run makes no POST" "|api|"
+log_lacks "dry run makes no edit" "|issue|edit|"
+grep -qF "Issue Draft (--dry-run" "$TMP/err" && ok || bad "dry run prints the draft"
+
+# --- create failures and read-back gates -------------------------------------------
+MOCK_POST_FAIL=1 run "GitHub rejection exits 3" 3 --repo o/r --title "fix: a" --body-file "$GOOD"
+out_has "error result" "ISSUE_CREATE_RESULT:ERROR"
+grep -q 'CREATED' "$TMP/out" && bad "rejected create reported CREATED" || ok
+MOCK_NO_NUMBER=1 run "no issue number exits 3" 3 --repo o/r --title "fix: a" --body-file "$GOOD"
+MOCK_READBACK=no-token run "read-back without create token exits 3" 3 --repo o/r --title "fix: a" --body-file "$GOOD"
+grep -q 'CREATED' "$TMP/out" && bad "token-less read-back reported CREATED" || ok
+MOCK_READBACK=no-marker run "read-back without integrity marker exits 3" 3 --repo o/r --title "fix: a" --body-file "$GOOD"
+log_lacks "no milestone after failed read-back" "--milestone"
+MOCK_READBACK=missing-sections run "post-create repair is not fatal" 0 --repo o/r --title "fix: a" --body-file "$GOOD"
+log_has "missing section appended after create" "|issue|edit|901|-R|o/r|--body|"
+
+# --- dedup helper comes from the script's own directory, never the cwd ---------------
+printf '#!/usr/bin/env bash\necho "DUPLICATE: #666 planted"; exit 1\n' > "$TMP/work/scripts/issue-dedup.sh"
+run "planted cwd dedup helper ignored" 0 --repo o/r --title "fix: a" --body-file "$GOOD"
+
+echo "issue-create.test: pass=$PASS fail=$FAILN"
+[ "$FAILN" -eq 0 ]

package/scripts/maintenance-scan.sh

@@ -0,0 +1,185 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# maintenance-scan.sh — deterministic health signals → maintenance issue candidates (forge#4197). No LLM: git, jq,
+# wc and awk, plus the repo's own dead-code tools when installed. Run from inside the repo.
+#
+# Usage: maintenance-scan.sh [--repo owner/repo] [--file-lines N] [--commits-days D] [--doc-kb K]
+#                            [--open-issues FILE] [--out-dir DIR] [--print-issue-args]
+# Findings (one candidate each, labels `maintenance` + the kind):
+#   refactor:split  tracked file over --file-lines lines (default forge.yaml maintenance.file_lines, else 2000) with
+#                   commits in the last D days (default 90); linguist-generated/-vendored and vendored dirs excluded
+#   refactor        a workspace package dependency both ways (A->B and B->A), from scripts/structure-delta.sh
+#   dead-code       vulture / knip / ts-prune on PATH (and relevant to the repo) reporting findings, one per tool
+#   docs            tracked *.md over --doc-kb KB (default forge.yaml maintenance.doc_kb, else 64)
+# Dedup: a candidate is dropped when an open issue body carries its `<!-- FORGE:MAINT:<kind>:<key> -->` marker, or its
+# title is a near-duplicate (scripts/issue-dedup.sh) of an open issue naming the same key. --open-issues FILE (JSON array
+# of {number,title,body}) replaces the one `gh issue list` call; it then matches markers and exact titles only.
+# Output: a JSON array of {kind,key,title,labels,body_file,marker,numbers}, `[]` when everything is under threshold.
+# Body files (with one FORGE:BODY-INTEGRITY marker, per /issue's programmatic contract) go to --out-dir (default a
+# mktemp dir under $TMPDIR). --print-issue-args prints one `/issue --title ... --body-file ... --label ...` line per
+# candidate instead, for `Skill(skill="{FORGE_SKILL_PREFIX}issue", args=<line>)`.
+# Exit: 0 ok | 2 usage, not a git repo, or open issues unreadable. bash 3.2 portable.
+set -uo pipefail
+
+die() { echo "maintenance-scan: $*" >&2; exit 2; }
+command -v jq >/dev/null 2>&1 || die "jq is required"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+REPO="" FILE_LINES="" DAYS=90 DOC_KB="" OPEN_FILE="" OUT_DIR="" PRINT_ARGS=false
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --repo) REPO="${2:-}"; shift 2 ;;
+    --file-lines) FILE_LINES="${2:-}"; shift 2 ;;
+    --commits-days) DAYS="${2:-}"; shift 2 ;;
+    --doc-kb) DOC_KB="${2:-}"; shift 2 ;;
+    --open-issues) OPEN_FILE="${2:-}"; shift 2 ;;
+    --out-dir) OUT_DIR="${2:-}"; shift 2 ;;
+    --print-issue-args) PRINT_ARGS=true; shift ;;
+    -h|--help) sed -n '5,24p' "$0"; exit 0 ;;
+    *) die "unknown argument: $1" ;;
+  esac
+done
+
+ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || die "not inside a git repository"
+cd "$ROOT" || die "cannot cd to $ROOT"
+
+# forge.yaml `maintenance:` block (block form only, like bin/forge-utils.mjs parseForgeYaml): direct children only, so
+# a sub-map's keys (`  hotspot:` → `    file_lines:`, forge#4195) never stand in for the section's own
+yaml_maint() {
+  [ -f forge.yaml ] || return 0
+  awk -v k="$1" '
+    /^[A-Za-z_][A-Za-z0-9_]*:[[:space:]]*(#.*)?$/ { on = ($0 ~ /^maintenance:/); ci = -1; next }
+    /^[^[:space:]#]/ { on = 0 }
+    on && /^[[:space:]]*(#|$)/ { next }
+    on { match($0, /^[[:space:]]*/); if (ci >= 0 && RLENGTH > ci) next; ci = RLENGTH }
+    on && $0 ~ "^[[:space:]]+" k ":" { sub("^[[:space:]]+" k ":[[:space:]]*", ""); sub("[[:space:]]*#.*$", ""); gsub(/"/, ""); print; exit }
+  ' forge.yaml
+}
+[ -n "$FILE_LINES" ] || FILE_LINES=$(yaml_maint file_lines)
+[ -n "$DOC_KB" ] || DOC_KB=$(yaml_maint doc_kb)
+FILE_LINES=${FILE_LINES:-2000} DOC_KB=${DOC_KB:-64}
+for v in "$FILE_LINES" "$DAYS" "$DOC_KB"; do case "$v" in ''|*[!0-9]*) die "thresholds must be positive integers" ;; esac; done
+
+T=$(mktemp -d "${TMPDIR:-/tmp}/maintenance-scan.XXXXXX") || die "mktemp failed"
+trap 'rm -rf "$T"' EXIT
+if [ -z "$OUT_DIR" ]; then OUT_DIR=$(mktemp -d "${TMPDIR:-/tmp}/maintenance-scan-out.XXXXXX") || die "mktemp failed"; fi
+mkdir -p "$OUT_DIR" || die "cannot create $OUT_DIR"
+OUT_DIR=$(cd "$OUT_DIR" && pwd)
+
+# ---- open issues, once ----
+if [ -n "$OPEN_FILE" ]; then
+  jq -e 'type == "array"' "$OPEN_FILE" >/dev/null 2>&1 || die "--open-issues must be a JSON array"
+  cp "$OPEN_FILE" "$T/open.json"
+else
+  gh issue list ${REPO:+-R "$REPO"} --state open --limit 1000 --json number,title,body > "$T/open.json" 2>/dev/null || die "cannot list open issues (gh)"
+fi
+
+# ---- tracked files, minus generated/vendored ----
+git ls-files > "$T/all"
+git check-attr --stdin linguist-generated linguist-vendored < "$T/all" \
+  | awk -F': ' '$3 == "set" || $3 == "true" { print $1 }' | sort -u > "$T/excluded"
+grep -vE '(^|/)(node_modules|vendor|third_party|dist|build)/' "$T/all" | sort | comm -23 - "$T/excluded" > "$T/files"
+
+# candidates: "kind<TAB>key<TAB>title<TAB>numbers-json<TAB>evidence"
+: > "$T/cands"
+add() { printf '%s\t%s\t%s\t%s\t%s\n' "$1" "$2" "$3" "$4" "$5" >> "$T/cands"; }
+
+# ---- hotspots: over-threshold files with commits in the window ----
+git log --since="$DAYS days ago" --format= --name-only 2>/dev/null | awk 'NF' | sort | uniq -c \
+  | awk '{ n = $1; sub(/^ *[0-9]+ /, ""); print $0 "\t" n }' > "$T/churn"
+tr '\n' '\0' < "$T/files" | xargs -0 wc -l 2>/dev/null \
+  | awk -v max="$FILE_LINES" '{ n = $1; p = $0; sub(/^ *[0-9]+ /, "", p); if (n > max && p != "total") print p "\t" n }' > "$T/big"
+while IFS="$(printf '\t')" read -r path lines; do
+  [ -f "$path" ] || continue
+  grep -Iq . "$path" 2>/dev/null || continue # binary
+  commits=$(awk -F'\t' -v p="$path" '$1 == p { print $2; exit }' "$T/churn")
+  [ -n "$commits" ] && [ "$commits" -gt 0 ] || continue
+  add "refactor:split" "$path" "split $path ($lines loc, $commits commits/${DAYS}d)" \
+    "{\"lines\":$lines,\"commits\":$commits,\"days\":$DAYS,\"threshold\":$FILE_LINES}" \
+    "\`$path\` has $lines lines (budget $FILE_LINES) and $commits commits in the last $DAYS days."
+done < "$T/big"
+
+# ---- backwards edges: workspace packages depending on each other both ways ----
+if git show HEAD:package.json 2>/dev/null | jq -e '.workspaces' >/dev/null 2>&1 || git cat-file -e HEAD:pnpm-workspace.yaml 2>/dev/null; then
+  first=$(git rev-list --max-parents=0 HEAD | tail -1)
+  if sd=$("$SCRIPT_DIR/structure-delta.sh" "$first" HEAD 2>/dev/null); then
+    printf '%s' "$sd" | jq -r '[(.package_edges_added // [])[] | [.from, .to]] | unique as $e
+      | $e[] | . as $p | select($p[0] < $p[1] and ($e | index([[$p[1], $p[0]]])) != null) | "\($p[0])\t\($p[1])"' 2>/dev/null \
+      | while IFS="$(printf '\t')" read -r a b; do
+          add "refactor" "$a->$b" "untangle $a <-> $b (pkg cycle)" "{\"edges\":2}" \
+            "Workspace package \`$a\` depends on \`$b\` and \`$b\` depends on \`$a\`."
+        done
+  fi
+fi
+
+# ---- dead code: the repo's own tools, only when installed and relevant ----
+count_lines() { awk 'NF' | wc -l | tr -d ' '; }
+dead() { # tool, count
+  [ "$2" -gt 0 ] 2>/dev/null || return 0
+  add "dead-code" "$1" "remove $2 unused ($1)" "{\"findings\":$2}" "\`$1\` reports $2 unused items."
+}
+if command -v vulture >/dev/null 2>&1 && grep -q '\.py$' "$T/files"; then
+  dead vulture "$(grep '\.py$' "$T/files" | tr '\n' '\0' | xargs -0 vulture 2>/dev/null | count_lines)"
+fi
+if [ -f package.json ]; then
+  command -v knip >/dev/null 2>&1 && dead knip "$(knip --no-progress --reporter compact 2>/dev/null | count_lines)"
+  command -v ts-prune >/dev/null 2>&1 && dead ts-prune "$(ts-prune 2>/dev/null | grep -v '(used in module)' | count_lines)"
+fi
+
+# ---- oversized docs ----
+grep -E '\.md$' "$T/files" | tr '\n' '\0' | xargs -0 wc -c 2>/dev/null \
+  | awk -v max="$((DOC_KB * 1024))" '{ n = $1; p = $0; sub(/^ *[0-9]+ /, "", p); if (n > max && p != "total") print p "\t" n }' \
+  | while IFS="$(printf '\t')" read -r path bytes; do
+      kb=$(( (bytes + 1023) / 1024 ))
+      add "docs" "$path" "trim $path ($kb KB > $DOC_KB KB)" "{\"kb\":$kb,\"threshold_kb\":$DOC_KB}" \
+        "\`$path\` is $kb KB; agents load docs under $DOC_KB KB whole."
+    done
+
+# ---- dedup, body files, output ----
+slug() { printf '%s' "$1" | tr -c 'A-Za-z0-9._-' '_' | cut -c1-80; }
+title_dup() { # title, key: an open near-duplicate title that names the same key
+  if [ -n "$OPEN_FILE" ]; then
+    jq -e --arg t "$1" 'any(.[]; .title == $t)' "$T/open.json" >/dev/null
+  else
+    local hit
+    hit=$("$SCRIPT_DIR/issue-dedup.sh" "$1" ${REPO:+-R "$REPO"} 2>/dev/null) && return 1
+    case "$hit" in *"$2"*) return 0 ;; *) return 1 ;; esac
+  fi
+}
+: > "$T/out.jsonl"
+sort -t "$(printf '\t')" -k1,1 -k2,2 -u "$T/cands" | while IFS="$(printf '\t')" read -r kind key title numbers evidence; do
+  marker="FORGE:MAINT:$kind:$key"
+  jq -e --arg m "<!-- $marker -->" 'any(.[]; (.body // "") | contains($m))' "$T/open.json" >/dev/null && continue
+  title_dup "$title" "$key" && continue
+  id="maint_$(slug "$kind")_$(printf '%s' "$kind:$key" | cksum | awk '{print $1}')"
+  body="$OUT_DIR/${id}_$(slug "${key%.md}").md"
+  cat > "$body" <<EOF
+## Problem
+
+$evidence Found by \`scripts/maintenance-scan.sh\`; it is dispatched within the maintenance budget (forge.yaml \`maintenance.share\`).
+
+## Evidence
+
+\`\`\`json
+$numbers
+\`\`\`
+
+## Acceptance Criteria
+
+- [ ] \`scripts/maintenance-scan.sh\` no longer reports \`$kind\` for \`$key\`
+- [ ] Behaviour is unchanged (existing tests pass)
+
+<!-- $marker -->
+<!-- FORGE:BODY-INTEGRITY:$id -->
+EOF
+  jq -n -c --arg kind "$kind" --arg key "$key" --arg title "$title" --arg body "$body" --arg marker "$marker" --argjson numbers "$numbers" \
+    '{kind: $kind, key: $key, title: $title, labels: ["maintenance", $kind], body_file: $body, marker: $marker, numbers: $numbers}' >> "$T/out.jsonl"
+done
+
+if [ "$PRINT_ARGS" = true ]; then
+  jq -r '"/issue --title \"" + (.title | gsub("\""; "\\\"")) + "\" --body-file \"" + .body_file + "\" --label maintenance --label " + .kind' "$T/out.jsonl"
+else
+  jq -s -c '.' "$T/out.jsonl"
+fi

package/scripts/maintenance-scan.test.sh

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+# maintenance-scan.test.sh — cases for scripts/maintenance-scan.sh (forge#4197). Throwaway repos under $TMPDIR, no network.
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SCAN="$SCRIPT_DIR/maintenance-scan.sh"
+TMP="$(mktemp -d "${TMPDIR:-/tmp}/maintenance-scan-test.XXXXXX")"; trap 'rm -rf "$TMP"' EXIT
+PASS=0 FAILN=0
+ok() { PASS=$((PASS + 1)); }
+fail() { FAILN=$((FAILN + 1)); echo "FAIL: $*"; }
+check() { if [ "$2" = "$3" ]; then ok; else fail "$1: expected [$3] got [$2]"; fi; }
+
+# A PATH without any dead-code tool (a host install must not leak into the cases).
+BIN="$TMP/bin"; mkdir -p "$BIN"
+for t in git jq awk sed tr wc sort comm uniq cut grep cksum mktemp xargs cat cp mkdir rm dirname head tail env bash; do
+  p=$(command -v "$t") && ln -sf "$p" "$BIN/$t"
+done
+export GIT_AUTHOR_NAME=t GIT_AUTHOR_EMAIL=t@t GIT_COMMITTER_NAME=t GIT_COMMITTER_EMAIL=t@t
+NONE="$TMP/none.json"; echo '[]' > "$NONE"
+scan() { PATH="$BIN" bash "$SCAN" --open-issues "${OPEN:-$NONE}" --out-dir "$TMP/out" "$@"; }
+
+R="$TMP/repo"; mkdir -p "$R"; cd "$R" || exit 1
+git init -q . && echo "# r" > README.md && git add . && git commit -qm init
+
+# ---- 1. below thresholds: [] ----
+seq 1 50 > small.py; git add . && git commit -qm small
+check "below thresholds" "$(scan --file-lines 100)" "[]"
+
+# ---- 2. one over-threshold file: one refactor:split candidate with numbers ----
+seq 1 300 > big.py; git add . && git commit -qm big1; echo x >> big.py; git commit -qam big2
+seq 1 400 > gen.py; echo "gen.py linguist-generated" > .gitattributes; git add . && git commit -qm gen
+out=$(scan --file-lines 100)
+check "one hotspot" "$(printf '%s' "$out" | jq -c '[.[] | [.kind, .key]]')" '[["refactor:split","big.py"]]'
+check "title numbers" "$(printf '%s' "$out" | jq -r '.[0].title')" "split big.py (301 loc, 2 commits/90d)"
+check "numbers" "$(printf '%s' "$out" | jq -c '.[0].numbers')" '{"lines":301,"commits":2,"days":90,"threshold":100}'
+check "labels" "$(printf '%s' "$out" | jq -c '.[0].labels')" '["maintenance","refactor:split"]'
+bf=$(printf '%s' "$out" | jq -r '.[0].body_file')
+check "body marker" "$(grep -c 'FORGE:MAINT:refactor:split:big.py' "$bf")" "1"
+check "integrity marker" "$(grep -cE '<!-- FORGE:BODY-INTEGRITY:[^>]+ -->' "$bf")" "1"
+# thresholds from forge.yaml (block form)
+printf 'maintenance:\n  enabled: true\n  file_lines: 100\n' > forge.yaml; git add . && git commit -qm cfg
+check "forge.yaml threshold" "$(scan | jq -c '[.[].key]')" '["big.py"]'
+# a sub-map's key (maintenance.hotspot.file_lines, forge#4195) is not the section's own threshold
+printf 'maintenance:\n  enabled: true\n  hotspot:\n    file_lines: 5000\n  file_lines: 100\n' > forge.yaml; git add . && git commit -qm cfg2
+check "sub-map key ignored" "$(scan | jq -c '[.[].key]')" '["big.py"]'
+
+# ---- 3. dedup: an open issue carrying the marker, or the exact title ----
+jq -n --arg b "x <!-- FORGE:MAINT:refactor:split:big.py --> y" '[{number: 1, title: "other", body: $b}]' > "$TMP/open1.json"
+check "dedup by marker" "$(OPEN="$TMP/open1.json" scan)" "[]"
+jq -n '[{number: 2, title: "split big.py (301 loc, 2 commits/90d)", body: ""}]' > "$TMP/open2.json"
+check "dedup by title" "$(OPEN="$TMP/open2.json" scan)" "[]"
+
+# ---- 4. oversized doc ----
+awk 'BEGIN { for (i = 0; i < 3000; i++) print "doc line padding padding padding" }' > ARCH.md; git add . && git commit -qm doc
+check "doc candidate" "$(scan --doc-kb 64 | jq -c '[.[] | select(.kind == "docs") | [.key, .numbers.kb]]')" '[["ARCH.md",97]]'
+check "doc under budget" "$(scan --doc-kb 200 | jq -c '[.[] | select(.kind == "docs")]')" "[]"
+
+# ---- 5. dead code from a stubbed knip (only when package.json exists) ----
+printf '#!/usr/bin/env bash\nprintf "a.ts: x\\nb.ts: y\\nc.ts: z\\n"\n' > "$BIN/knip"; chmod +x "$BIN/knip"
+check "knip needs package.json" "$(scan | jq -c '[.[] | select(.kind == "dead-code")]')" "[]"
+echo '{"name":"r"}' > package.json; git add . && git commit -qm pkg
+check "knip candidate" "$(scan | jq -c '[.[] | select(.kind == "dead-code") | [.key, .numbers.findings, .title]]')" '[["knip",3,"remove 3 unused (knip)"]]'
+rm -f "$BIN/knip"
+
+# ---- 6. determinism and /issue argument lines ----
+a=$(scan); b=$(scan)
+check "deterministic" "$a" "$b"
+args=$(scan --print-issue-args)
+check "issue-arg lines" "$(printf '%s\n' "$args" | grep -c '^/issue --title ".*" --body-file ".*" --label maintenance --label ')" "$(printf '%s' "$a" | jq length)"
+
+# ---- 7. a workspace package cycle ----
+W="$TMP/ws"; mkdir -p "$W"; cd "$W" || exit 1
+git init -q . && echo "# w" > README.md && git add . && git commit -qm init
+echo '{"name":"root","private":true,"workspaces":["packages/*"]}' > package.json
+mkdir -p packages/a packages/b packages/c
+echo '{"name":"@s/a","dependencies":{"@s/b":"*"}}' > packages/a/package.json
+echo '{"name":"@s/b","dependencies":{"@s/a":"*"}}' > packages/b/package.json
+echo '{"name":"@s/c","dependencies":{"@s/a":"*"}}' > packages/c/package.json
+git add . && git commit -qm ws
+check "package cycle" "$(scan | jq -c '[.[] | select(.kind == "refactor") | [.key, .title]]')" '[["@s/a->@s/b","untangle @s/a <-> @s/b (pkg cycle)"]]'
+
+# ---- 8. usage and no model call ----
+PATH="$BIN" bash "$SCAN" --bogus >/dev/null 2>&1; check "usage exit" "$?" "2"
+check "no LLM invocation" "$(grep -nEi '\b(claude|codex|anthropic|openai|ollama)\b' "$SCAN" | grep -v '^[0-9]*:#' || true)" ""
+
+echo "maintenance-scan.test.sh: $PASS passed, $FAILN failed"
+[ "$FAILN" -eq 0 ]