forgedock 1.2.0 → 1.4.0

package/scripts/check-admission-parity.mjs

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+/**
+ * CI parity check: bin/engine/admission.mjs's `CASCADE_PRESETS` table is the
+ * typed, unit-tested reference implementation of the cascade admission
+ * policy (forge#2234). The logic actually EXECUTED at runtime is a
+ * hand-written bash/yq mirror in commands/orchestrate/phase-4-execution.md's
+ * Step 4A.pre `case "$CASCADE_POLICY_NAME" in ... esac` block — the two are
+ * kept in sync by hand, with no automated check catching divergence
+ * (forge#2340). This script closes that gap: it imports the real
+ * `CASCADE_PRESETS` table and diffs it against the values parsed out of the
+ * bash mirror, failing non-zero on any mismatch.
+ *
+ * Usage: node scripts/check-admission-parity.mjs
+ */
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import path from "node:path";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, "..");
+const ADMISSION_MJS_PATH = path.join(REPO_ROOT, "bin/engine/admission.mjs");
+const SPEC_PATH = path.join(REPO_ROOT, "commands/orchestrate/phase-4-execution.md");
+
+/**
+ * Parse a single bash literal captured from the mirror's case arm into the
+ * same JS types `CASCADE_PRESETS` uses (number | "unlimited" | boolean).
+ * @param {string} raw
+ */
+function parseBashValue(raw) {
+  const trimmed = raw.trim().replace(/^"(.*)"$/, "$1");
+  if (trimmed === "true") return true;
+  if (trimmed === "false") return false;
+  if (trimmed === "unlimited") return "unlimited";
+  const n = Number(trimmed);
+  return Number.isFinite(n) && trimmed !== "" ? n : trimmed;
+}
+
+/**
+ * Extract each `PRESET_*` assignment from a single case-arm body.
+ * @param {string} body - text between `{name})` and the arm's `;;`
+ */
+function parseArmBody(body) {
+  const get = (key) => {
+    const m = body.match(new RegExp(`${key}=("?[^;"]*"?)`));
+    return m ? parseBashValue(m[1]) : undefined;
+  };
+  return {
+    maxGeneration: get("PRESET_MAX_GEN"),
+    tokenBudget: get("PRESET_TOKEN_BUDGET"),
+    deferOnBatchGated: get("PRESET_DEFER_GATED"),
+    keywordHeuristic: get("PRESET_KEYWORD"),
+    p3SameFileDefer: get("PRESET_P3_SAME_FILE"),
+  };
+}
+
+/**
+ * Isolate the `case "$CASCADE_POLICY_NAME" in ... esac` block and return a
+ * map of arm-name -> resolved preset object. The wildcard `*` fallback arm
+ * is excluded (it re-declares "balanced", not a distinct preset name).
+ */
+function extractBashMirrorPresets(specText) {
+  const caseMatch = specText.match(/case "\$CASCADE_POLICY_NAME" in([\s\S]*?)\nesac/);
+  if (!caseMatch) {
+    return null;
+  }
+  const caseBlock = caseMatch[1];
+
+  const armRe = /\n\s*([a-zA-Z0-9_*]+)\)([\s\S]*?);;/g;
+  const presets = {};
+  let m;
+  while ((m = armRe.exec(caseBlock))) {
+    const [, name, body] = m;
+    if (name === "*") continue; // wildcard fallback arm — not a named preset
+    presets[name] = parseArmBody(body);
+  }
+  return presets;
+}
+
+async function main() {
+  let admissionModule;
+  try {
+    // pathToFileURL is required for cross-platform dynamic import() of an absolute
+    // path — a bare Windows path like "C:\..." is not a valid ESM specifier and
+    // throws ERR_UNSUPPORTED_ESM_URL_SCHEME ("Only URLs with a scheme in: file,
+    // data, and node are supported"). POSIX absolute paths import fine either way,
+    // but file:// URLs work identically on both, so always convert.
+    admissionModule = await import(pathToFileURL(ADMISSION_MJS_PATH));
+  } catch (err) {
+    console.error(`ERROR: failed to import ${ADMISSION_MJS_PATH}: ${err.message}`);
+    process.exit(1);
+  }
+  const { CASCADE_PRESETS } = admissionModule;
+  if (!CASCADE_PRESETS) {
+    console.error(`ERROR: ${ADMISSION_MJS_PATH} does not export CASCADE_PRESETS — has it been renamed?`);
+    process.exit(1);
+  }
+
+  let specText;
+  try {
+    specText = readFileSync(SPEC_PATH, "utf8");
+  } catch (err) {
+    console.error(`ERROR: failed to read ${SPEC_PATH}: ${err.message}`);
+    process.exit(1);
+  }
+
+  const bashPresets = extractBashMirrorPresets(specText);
+  if (!bashPresets) {
+    console.error(
+      `ERROR: could not locate the case "$CASCADE_POLICY_NAME" in ... esac bash mirror block in ${SPEC_PATH}.`,
+    );
+    console.error(
+      "       (parity check has nothing to compare admission.mjs against — has the mirror been renamed or restructured?)",
+    );
+    process.exit(1);
+  }
+
+  let failed = false;
+  const mjsNames = Object.keys(CASCADE_PRESETS);
+  const bashNames = Object.keys(bashPresets);
+
+  for (const name of mjsNames) {
+    if (!(name in bashPresets)) {
+      console.error(
+        `MISMATCH: preset "${name}" exists in admission.mjs CASCADE_PRESETS but has no matching bash case arm in ${SPEC_PATH}`,
+      );
+      failed = true;
+      continue;
+    }
+    const mjsPreset = CASCADE_PRESETS[name];
+    const bashPreset = bashPresets[name];
+    for (const key of Object.keys(mjsPreset)) {
+      if (mjsPreset[key] !== bashPreset[key]) {
+        console.error(
+          `MISMATCH: preset "${name}".${key} — admission.mjs=${JSON.stringify(mjsPreset[key])} bash-mirror=${JSON.stringify(bashPreset[key])}`,
+        );
+        failed = true;
+      }
+    }
+  }
+
+  for (const name of bashNames) {
+    if (!(name in CASCADE_PRESETS)) {
+      console.error(
+        `MISMATCH: bash case arm "${name}" in ${SPEC_PATH} has no matching preset in admission.mjs CASCADE_PRESETS`,
+      );
+      failed = true;
+    }
+  }
+
+  if (failed) {
+    console.error("");
+    console.error(
+      "admission.mjs CASCADE_PRESETS and the phase-4-execution.md bash mirror have drifted out of sync.",
+    );
+    console.error(
+      "Update both together — see the admission.mjs module docstring and phase-4-execution.md Step 4A.pre ('Cascade admission policy resolution').",
+    );
+    process.exit(1);
+  }
+
+  console.log(
+    `OK: admission.mjs CASCADE_PRESETS matches the phase-4-execution.md bash mirror for: ${mjsNames.join(", ")}`,
+  );
+}
+
+main();

