forgedock 1.27.0 → 1.28.0

package/scripts/fixtures/symbol-move-ts/gen_big.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+//
+// gen_big.mjs <repo dir>: writes the TypeScript refactor:split fixture used by scripts/symbol-move-ts.test.sh
+// (forge#4212): src/big.ts (~700 lines: exported consts, non-exported helpers each used only by its exported
+// function, interfaces, classes, async functions, kept code that uses moved names, a relative import), src/util.ts
+// and a node:test suite in test/big.test.ts (one skipped test). Specifiers carry the .ts extension so Node runs
+// the sources with type stripping.
+import { mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+const root = process.argv[2];
+if (!root) { process.stderr.write("usage: gen_big.mjs <dir>\n"); process.exit(2); }
+const N = 20;
+const pad = (i) => String(i).padStart(2, "0");
+const out = [];
+out.push("// SPDX-License-Identifier: MIT", "// big.ts: a hotspot module for the split fixture.", "",
+  'import { clamp, type Unit } from "./util.ts";', "");
+for (let i = 0; i < N; i++) out.push(`export const LIMIT_${pad(i)} = ${100 + i};`);
+out.push("");
+for (let i = 0; i < N; i++) {
+  out.push(`// scale step ${i}`, `function _scale_${pad(i)}(x: number): number {`, `  const factor = ${i + 1};`, "  return x * factor;", "}", "");
+  out.push(`/** compute ${i}: scaled and clamped. */`, `export function compute_${pad(i)}(x: number): number {`, `  const scaled = _scale_${pad(i)}(x);`,
+    `  return clamp(scaled, 0, LIMIT_${pad(i)});`, "}", "");
+}
+for (let i = 0; i < N; i++) {
+  out.push(`export interface Item_${pad(i)} {`, "  id: number;", "  unit: Unit;", "}", "");
+  out.push(`export class Store_${pad(i)} {`, `  items: Item_${pad(i)}[] = [];`, `  add(item: Item_${pad(i)}): number {`, "    this.items.push(item);",
+    `    return compute_${pad(i)}(item.id);`, "  }", "", "  size(): number {", "    return this.items.length;", "  }", "}", "");
+}
+for (let i = 0; i < N; i++) {
+  out.push(`export async function fetch_${pad(i)}(x: number): Promise<number> {`, "  await Promise.resolve();", `  return compute_${pad(i)}(x) + 1;`, "}", "");
+}
+out.push("// kept code that uses moved names", "export function summary(): number {", "  return compute_00(1) + LIMIT_01 + new Store_02().size();", "}", "",
+  "function _shared(x: number): number {", "  return x + 1;", "}", "", "export function kept_total(x: number): number {", "  return _shared(x) * 2;", "}", "",
+  "export function ping(n: number): number {", "  return n <= 0 ? 0 : pong(n - 1);", "}", "", "export function pong(n: number): number {", "  return n <= 0 ? 1 : ping(n - 1);", "}");
+
+const test = [
+  'import { test } from "node:test";', 'import assert from "node:assert/strict";',
+  'import { compute_03, LIMIT_05, Store_04, fetch_06, summary, kept_total, ping } from "../src/big.ts";', "",
+  'test("compute clamps", () => { assert.equal(compute_03(1000), 103); assert.equal(compute_03(2), 8); });',
+  'test("limits", () => { assert.equal(LIMIT_05, 105); });',
+  'test("store", () => { const s = new Store_04(); assert.equal(s.add({ id: 2, unit: "m" }), 10); assert.equal(s.size(), 1); });',
+  'test("fetch", async () => { assert.equal(await fetch_06(1), 8); });',
+  'test("kept", () => { assert.equal(summary(), 1 + 101 + 0); assert.equal(kept_total(1), 4); assert.equal(ping(3), 1); });',
+  'test("later", { skip: "not yet" }, () => {});', "",
+];
+
+mkdirSync(path.join(root, "src"), { recursive: true });
+mkdirSync(path.join(root, "test"), { recursive: true });
+writeFileSync(path.join(root, "src/big.ts"), out.join("\n") + "\n");
+writeFileSync(path.join(root, "src/util.ts"),
+  'export type Unit = "m" | "s";\n\nexport function clamp(x: number, lo: number, hi: number): number {\n  return Math.min(hi, Math.max(lo, x));\n}\n');
+writeFileSync(path.join(root, "test/big.test.ts"), test.join("\n"));
+writeFileSync(path.join(root, "package.json"), '{ "name": "split-fixture", "private": true, "type": "module" }\n');

package/scripts/forge-root.test.sh

@@ -341,7 +341,7 @@ hr_check_stub review-pr "$HR_CLASSIFY" DERIVE_MILESTONE_SCRIPT derive-finding-mi
 hr_check_stub review-pr "$HR_CLASSIFY" PRIORITY_SCRIPT severity-to-priority.sh
 hr_check_stub review-prepare "$HR_PREPARE" CODE_INDEX_SCRIPT code-index.sh
 hr_check_stub review-pr "$HR_CLASSIFY" DEDUP_SCRIPT issue-dedup.sh
-hr_check_block issue "$ROOT/commands/issue.md" DEDUP_SCRIPT issue-dedup.sh
+hr_check_stub issue "$ROOT/commands/issue.md" ISSUE_CREATE_SCRIPT issue-create.sh
 stub_block "$HR_CLASSIFY" DERIVE_MILESTONE_SCRIPT > "$T/hr_dm.sh"
 stub_block "$HR_CLASSIFY" PRIORITY_SCRIPT > "$T/hr_pr.sh"
 # no bare cwd-relative helper call in either review spec

package/scripts/hotspots.sh

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# hotspots.sh — deterministic size and churn facts for named files (forge#4195). No LLM, no network: git + wc + jq,
+# yq (optional) only to read forge.yaml. Run from the repo root.
+#
+# Usage: hotspots.sh [--base <ref>] [--] <path>...
+# Config: forge.yaml maintenance.hotspot {enabled, file_lines, growth_lines, exclude_globs}; defaults true/2000/150/[]
+#   (also when forge.yaml or yq is missing).
+# Output (stdout, one JSON object):
+#   {"enabled","file_lines","growth_lines","files":[{path,lines,commits_90d,hotspot,over,excluded,base_lines,growth}]}
+# lines = `wc -l` of the working-tree file (0 when missing); commits_90d = `git rev-list --count --since=90.days HEAD`;
+# hotspot = lines × commits_90d; over = lines > file_lines; excluded = linguist-generated / linguist-vendored set by
+# .gitattributes, or a match of an exclude_glob (shell pattern, `*` crosses `/`). Without --base no blob is read and
+# base_lines/growth are null; with --base they are the line count at git merge-base(<ref>, HEAD) (0 when absent there)
+# and lines - base_lines. enabled:false prints files:[] and does no per-file work.
+# Exit: 0 ok | 2 usage or bad ref. bash 3.2 portable.
+set -uo pipefail
+
+die() { echo "hotspots: $*" >&2; exit 2; }
+command -v jq >/dev/null 2>&1 || die "jq is required"
+BASE=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --base) [ $# -ge 2 ] && [ -n "$2" ] || die "usage: hotspots.sh [--base <ref>] [--] <path>..."; BASE="$2"; shift 2 ;;
+    --) shift; break ;;
+    -*) die "unknown option: $1" ;;
+    *) break ;;
+  esac
+done
+
+# ---- config: maintenance.hotspot as JSON, {} when unreadable ----
+CFG='{}'
+if [ -f forge.yaml ] && command -v yq >/dev/null 2>&1; then
+  c=$(yq -o=json '.maintenance.hotspot // {}' forge.yaml 2>/dev/null) || c=""
+  printf '%s' "$c" | jq -e 'type == "object"' >/dev/null 2>&1 && CFG="$c"
+fi
+CFG=$(printf '%s' "$CFG" | jq -c '
+  def pos($d): if type == "number" and . > 0 then floor else $d end;
+  { enabled: (.enabled != false), file_lines: (.file_lines | pos(2000)), growth_lines: (.growth_lines | pos(150)),
+    exclude_globs: ([(.exclude_globs // [])[]? | strings]) }')
+ENABLED=$(printf '%s' "$CFG" | jq -r '.enabled')
+FILE_LINES=$(printf '%s' "$CFG" | jq -r '.file_lines')
+GROWTH_LINES=$(printf '%s' "$CFG" | jq -r '.growth_lines')
+head_json() { printf '%s' "$CFG" | jq -c --argjson files "$1" '{enabled, file_lines, growth_lines, files: $files}'; }
+[ "$ENABLED" = true ] || { head_json '[]'; exit 0; }
+
+MB=""
+if [ -n "$BASE" ]; then
+  git rev-parse --verify -q "$BASE^{commit}" >/dev/null || die "bad base ref: $BASE"
+  MB=$(git merge-base "$BASE" HEAD) || die "no merge base for $BASE and HEAD"
+fi
+HAS_HEAD=0; git rev-parse --verify -q "HEAD^{commit}" >/dev/null && HAS_HEAD=1
+GLOBS=$(printf '%s' "$CFG" | jq -r '.exclude_globs[]')
+
+T=$(mktemp -d "${TMPDIR:-/tmp}/hotspots.XXXXXX") || die "mktemp failed"
+trap 'rm -rf "$T"' EXIT
+: > "$T/rows"
+# one history walk per file, 8 at a time: wall time is the slowest batch, not the sum
+i=0
+for p in "$@"; do
+  i=$((i+1))
+  [ "$HAS_HEAD" = 1 ] && [ -n "${p#./}" ] && { git rev-list --count --since=90.days HEAD -- "${p#./}" > "$T/c.$i" 2>/dev/null & }
+  [ $((i % 8)) -eq 0 ] && wait
+done
+wait
+i=0
+for p in "$@"; do
+  i=$((i+1))
+  p=${p#./}
+  [ -n "$p" ] || continue
+  lines=0; [ -f "$p" ] && lines=$(wc -l < "$p" | tr -d ' ')
+  commits=$(cat "$T/c.$i" 2>/dev/null); case "$commits" in ''|*[!0-9]*) commits=0 ;; esac
+  excluded=false
+  if git check-attr linguist-generated linguist-vendored -- "$p" 2>/dev/null | grep -qE ': (set|true)$'; then excluded=true; fi
+  if [ "$excluded" = false ] && [ -n "$GLOBS" ]; then
+    while IFS= read -r g; do
+      [ -n "$g" ] || continue
+      # shellcheck disable=SC2254
+      case "$p" in $g) excluded=true; break ;; esac
+    done <<EOF
+$GLOBS
+EOF
+  fi
+  base_lines=null; growth=null
+  if [ -n "$MB" ]; then
+    base_lines=0
+    git cat-file -e "$MB:$p" 2>/dev/null && base_lines=$(git show "$MB:$p" | wc -l | tr -d ' ')
+    growth=$((lines - base_lines))
+  fi
+  printf '%s\t%s\t%s\t%s\t%s\t%s\n' "$p" "$lines" "$commits" "$excluded" "$base_lines" "$growth" >> "$T/rows"
+done
+
+FILES=$(jq -R -s -c --argjson fl "$FILE_LINES" '
+  [split("\n")[] | select(length > 0) | split("\t") |
+   { path: .[0], lines: (.[1] | tonumber), commits_90d: (.[2] | tonumber) } as $r |
+   $r + { hotspot: ($r.lines * $r.commits_90d), over: ($r.lines > $fl), excluded: (.[3] == "true"),
+          base_lines: (.[4] | fromjson), growth: (.[5] | fromjson) }]' < "$T/rows")
+head_json "$FILES"

package/scripts/hotspots.test.sh

@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+# hotspots.test.sh — cases for scripts/hotspots.sh (forge#4195).
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+set -uo pipefail
+S="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/hotspots.sh"
+PASS=0; FAILN=0
+TMP="$(mktemp -d "${TMPDIR:-/tmp}/hotspots-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 }
+q() { printf '%s' "$OUT" | jq -c "$1"; }
+HAVE_YQ=1; yq -o=json '.' - <<<'a: 1' 2>/dev/null | grep -q '"a"' || HAVE_YQ=0
+
+new_repo() {
+  rm -rf "$TMP/w"; mkdir -p "$TMP/w"; cd "$TMP/w" || exit 1
+  git init -q -b main; git config user.email t@example.com; git config user.name t; git config commit.gpgsign false
+}
+commit() { git add -A; git commit -qm "$1"; }
+lines() { i=0; : > "$1"; while [ $i -lt "$2" ]; do echo "l$i" >> "$1"; i=$((i+1)); done; }
+
+# ---- 1. exact lines, commits_90d, hotspot, over; old commits outside the window are not counted ----
+new_repo
+lines big.py 2100; GIT_COMMITTER_DATE="2000-01-01T00:00:00Z" GIT_AUTHOR_DATE="2000-01-01T00:00:00Z" commit old
+echo x >> big.py; commit c1
+echo y >> big.py; lines small.py 10; commit c2
+OUT="$(bash "$S" big.py ./small.py missing/gone.py)"; rc=$?
+eq "rc" "$rc" 0
+eq "defaults" "$(q '[.enabled,.file_lines,.growth_lines]')" '[true,2000,150]'
+eq "big facts" "$(q '.files[0]')" '{"path":"big.py","lines":2102,"commits_90d":2,"hotspot":4204,"over":true,"excluded":false,"base_lines":null,"growth":null}'
+eq "small facts (./ stripped)" "$(q '.files[1] | [.path,.lines,.commits_90d,.over]')" '["small.py",10,1,false]'
+eq "missing file" "$(q '.files[2] | [.path,.lines,.commits_90d,.over]')" '["missing/gone.py",0,0,false]'
+OUT="$(bash "$S")"; eq "no paths" "$(q '.files')" '[]'
+
+# ---- 2. --base growth: merge-base side, new file counts from 0 ----
+git checkout -q -b feat
+lines extra 200; cat extra >> big.py; lines fresh.py 30; commit grow
+OUT="$(bash "$S" --base main -- big.py fresh.py)"
+eq "growth" "$(q '.files[0] | [.base_lines,.growth,.lines]')" '[2102,200,2302]'
+eq "new file growth" "$(q '.files[1] | [.base_lines,.growth]')" '[0,30]'
+bash "$S" --base no-such-ref big.py >/dev/null 2>&1; eq "bad ref exit" "$?" 2
+bash "$S" --base >/dev/null 2>&1; eq "usage exit" "$?" 2
+bash "$S" --bogus x >/dev/null 2>&1; eq "unknown option exit" "$?" 2
+
+# ---- 3. exclusions: linguist-generated, linguist-vendored, forge.yaml globs ----
+mkdir -p gen vendor/lib dist
+lines gen/api.py 2500; lines vendor/lib/x.js 2500; lines dist/bundle.js 2500
+printf 'gen/** linguist-generated\nvendor/** linguist-vendored=true\n' > .gitattributes
+commit gen
+OUT="$(bash "$S" gen/api.py vendor/lib/x.js dist/bundle.js big.py)"
+eq "attr exclusions" "$(q '[.files[] | .excluded]')" '[true,true,false,false]'
+if [ "$HAVE_YQ" = 1 ]; then
+  printf 'maintenance:\n  hotspot:\n    file_lines: 100\n    growth_lines: 5\n    exclude_globs: ["dist/*", "*.lock"]\n' > forge.yaml
+  OUT="$(bash "$S" dist/bundle.js small.py big.py)"
+  eq "config thresholds" "$(q '[.file_lines,.growth_lines]')" '[100,5]'
+  eq "glob exclusion" "$(q '[.files[] | .excluded]')" '[true,false,false]'
+  eq "over uses configured file_lines" "$(q '[.files[] | .over]')" '[true,false,true]'
+  printf 'maintenance:\n  hotspot:\n    enabled: false\n' > forge.yaml
+  OUT="$(bash "$S" big.py)"
+  eq "opt-out" "$(q '[.enabled,.files]')" '[false,[]]'
+  printf 'maintenance:\n  hotspot:\n    file_lines: nope\n' > forge.yaml
+  OUT="$(bash "$S" big.py)"; eq "bad value falls back" "$(q '.file_lines')" 2000
+  rm -f forge.yaml
+else
+  echo "SKIP: forge.yaml cases need mikefarah yq v4"
+fi
+# yq missing: defaults, still exit 0
+mkdir -p "$TMP/noyq"; printf '#!/bin/sh\nexit 1\n' > "$TMP/noyq/yq"; chmod +x "$TMP/noyq/yq"
+printf 'maintenance:\n  hotspot:\n    file_lines: 100\n' > forge.yaml
+OUT="$(PATH="$TMP/noyq:$PATH" bash "$S" big.py)"; eq "yq unusable: defaults" "$(q '.file_lines')" 2000
+rm -f forge.yaml
+
+# ---- 4. 30k-commit repo: exact counts under 1 s, no blob reads, no network ----
+rm -rf "$TMP/big"; git init -q -b main "$TMP/big"; cd "$TMP/big" || exit 1
+now=$(date +%s)
+awk -v now="$now" 'BEGIN { for (i = 1; i <= 30000; i++) {
+  ts = (i > 27000) ? now - (30000 - i) * 60 : now - 200 * 86400 - (27000 - i) * 600
+  print "commit refs/heads/main"; print "mark :" i; print "committer t <t@e> " ts " +0000"; print "data 1"; print "x"
+  if (i > 1) print "from :" (i - 1)
+  f = (i % 10 == 0) ? "hot.py" : "other" (i % 50) ".txt"; c = "line " i
+  print "M 644 inline " f; print "data " length(c) + 1; print c; print "" } }' | git fast-import --quiet
+git checkout -q main
+mkdir -p "$TMP/bin"
+for t in gh curl wget npm npx pnpm yarn nc ssh; do printf '#!/bin/sh\necho "%s" >> "%s/net.log"\nexit 1\n' "$t" "$TMP" > "$TMP/bin/$t"; chmod +x "$TMP/bin/$t"; done
+best=""
+for _ in 1 2 3; do
+  start=$(date +%s%N 2>/dev/null)
+  OUT="$(PATH="$TMP/bin:$PATH" GIT_TRACE2_EVENT="$TMP/trace.json" bash "$S" hot.py other1.txt other2.txt other3.txt)"
+  end=$(date +%s%N 2>/dev/null)
+  case "$start$end" in *N*|"") best=0; break ;; esac
+  ms=$(( (end - start) / 1000000 )); if [ -z "$best" ] || [ "$ms" -lt "$best" ]; then best=$ms; fi
+done
+eq "30k exact commits" "$(q '[.files[] | .commits_90d]')" '[300,60,60,60]'
+eq "30k exact lines" "$(q '[.files[] | .lines]')" '[1,1,1,1]'
+if [ "$best" -lt 1000 ]; then ok; else bad "30k-commit run took ${best} ms (limit 1000)"; fi
+grep -q '"rev-list"' "$TMP/trace.json" && ok || bad "git trace not captured"
+if grep -qE '"(cat-file|show)"' "$TMP/trace.json"; then bad "blob read without --base"; else ok; fi
+if [ -e "$TMP/net.log" ]; then bad "network tool invoked: $(tr '\n' ' ' < "$TMP/net.log")"; else ok; fi
+
+echo "hotspots.test.sh: $PASS passed, $FAILN failed"
+[ "$FAILN" -eq 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 ]