package/scripts/check-command-side-effects.sh

@@ -0,0 +1,376 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# check-command-side-effects.sh — Scan commands/**/*.md for two classes of
+#                                  spec-as-code side-effect defects.
+#
+# Command specs are spec-as-code: they drive autonomous side effects (auto-merge,
+# gh gist create, git push, label mutations, issue creation). This script catches
+# two defect classes before they reach staging:
+#
+#   Class A — Unconditionally prohibited patterns (full-corpus, always blocked):
+#     `gh gist create --public` or `gh gist edit --public` anywhere in a code block.
+#     Gists created by the pipeline MUST be secret — --public exposes private repo
+#     titles, root causes, and file paths to the world. (Ref: forge#1587)
+#
+#   Class B — Side-effect verbs in code blocks with no DRY_RUN/governor guard (diff-aware):
+#     When added lines introduce a side-effect verb (gh issue create, gh pr merge,
+#     git push, gh issue edit|comment, --auto-merge, --add/remove-label) inside a
+#     code block that has no guard expression (DRY_RUN, GOVERNOR, --dry-run)
+#     anywhere in THAT SAME code block, the change is flagged. Guard/side-effect
+#     correlation is scoped to the individual fenced code block, not the whole
+#     section — a guard mentioned in an unrelated code block elsewhere in the
+#     same section (before or after the flagged verb) does not silence the
+#     finding. (Ref: forge#2289 — a decoy guard anywhere in the section, in any
+#     code block, previously silenced detection of an actually-unguarded side
+#     effect in a different block of that same section.)
+#     Operates on the diff (GITHUB_BASE_SHA or HEAD^) to avoid flagging legacy corpus.
+#     (Ref: forge#1609 — signal-planner.md DRY_RUN guard placed after the create it guards)
+#
+# Allowlist: add <!-- allowlist:check-command-side-effects --> on the same line as
+# the side-effect verb to suppress that specific hit.
+#
+# Usage:
+#   check-command-side-effects.sh [--full] [<commands_dir>]
+#     --full         Scan entire corpus (not just diff) for Class A violations only.
+#                    Class B is diff-aware by design — --full does not change Class B.
+#     commands_dir   Path to the commands/ directory (default: ./commands)
+#
+# Environment:
+#   GITHUB_BASE_SHA   When set, used as the base commit for Class B diff mode.
+#
+# Exit codes:
+#   0  no violations found
+#   1  one or more violations found (listed to stderr)
+#   2  usage / dependency error
+#
+# <!-- Added: forge#1609 -->
+
+set -euo pipefail
+
+# ---------------------------------------------------------------------------
+# Argument parsing
+# ---------------------------------------------------------------------------
+
+FULL_MODE=0
+COMMANDS_DIR="./commands"
+
+for arg in "$@"; do
+  case "$arg" in
+    -h|--help)
+      sed -n '2,/^set -/p' "$0" | grep '^#' | sed 's/^# *//'
+      exit 0
+      ;;
+    --full) FULL_MODE=1 ;;
+    -*) echo "ERROR: unknown option: $arg" >&2; exit 2 ;;
+    *) COMMANDS_DIR="$arg" ;;
+  esac
+done
+
+if [ ! -d "$COMMANDS_DIR" ]; then
+  echo "ERROR: commands directory not found: $COMMANDS_DIR" >&2
+  echo "Usage: $0 [--full] [<commands_dir>]" >&2
+  exit 2
+fi
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+# Code fence marker — stored in variable to avoid backtick shell-expansion bugs.
+# Do NOT inline as grep -E '^[[:space:]]*\`\`\`' — escaped backticks in grep
+# patterns undergo shell expansion, turning the pattern into '^[[:space:]]*'
+# which matches every line. (forge#1609)
+FENCE='```'
+
+# Guard expressions: any occurrence in a section's code blocks marks it as guarded
+GUARD_PATTERN='DRY_RUN|GOVERNOR|--dry-run|DRY_RUN_MODE|DryRun'
+
+# Class B side-effect verbs (in code blocks)
+SIDE_EFFECT_PATTERN='gh[[:space:]]+(issue[[:space:]]+(create|edit|comment)|pr[[:space:]]+(merge|create|edit)|gist[[:space:]]+(create|edit))|git[[:space:]]+push|--auto-merge|--add-label|--remove-label'
+
+ALLOWLIST_TOKEN='allowlist:check-command-side-effects'
+
+VIOLATIONS=0
+
+# ---------------------------------------------------------------------------
+# Class A: Scan for gh gist create/edit --public in code blocks (full corpus)
+# This runs regardless of --full or diff mode.
+# ---------------------------------------------------------------------------
+
+class_a_scan() {
+  local file="$1"
+  local IN_CB=0
+  local HAS_GIST=0
+  local BLOCK_LINES=""
+  local BLOCK_START=0
+  local LN=0
+  local line PUBLIC_LN ACTUAL_LINE IS_FENCE IS_BARE
+
+  # flush_a_block — evaluate the currently-accumulated block's HAS_GIST/
+  # BLOCK_LINES state for a 'gh gist create/edit --public' violation, then
+  # reset it. Defined inside class_a_scan (not at file scope) so it shares
+  # this invocation's `local` variables via bash's dynamic scoping — the same
+  # mechanism Class B's flush_block() relies on for its own loop-local state.
+  # Called from two sites: (1) the existing fence-close path below, when a
+  # bare fence brings IN_CB back to 0, and (2) once more, defensively, after
+  # the read loop ends — covering a file that ends with an unterminated
+  # fence (IN_CB still > 0 at EOF), which previously discarded any
+  # accumulated violation silently. (forge#2289 added the equivalent
+  # end-of-file flush for Class B only; this closes the same gap in Class A.)
+  flush_a_block() {
+    if [ "$HAS_GIST" -eq 1 ] && echo "$BLOCK_LINES" | grep -qE '^[[:space:]]*--public([[:space:]]|$)'; then
+      # Find the line number of --public within the block
+      PUBLIC_LN=$(echo "$BLOCK_LINES" | grep -n '^[[:space:]]*--public' | head -1 | cut -d: -f1)
+      ACTUAL_LINE=$((BLOCK_START + PUBLIC_LN))
+      if ! echo "$BLOCK_LINES" | grep -qF "$ALLOWLIST_TOKEN"; then
+        echo "HIGH | $file | line ~$ACTUAL_LINE | Class A: 'gh gist create/edit --public' in code block — gists MUST be secret (omit --public); --public exposes private repo data. (forge#1587)" >&2
+        VIOLATIONS=$((VIOLATIONS + 1))
+      fi
+    fi
+    HAS_GIST=0
+    BLOCK_LINES=""
+  }
+
+  while IFS= read -r line; do
+    LN=$((LN + 1))
+
+    # Fence detection is anchored to line-start (ignoring leading whitespace).
+    # IN_CB is a true nesting-DEPTH counter, not a 0/1 flag: a fence line
+    # carrying an info string (e.g. a nested ```bash) while already inside a
+    # block opens one more nesting level (increment); a bare fence (nothing
+    # after the backticks but optional trailing whitespace) closes exactly
+    # one level (decrement). The accumulated block is only evaluated once
+    # depth returns to 0 — i.e. once the OUTERMOST fence has actually closed,
+    # not merely an inner one. A binary flag cannot distinguish "still inside
+    # the outer fence, past an inner fence's close" from "outside all
+    # fences"; depth tracking can. (forge#2210 fixed anchoring/info-string-is-
+    # content; forge#2288 adds true depth so 2+ nesting levels close correctly.)
+    IS_FENCE=0
+    IS_BARE=0
+    if echo "$line" | grep -qE "^[[:space:]]*${FENCE}"; then
+      IS_FENCE=1
+      if echo "$line" | grep -qE "^[[:space:]]*${FENCE}[[:space:]]*\$"; then
+        IS_BARE=1
+      fi
+    fi
+
+    if [ "$IN_CB" -eq 0 ]; then
+      if [ "$IS_FENCE" -eq 1 ]; then
+        IN_CB=1
+        HAS_GIST=0
+        BLOCK_LINES=""
+        BLOCK_START=$LN
+      fi
+      continue
+    fi
+
+    # IN_CB >= 1 — inside a block, possibly nested.
+    if [ "$IS_FENCE" -eq 1 ]; then
+      if [ "$IS_BARE" -eq 1 ]; then
+        IN_CB=$((IN_CB - 1))
+      else
+        IN_CB=$((IN_CB + 1))
+      fi
+      if [ "$IN_CB" -eq 0 ]; then
+        # Fully closed (outermost fence) — evaluate the accumulated block now.
+        flush_a_block
+        continue
+      fi
+      # Still inside (nested transition) — the fence line itself is block content.
+      BLOCK_LINES="${BLOCK_LINES}${line}
+"
+      continue
+    fi
+
+    # Regular content line while inside (at any depth).
+    BLOCK_LINES="${BLOCK_LINES}${line}
+"
+    # Check if this line has gh gist create/edit (even with line continuation \)
+    if echo "$line" | grep -qE 'gh[[:space:]]+gist[[:space:]]+(create|edit)'; then
+      HAS_GIST=1
+    fi
+  done < "$file"
+
+  # Defensive final flush — evaluates any block state left accumulated if the
+  # file ended with an unterminated fence (IN_CB never returned to 0). A
+  # no-op if the last block already closed and was flushed above. Mirrors
+  # Class B's identical end-of-file `flush_block` call. (forge#2305)
+  flush_a_block
+}
+
+while IFS= read -r file; do
+  [ -f "$file" ] || continue
+  class_a_scan "$file"
+done < <(find "$COMMANDS_DIR" -name '*.md' | sort)
+
+# ---------------------------------------------------------------------------
+# Class B: Diff-aware scan for unguarded side-effect verbs in added lines
+# ---------------------------------------------------------------------------
+
+# Determine base SHA for diff
+BASE_SHA=""
+if [ -n "${GITHUB_BASE_SHA:-}" ]; then
+  BASE_SHA="$GITHUB_BASE_SHA"
+elif [ -n "${GITHUB_EVENT_PULL_REQUEST_BASE_SHA:-}" ]; then
+  BASE_SHA="$GITHUB_EVENT_PULL_REQUEST_BASE_SHA"
+else
+  BASE_SHA="$(git rev-parse HEAD^ 2>/dev/null || echo '')"
+fi
+
+if [ -z "$BASE_SHA" ]; then
+  echo "INFO: No git base SHA available — Class B (diff-aware) check skipped" >&2
+else
+  # Get list of changed command spec files
+  CHANGED_SPECS=$(git diff --name-only "$BASE_SHA"...HEAD -- "${COMMANDS_DIR}" 2>/dev/null \
+    | grep -E '\.md$' | grep -v '^$' || true)
+
+  if [ -z "$CHANGED_SPECS" ]; then
+    echo "OK (Class B): No commands/*.md files changed — diff check skipped"
+  else
+    echo "Class B: Checking changed spec files for unguarded side-effect verbs:"
+    echo "$CHANGED_SPECS"
+    echo ""
+
+    while IFS= read -r file; do
+      [ -f "$file" ] || continue
+
+      # Get added lines for this file
+      ADDED_CONTENT=$(git diff "$BASE_SHA"...HEAD -- "$file" 2>/dev/null \
+        | grep '^+' | grep -v '^+++' | sed 's/^+//' || true)
+
+      # Skip if no added lines contain side-effect verbs
+      if ! echo "$ADDED_CONTENT" | grep -qE "$SIDE_EFFECT_PATTERN"; then
+        continue
+      fi
+
+      # Parse the full file to map code blocks → (has_guard, has_side_effect_in_added_lines).
+      # SECTION is tracked only as a human-readable label for the violation message —
+      # it plays NO role in guard/side-effect correlation. Correlation is scoped to
+      # the individual fenced code block (BLOCK_* state), reset on every block open
+      # and evaluated on every block close, so a guard mentioned in a different code
+      # block — even one earlier or later in the very same section — cannot silence
+      # an unguarded side effect in another block. (forge#2289)
+      IN_CB=0
+      SECTION="(top)"
+      BLOCK_HAS_GUARD=0
+      BLOCK_HAS_ADDED_SE=0
+      BLOCK_SE_LINE=0
+      BLOCK_SE_VERB=""
+      LN=0
+
+      flush_block() {
+        # Evaluate and reset the current code block's guard/side-effect state.
+        # Called whenever a fenced code block's outermost fence closes (depth
+        # returns to 0), and once more, defensively, at end-of-file to cover a
+        # malformed/unterminated block (mirrors the pre-forge#2289 behavior of
+        # unconditionally evaluating accumulated state before resetting).
+        if [ "$BLOCK_HAS_ADDED_SE" -eq 1 ] && [ "$BLOCK_HAS_GUARD" -eq 0 ]; then
+          echo "HIGH | $file | line $BLOCK_SE_LINE | Class B: side-effect '$BLOCK_SE_VERB' added in section '$SECTION' with no DRY_RUN/governor guard in the same code block — add a guard inside this code block or wrap the effect in a DRY_RUN check" >&2
+          VIOLATIONS=$((VIOLATIONS + 1))
+        fi
+        BLOCK_HAS_GUARD=0
+        BLOCK_HAS_ADDED_SE=0
+        BLOCK_SE_LINE=0
+        BLOCK_SE_VERB=""
+      }
+
+      while IFS= read -r line; do
+        LN=$((LN + 1))
+
+        # Code block fence — checked BEFORE the heading test so IN_CB reflects
+        # this line's actual state. IN_CB is a true nesting-DEPTH counter, not
+        # a 0/1 flag: a fence line carrying an info string (e.g. nested
+        # ```bash) encountered while already inside a block opens one more
+        # nesting level (increment); a bare fence (nothing after the
+        # backticks) closes exactly one level (decrement). Heading detection
+        # below only fires once depth returns to 0 — i.e. once we are outside
+        # ALL fences, not merely an inner one. A binary flag cannot
+        # distinguish "still inside the outer fence, past an inner fence's
+        # close" from "outside all fences"; this is exactly the gap that let
+        # embedded `## Step N` headers inside one continuous outer code block
+        # (e.g. commands/review-pr-agents/spec-cli.md) be misdetected as real
+        # section boundaries. (forge#2210 fixed anchoring/info-string-is-
+        # content for a single nesting level; forge#2288 adds true depth so
+        # 2+ nesting levels close correctly.)
+        IS_FENCE=0
+        IS_BARE=0
+        if echo "$line" | grep -qE "^[[:space:]]*${FENCE}"; then
+          IS_FENCE=1
+          if echo "$line" | grep -qE "^[[:space:]]*${FENCE}[[:space:]]*\$"; then
+            IS_BARE=1
+          fi
+        fi
+
+        if [ "$IN_CB" -eq 0 ]; then
+          if [ "$IS_FENCE" -eq 1 ]; then
+            IN_CB=1
+            continue
+          fi
+
+          # Section heading — label-only update (forge#2210). This no longer
+          # flushes guard/side-effect state: that state is now block-scoped
+          # (forge#2289) and is always already at rest here, since this branch
+          # is only reached when IN_CB is 0 — i.e. any block that was open has
+          # already been closed and flushed at its own fence-close below.
+          if echo "$line" | grep -qE '^#{1,6}[[:space:]]+'; then
+            heading=$(echo "$line" | sed 's/^#*[[:space:]]*//' | sed 's/[[:space:]]*$//')
+            SECTION="$heading"
+            continue
+          fi
+          continue
+        fi
+
+        # IN_CB >= 1 — inside a block, possibly nested.
+        if [ "$IS_FENCE" -eq 1 ]; then
+          if [ "$IS_BARE" -eq 1 ]; then
+            IN_CB=$((IN_CB - 1))
+          else
+            IN_CB=$((IN_CB + 1))
+          fi
+          if [ "$IN_CB" -eq 0 ]; then
+            # Outermost fence just closed — evaluate this block's guard/SE
+            # correlation now, before starting the next block. (forge#2289)
+            flush_block
+          fi
+          continue
+        fi
+
+        # Content line while inside (at any depth).
+        if echo "$line" | grep -qF "$ALLOWLIST_TOKEN"; then continue; fi
+
+        # Check for guard — scoped to THIS code block only (forge#2289)
+        echo "$line" | grep -qE "$GUARD_PATTERN" && BLOCK_HAS_GUARD=1
+
+        # Check if this line is in the diff's added lines AND has a side-effect verb
+        if [ "$BLOCK_HAS_ADDED_SE" -eq 0 ] && echo "$line" | grep -qE "$SIDE_EFFECT_PATTERN"; then
+          # Is this specific line in the added content?
+          if echo "$ADDED_CONTENT" | grep -qF "${line:0:80}" 2>/dev/null; then
+            BLOCK_HAS_ADDED_SE=1
+            BLOCK_SE_LINE=$LN
+            BLOCK_SE_VERB=$(echo "$line" | grep -oE "$SIDE_EFFECT_PATTERN" | head -1 || echo "side-effect")
+          fi
+        fi
+      done < "$file"
+
+      # Defensive final flush — evaluates any block state left accumulated if
+      # the file ended with an unterminated fence (malformed input); a no-op
+      # if the last block already closed and was flushed above.
+      flush_block
+
+    done <<< "$CHANGED_SPECS"
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# Summary
+# ---------------------------------------------------------------------------
+
+if [ "$VIOLATIONS" -gt 0 ]; then
+  echo "check-command-side-effects: $VIOLATIONS violation(s) found. See stderr for details." >&2
+  exit 1
+fi
+
+echo "OK: No side-effect violations found"
+exit 0

package/scripts/check-phase-registry-drift.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+/**
+ * CI drift check: bin/engine/phases.mjs's `PHASES` array (the authoritative
+ * engine phase table) must have exactly the same phase-id list, in the same
+ * order, as packages/protocol/src/phases.js's `PHASE_IDS` — the single-source
+ * registry both bin/engine/phases.mjs and bin/hooks/interactive-engine.mjs
+ * import their marker strings from (forge#2378).
+ *
+ * This does NOT re-validate the marker *strings* themselves — both consumer
+ * files import the registry directly, so a string-level mismatch between them
+ * is now structurally impossible (there is exactly one literal declaration of
+ * each marker, in packages/protocol/src/phases.js / types.js). What CAN still
+ * drift is the *phase-id list itself*: someone adds/removes/reorders a phase
+ * in bin/engine/phases.mjs's PHASES array without updating the registry's
+ * PHASE_IDS (or vice versa). This script catches that.
+ *
+ * Usage: node scripts/check-phase-registry-drift.mjs
+ * Exit codes: 0 = no drift, 1 = drift detected, 2 = usage/import error.
+ */
+
+import { fileURLToPath, pathToFileURL } from "node:url";
+import path from "node:path";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, "..");
+
+async function main() {
+  let registryModule;
+  let phasesModule;
+  try {
+    registryModule = await import(
+      pathToFileURL(path.join(REPO_ROOT, "packages/protocol/src/phases.js")).href
+    );
+  } catch (err) {
+    console.error(`ERROR: failed to import packages/protocol/src/phases.js: ${err.message}`);
+    process.exit(2);
+  }
+  try {
+    phasesModule = await import(
+      pathToFileURL(path.join(REPO_ROOT, "bin/engine/phases.mjs")).href
+    );
+  } catch (err) {
+    console.error(`ERROR: failed to import bin/engine/phases.mjs: ${err.message}`);
+    process.exit(2);
+  }
+
+  const registryIds = registryModule.PHASE_IDS;
+  const enginePhaseIds = (phasesModule.PHASES || []).map((p) => p.id);
+
+  if (!Array.isArray(registryIds)) {
+    console.error("ERROR: packages/protocol/src/phases.js did not export a PHASE_IDS array.");
+    process.exit(2);
+  }
+  if (!Array.isArray(enginePhaseIds) || enginePhaseIds.length === 0) {
+    console.error("ERROR: bin/engine/phases.mjs did not export a non-empty PHASES array.");
+    process.exit(2);
+  }
+
+  const drifted =
+    registryIds.length !== enginePhaseIds.length ||
+    registryIds.some((id, i) => id !== enginePhaseIds[i]);
+
+  if (drifted) {
+    console.error("ERROR: phase-id list drift detected between the registry and the engine.");
+    console.error(`  packages/protocol/src/phases.js PHASE_IDS: ${JSON.stringify(registryIds)}`);
+    console.error(`  bin/engine/phases.mjs PHASES ids:          ${JSON.stringify(enginePhaseIds)}`);
+    console.error("  Update packages/protocol/src/phases.js's PHASE_IDS to match bin/engine/phases.mjs's");
+    console.error("  PHASES array (or vice versa) so the two stay single-sourced. See forge#2378.");
+    process.exit(1);
+  }
+
+  // Also verify every registry marker entry that has a `completionMarker` or
+  // `completionLabel` field is a non-empty string — catches an accidental
+  // undefined/null slipping in (e.g. a typo'd RESERVED_TYPES key whose
+  // completionSentinel is null) which would otherwise fail silently at
+  // has(blob, undefined) → substring "undefined" never matches, masking a
+  // real bug as "phase never completes".
+  const emptyMarkers = [];
+  for (const [phaseId, entry] of Object.entries(registryModule.PHASE_MARKERS || {})) {
+    const marker = entry.completionMarker ?? entry.completionLabel;
+    if (typeof marker !== "string" || marker.length === 0) {
+      emptyMarkers.push(phaseId);
+    }
+  }
+  if (emptyMarkers.length > 0) {
+    console.error(
+      `ERROR: PHASE_MARKERS entries with no usable completionMarker/completionLabel: ${emptyMarkers.join(", ")}`
+    );
+    process.exit(1);
+  }
+
+  console.log("OK: phase-id list and marker registry are consistent (no drift detected).");
+  process.exit(0);
+}
+
+main();