@codyswann/lisa 3.62.0 → 3.64.0

package/scripts/lisa-github-rulesets.sh

@@ -44,6 +44,25 @@ PROJECT_PATH=""
 UNCHANGED_COUNT=0
 APPLIED_PAYLOAD=""
 
+# The temp file holding the config-derived `base` ruleset, cleaned up on exit.
+GENERATED_RULESET=""
+
+# Delete the generated ruleset, but ONLY when the top-level shell exits.
+#
+# A command substitution runs in a subshell that inherits this EXIT trap and
+# fires it on the subshell's exit. Without the pid guard the very next
+# `$(collect_templates ...)` deleted the file that had just been generated, and
+# the applier then read an empty template, resolved its name to the empty
+# string, and reported "Skipping ruleset '' — no applicable rules" while
+# exiting 0. That is the whole failure mode this change exists to prevent, one
+# layer down: a run that reports success having applied no branch protection.
+cleanup_generated_ruleset() {
+  [[ "$BASHPID" == "$$" ]] || return 0
+  [[ -n "$GENERATED_RULESET" ]] && rm -f "$GENERATED_RULESET"
+  return 0
+}
+trap cleanup_generated_ruleset EXIT
+
 # Project type hierarchy (child -> parent)
 # Using a function to avoid associative array issues with set -u
 get_parent_type() {
@@ -141,6 +160,14 @@ check_prerequisites() {
     missing+=("jq")
   fi
 
+  # The `base` ruleset is no longer a shipped JSON file; it is generated from
+  # .lisa.config.json by scripts/lisa-ruleset-payload.mjs. Without node there
+  # is no branch protection to apply at all, so this is a hard prerequisite
+  # rather than a degraded mode.
+  if ! command -v node &> /dev/null; then
+    missing+=("node")
+  fi
+
   if [[ ${#missing[@]} -gt 0 ]]; then
     log_error "Missing required tools: ${missing[*]}"
     exit 1
@@ -362,14 +389,22 @@ strip_config_dropped_checks() {
 # report, and a required check that never reports blocks every pull request
 # forever (the #2476 "aspirational seed a guard then trusts" defect).
 #
-# Keyed by ruleset name, because more than one shipped template carries a
-# required_status_checks rule (`base` and `quality checks` both do) and an
-# unkeyed list could not say which one it meant:
-#   { "github": { "rulesets": { "addRequiredChecks": {
+# Keyed by ruleset name, because more than one ruleset carries a
+# required_status_checks rule (the generated `base` and `quality checks` both
+# do) and an unkeyed list could not say which one it meant:
+#   { "github": { "rulesets": { "requiredChecks": {
 #       "quality checks": [
 #         { "context": "🧩 Plugin artifacts match source", "integration_id": 15368 }
 #       ] } } } }
 #
+# `requiredChecks` is DECLARATIVE where the retired `addRequiredChecks` was
+# additive: naming a ruleset here also stops the applier unioning that
+# ruleset's LIVE required list back into the payload. Additive-only could add a
+# context and never remove one, so a required check outlived the job that
+# posted it and the only way to drop it was the admin console. `addRequiredChecks`
+# is still read so installed projects keep applying, with a warning naming its
+# replacement.
+#
 # `integration_id` is optional and defaults to GitHub Actions. Contexts already
 # present are not duplicated, and a ruleset with no required_status_checks rule
 # gets one created so an addition is never silently dropped.
@@ -380,24 +415,62 @@ strip_config_dropped_checks() {
 # on a repository with no workflows can never report, and would block every pull
 # request), and naming the same context in both lists is operator error whose
 # safe resolution is to drop it rather than to require it.
-add_config_required_checks() {
-  local json="$1"
-  local project_path="$2"
-  local ruleset_name="$3"
+
+# The declared required-check list for one ruleset, or "[]" when none.
+# Prefers the declarative key and falls back to the retired additive one.
+config_required_checks() {
+  local project_path="$1"
+  local ruleset_name="$2"
   local config="$project_path/.lisa.config.json"
 
   if [[ ! -f "$config" ]]; then
-    echo "$json"
+    echo "[]"
     return 0
   fi
 
-  local added
-  if ! added=$(jq -c --arg name "$ruleset_name" \
-    '.github.rulesets.addRequiredChecks[$name] // []' "$config" 2>/dev/null); then
+  local declared
+  if ! declared=$(jq -c --arg name "$ruleset_name" \
+    '.github.rulesets.requiredChecks[$name] // null' "$config" 2>/dev/null); then
     log_warning ".lisa.config.json could not be parsed — ignoring github.rulesets overrides" >&2
-    added="[]"
+    echo "[]"
+    return 0
+  fi
+
+  if [[ "$declared" != "null" ]]; then
+    echo "$declared"
+    return 0
   fi
 
+  local legacy
+  legacy=$(jq -c --arg name "$ruleset_name" \
+    '.github.rulesets.addRequiredChecks[$name] // []' "$config" 2>/dev/null) || legacy="[]"
+  if [[ "$legacy" != "[]" && "$legacy" != "null" ]]; then
+    log_warning "github.rulesets.addRequiredChecks is retired — rename it to requiredChecks, which can also STOP requiring a context" >&2
+  fi
+  echo "$legacy"
+}
+
+# True when config states this ruleset's required list, so the live list must
+# NOT be unioned back in. That union is what made removal impossible.
+ruleset_checks_are_declared() {
+  local project_path="$1"
+  local ruleset_name="$2"
+  local config="$project_path/.lisa.config.json"
+
+  [[ -f "$config" ]] || return 1
+  jq -e --arg name "$ruleset_name" \
+    '(.github.rulesets.requiredChecks[$name] // null) | type == "array"' \
+    "$config" &> /dev/null
+}
+
+add_config_required_checks() {
+  local json="$1"
+  local project_path="$2"
+  local ruleset_name="$3"
+
+  local added
+  added=$(config_required_checks "$project_path" "$ruleset_name")
+
   if [[ "$added" == "[]" || "$added" == "null" ]]; then
     echo "$json"
     return 0
@@ -526,6 +599,27 @@ ruleset_is_current() {
     covers($live; $want)' > /dev/null
 }
 
+# The contexts the live ruleset requires that the outgoing payload does not.
+# The mirror of ruleset_added_contexts, and it exists because a declarative
+# required-check list can now REMOVE a requirement. Losing a protection is the
+# more consequential of the two directions, so it is never merely "applied".
+ruleset_removed_contexts() {
+  local live="$1"
+  local payload="$2"
+
+  jq -r -n --argjson live "${live:-null}" --argjson want "$payload" '
+    def contexts:
+      [ (.rules // [])[]
+        | select(.type == "required_status_checks")
+        | (.parameters.required_status_checks // [])[]
+        | .context ];
+
+    ($want | contexts) as $want_contexts
+    | (if $live == null then [] else ($live | contexts) end)
+    | map(select(. as $context | ($want_contexts | index($context)) | not))
+    | .[]'
+}
+
 # Print one line per context this run makes blocking. Reads the payload that
 # GitHub actually ACCEPTED, so a context dropped by the integration fallback is
 # never reported as added.
@@ -539,6 +633,20 @@ report_added_contexts() {
   done < <(ruleset_added_contexts "$live" "$payload")
 }
 
+# Print one line per context this run stops requiring, by name. A declarative
+# list that quietly dropped a check would read in the audit log as a routine
+# reconciliation, which is exactly how a guarantee disappears without anyone
+# deciding to give it up.
+report_removed_contexts() {
+  local live="$1"
+  local payload="$2"
+
+  local context
+  while IFS= read -r context; do
+    [[ -n "$context" ]] && log_warning "  - no longer required: $context (nothing in .lisa.config.json declares it)"
+  done < <(ruleset_removed_contexts "$live" "$payload")
+}
+
 apply_ruleset() {
   local repo="$1"
   local template_file="$2"
@@ -570,7 +678,29 @@ apply_ruleset() {
       log_warning "Could not read existing ruleset '$ruleset_name' details — refusing to silently replace required checks"
       return 1
     fi
-    clean_template=$(preserve_live_required_checks "$live" "$clean_template")
+    # Union the live required list back in UNLESS config states it. Preserving
+    # it is the right default — the live list carries external app checks
+    # nothing declares, and replacing it silently would strip protection. But a
+    # project that names a ruleset in `requiredChecks` has said what it wants
+    # required there, and honouring the union in that case is precisely what
+    # made `addRequiredChecks` unable to remove anything.
+    #
+    # The generated `base` ruleset gets NO exemption from this. It was tempting:
+    # its payload is entirely config-derived, so unioning the live list back in
+    # means an await removed from config does not stop being required. But the
+    # exemption would make removal unconditional on every run of a script
+    # `lisa-github-repo-setup.sh` invokes with `--yes`, so any context required
+    # today that no gate awaits and no `requiredChecks.base` names would be
+    # deleted with no operator ever opting in. That is the mirror of the rule
+    # `lisa-reconcile-policy.mjs` states in its own header — an EXTRA context is
+    # reported, never removed without `--prune` — and a protection lost by
+    # default reads in the audit log as a routine reconciliation. So `base`
+    # becomes declarative the same way every other ruleset does: by being named.
+    if ruleset_checks_are_declared "$project_path" "$ruleset_name"; then
+      log_verbose "Required checks for '$ruleset_name' are declared in .lisa.config.json — the live list is not preserved"
+    else
+      clean_template=$(preserve_live_required_checks "$live" "$clean_template")
+    fi
   fi
 
   # Idempotence: a run that would change nothing must say so and send nothing,
@@ -588,6 +718,7 @@ apply_ruleset() {
       log_info "[DRY RUN] Would create ruleset '$ruleset_name'"
     fi
     report_added_contexts "$live" "$clean_template"
+    report_removed_contexts "$live" "$clean_template"
     log_verbose "Template: $template_file"
     return 0
   fi
@@ -601,6 +732,7 @@ apply_ruleset() {
   APPLIED_PAYLOAD=""
   if apply_with_integration_fallback "$repo" "$ruleset_name" "$clean_template" "$existing_id"; then
     report_added_contexts "$live" "${APPLIED_PAYLOAD:-$clean_template}"
+    report_removed_contexts "$live" "${APPLIED_PAYLOAD:-$clean_template}"
     return 0
   fi
   log_error "Failed to apply ruleset '$ruleset_name'"
@@ -690,6 +822,50 @@ apply_with_integration_fallback() {
 # Main Logic
 ##############################################################################
 
+# Build the `base` ruleset from .lisa.config.json into a temp file.
+#
+# `all/github-rulesets/base.json` used to be a shipped template here. Seven of
+# its fields were already declared in `.lisa.config.json`, so two writers set
+# the same settings and the last one won; four more could not be declared at
+# all; and it pinned two vendor status checks every repository inherited and
+# none could drop. It is now generated, from one declaration, per project.
+#
+# A failure here is fatal rather than a skip. The alternative is applying every
+# OTHER ruleset and reporting success while the repository has no branch
+# protection, which is the shape of failure this whole change exists to stop.
+generate_base_ruleset() {
+  local project_path="$1"
+  local generator="$LISA_ROOT/scripts/lisa-ruleset-payload.mjs"
+  local out
+
+  if [[ ! -f "$generator" ]]; then
+    log_error "Missing $generator — the base ruleset is generated from .lisa.config.json and cannot be applied without it"
+    return 1
+  fi
+
+  out="$(mktemp)"
+  if ! node "$generator" --project="$project_path" > "$out" 2>"$out.err"; then
+    log_error "Could not build the base ruleset from .lisa.config.json:"
+    log_error "$(cat "$out.err")"
+    rm -f "$out" "$out.err"
+    return 1
+  fi
+  rm -f "$out.err"
+
+  # A generator that exits 0 having printed nothing is the failure this guard
+  # exists for: the applier would read an empty template, resolve its name to
+  # the empty string, skip it as "no applicable rules", and exit 0 having
+  # applied no branch protection at all. Measured — a symlinked path made the
+  # generator's own entry-point guard false. Never trust the exit code alone.
+  if ! jq -e '(.name | type == "string" and length > 0) and ((.rules // []) | length) > 0' "$out" &> /dev/null; then
+    log_error "The generated base ruleset is empty or has no name — refusing to continue with no branch protection to apply"
+    rm -f "$out"
+    return 1
+  fi
+
+  echo "$out"
+}
+
 collect_templates() {
   local -a types=("$@")
   local -a templates=()
@@ -789,18 +965,22 @@ main() {
     log_info "Detected types: ${expanded_types[*]}"
   fi
 
+  # Build the config-derived base ruleset first, so it is applied before any
+  # template and a failure to build it stops the run before anything is written.
+  if ! GENERATED_RULESET=$(generate_base_ruleset "$PROJECT_PATH"); then
+    exit 1
+  fi
+  log_verbose "Generated base ruleset from .lisa.config.json"
+
   # Collect templates
   local templates_str
   templates_str=$(collect_templates "${expanded_types[@]}")
 
-  local -a templates=()
+  local -a templates=("$GENERATED_RULESET")
+  local -a extra_templates=()
   if [[ -n "$templates_str" ]]; then
-    read -ra templates <<< "$templates_str"
-  fi
-
-  if [[ ${#templates[@]} -eq 0 ]]; then
-    log_warning "No ruleset templates found"
-    exit 0
+    read -ra extra_templates <<< "$templates_str"
+    templates+=("${extra_templates[@]}")
   fi
 
   log_info "Found ${#templates[@]} ruleset template(s)"

package/scripts/lisa-ruleset-payload.mjs

@@ -0,0 +1,376 @@
+#!/usr/bin/env node
+
+/**
+ * @file Build the `base` branch-ruleset payload from resolved Lisa config.
+ *
+ * This replaces `all/github-rulesets/base.json`, a shipped template that did
+ * two jobs badly.
+ *
+ * Seven of its fields were ALREADY declared in `.lisa.config.json`'s `policy`
+ * block — deletion, non-fast-forward, thread resolution, stale-review
+ * dismissal, last-push approval, allowed merge methods, strict status checks.
+ * Two writers therefore set the same settings from two files, whichever ran
+ * last won, and nothing compared them. Four more fields — `bypass_actors`, the
+ * `ref_name` conditions, `required_approving_review_count`, `enforcement` —
+ * could not be declared in config at all, so the template's values were a
+ * fleet-wide lock no project could override.
+ *
+ * And it pinned two vendor status checks by integration id, which every
+ * repository inherited and none could drop, because the only config hook was
+ * `github.rulesets.addRequiredChecks` — additive by construction. A project
+ * proving credential leakage with a different scanner had no way to say so,
+ * and a required context that nothing posts blocks every pull request in that
+ * repository forever.
+ *
+ * ## Where the required checks come from now
+ *
+ * From `await` gate declarations, a mode `lisa-gates.mjs` has always carried
+ * and nothing used. An awaited gate names a signal somebody else posts:
+ *
+ * ```json
+ * "credential-leakage": {
+ *   "pull-request": {
+ *     "level": "required",
+ *     "await": "GitGuardian Security Checks",
+ *     "posted_by": 46505
+ *   }
+ * }
+ * ```
+ *
+ * `contextsFor` already emits an awaited gate's context verbatim rather than
+ * deriving `<workflow> / <label>`, so the same declaration feeds the branch
+ * ruleset, the CI façade, and `lisa-reconcile-policy.mjs`'s drift comparison.
+ * Declaring nothing requires nothing: that is the override the template could
+ * not express.
+ *
+ * ## Defaults are the old template, minus its vendors
+ *
+ * A project with no `policy` block gets exactly the ruleset `base.json`
+ * described, EXCEPT its two vendor checks. That is the deliberate difference:
+ * the shape was never the objectionable part, the un-droppable vendor lock was.
+ *
+ * Usage:
+ *   lisa-ruleset-payload.mjs [--project=PATH] [--moment=pull-request]
+ * @module lisa-ruleset-payload
+ */
+
+import { invokedAsScript } from "../all/copy-overwrite/scripts/lib/invoked-as-script.mjs";
+import {
+  readGates,
+  resolveMoment,
+} from "../all/copy-overwrite/scripts/lisa-gates.mjs";
+
+/**
+ * The ruleset this module builds.
+ *
+ * Named rather than inferred because `lisa-reconcile-policy.mjs` compares the
+ * declared `policy.ruleset` block against ONE live ruleset's shape, and a
+ * comparison that guessed which one would report drift against whichever
+ * ruleset happened to sort first.
+ */
+export const POLICY_RULESET_NAME = "base";
+
+/**
+ * The ruleset shape a project inherits when it declares none.
+ *
+ * Field-for-field the retired `all/github-rulesets/base.json`, so deleting the
+ * template changes nothing for a project that declared nothing. The one
+ * omission is its `required_status_checks` list: those two contexts are now
+ * `await` declarations, and a default would put the lock straight back.
+ */
+export const RULESET_DEFAULTS = Object.freeze({
+  enforcement: "active",
+  include_refs: Object.freeze([
+    "~DEFAULT_BRANCH",
+    "refs/heads/dev",
+    "refs/heads/staging",
+    "refs/heads/main",
+  ]),
+  exclude_refs: Object.freeze([]),
+  bypass_actors: Object.freeze([
+    Object.freeze({
+      actor_id: null,
+      actor_type: "DeployKey",
+      bypass_mode: "always",
+    }),
+    Object.freeze({
+      actor_id: 5,
+      actor_type: "RepositoryRole",
+      bypass_mode: "always",
+    }),
+  ]),
+});
+
+/** Pull-request policy defaults, matching the retired template. */
+export const REVIEW_DEFAULTS = Object.freeze({
+  required_approving_review_count: 0,
+  require_code_owner_review: false,
+});
+
+/** Branch-protection defaults, matching the retired template. */
+export const PROTECT_DEFAULTS = Object.freeze({
+  deletion: true,
+  force_push: true,
+  conversation_resolution: true,
+  dismiss_stale_reviews: false,
+  require_last_push_approval: false,
+  up_to_date_before_merge: false,
+});
+
+/** Merge-method defaults, matching the retired template. */
+export const MERGE_DEFAULTS = Object.freeze({
+  merge_commit: true,
+  squash: false,
+  rebase: false,
+});
+
+/** GitHub's spelling of each allowed merge method. */
+const MERGE_METHODS = Object.freeze({
+  merge_commit: "merge",
+  squash: "squash",
+  rebase: "rebase",
+});
+
+/**
+ * Read a declared value, falling back to the default.
+ * @param {object|undefined} section The declared section.
+ * @param {string} field The field name.
+ * @param {object} defaults The defaults for that section.
+ * @returns {*} The resolved value.
+ */
+function resolved(section, field, defaults) {
+  const declared = section?.[field];
+  return declared === undefined ? defaults[field] : declared;
+}
+
+/**
+ * The awaited signals a project requires at one moment.
+ *
+ * Only `required` gates. An awaited gate at `optional` says the signal exists
+ * and is read, not that a pull request waits for it, and promoting it to a
+ * required context would turn advisory information into a merge block nobody
+ * declared.
+ * @param {object} gates The gates block.
+ * @param {string} moment The moment to resolve.
+ * @returns {Array<{context: string, integration_id?: number}>} Required checks.
+ */
+export function awaitedChecks(gates, moment) {
+  return resolveMoment({ gates, moment })
+    .filter(gate => gate.level === "required" && gate.mode === "await")
+    .filter(gate => Boolean(gate.awaits))
+    .map(gate =>
+      gate.postedBy === null
+        ? { context: gate.awaits }
+        : { context: gate.awaits, integration_id: gate.postedBy }
+    );
+}
+
+/**
+ * Collapse exact duplicate awaited checks, and refuse conflicting ones.
+ *
+ * A ruleset carries one entry per context. Two required gates awaiting the same
+ * signal is legitimate, so an exact duplicate — same context, same pin, both
+ * unpinned included — collapses to one entry. Two DIFFERENT pins for one
+ * context cannot both be honoured, and keeping whichever came first would
+ * discard a declaration silently: the repository would then require the context
+ * pinned to an app the project never named for it.
+ *
+ * `validateGates` refuses this too. Both, because this function is what
+ * actually writes the payload, and a writer that trusts its caller to have
+ * validated is a writer that ships the conflict the day some path skips
+ * validation.
+ * @param {Array<{context: string, integration_id?: number}>} checks Awaited checks.
+ * @returns {Array<{context: string, integration_id?: number}>} One per context.
+ * @throws {Error} When one context is declared with two different pins.
+ */
+function collapseAwaited(checks) {
+  const byContext = new Map();
+  for (const check of checks) {
+    const previous = byContext.get(check.context);
+    if (previous === undefined) {
+      byContext.set(check.context, check);
+      continue;
+    }
+    if ((previous.integration_id ?? null) === (check.integration_id ?? null)) {
+      continue;
+    }
+    throw new Error(
+      `"${check.context}" is awaited by two required gates naming different ` +
+        `apps (${JSON.stringify(check.integration_id ?? null)} and ` +
+        `${JSON.stringify(previous.integration_id ?? null)}). A ruleset carries ` +
+        `one entry per context, so one pin would be dropped silently. An ` +
+        `omitted posted_by means unpinned, which is a different requirement ` +
+        `from a pinned one.`
+    );
+  }
+  return [...byContext.values()];
+}
+
+/**
+ * The `pull_request` rule, built from `policy.protect` and `policy.review`.
+ * @param {object} policy The policy block.
+ * @returns {object} The rule.
+ */
+function pullRequestRule(policy) {
+  const merge = policy?.merge ?? {};
+  const allowed = Object.entries(MERGE_METHODS)
+    .filter(([field]) => resolved(merge, field, MERGE_DEFAULTS) === true)
+    .map(([, method]) => method);
+
+  return {
+    type: "pull_request",
+    parameters: {
+      required_approving_review_count: resolved(
+        policy?.review,
+        "required_approving_review_count",
+        REVIEW_DEFAULTS
+      ),
+      dismiss_stale_reviews_on_push: resolved(
+        policy?.protect,
+        "dismiss_stale_reviews",
+        PROTECT_DEFAULTS
+      ),
+      require_code_owner_review: resolved(
+        policy?.review,
+        "require_code_owner_review",
+        REVIEW_DEFAULTS
+      ),
+      require_last_push_approval: resolved(
+        policy?.protect,
+        "require_last_push_approval",
+        PROTECT_DEFAULTS
+      ),
+      required_review_thread_resolution: resolved(
+        policy?.protect,
+        "conversation_resolution",
+        PROTECT_DEFAULTS
+      ),
+      allowed_merge_methods: allowed,
+    },
+  };
+}
+
+/**
+ * Build the ruleset payload GitHub is sent.
+ *
+ * Deliberately reads only `gates` and `policy`. The per-ruleset opt-ins —
+ * `github.rulesets.requiredChecks` and `dropRequiredChecks` — are applied by
+ * `scripts/lisa-github-rulesets.sh` to EVERY ruleset it sends, this one
+ * included, and applying them here as well would mean two writers with two
+ * different defaults for `integration_id` racing over the same list.
+ * @param {object} options Build inputs.
+ * @param {object} [options.gates] The gates block.
+ * @param {object} [options.policy] The policy block.
+ * @param {string} [options.moment] Moment to derive awaited checks for.
+ * @returns {object} A create/update payload for the `base` ruleset.
+ */
+export function buildRulesetPayload({
+  gates = {},
+  policy = {},
+  moment = "pull-request",
+} = {}) {
+  const protect = policy?.protect ?? {};
+  const history = policy?.history ?? {};
+  const ruleset = policy?.ruleset ?? {};
+
+  const rules = [];
+  if (resolved(protect, "deletion", PROTECT_DEFAULTS)) {
+    rules.push({ type: "deletion" });
+  }
+  if (resolved(protect, "force_push", PROTECT_DEFAULTS)) {
+    rules.push({ type: "non_fast_forward" });
+  }
+  if (history.linear === true) rules.push({ type: "required_linear_history" });
+  if (history.signed_commits === true) {
+    rules.push({ type: "required_signatures" });
+  }
+  rules.push(pullRequestRule(policy));
+
+  const checks = collapseAwaited(awaitedChecks(gates, moment));
+
+  // An empty required_status_checks rule is not a weaker rule, it is a rule
+  // GitHub rejects. Omitting it is also what makes "this project requires no
+  // external signal" representable at all, which the template could not say.
+  if (checks.length > 0) {
+    rules.push({
+      type: "required_status_checks",
+      parameters: {
+        strict_required_status_checks_policy: resolved(
+          protect,
+          "up_to_date_before_merge",
+          PROTECT_DEFAULTS
+        ),
+        do_not_enforce_on_create: false,
+        required_status_checks: checks,
+      },
+    });
+  }
+
+  return {
+    name: POLICY_RULESET_NAME,
+    target: "branch",
+    enforcement: resolved(ruleset, "enforcement", RULESET_DEFAULTS),
+    conditions: {
+      ref_name: {
+        exclude: [...resolved(ruleset, "exclude_refs", RULESET_DEFAULTS)],
+        include: [...resolved(ruleset, "include_refs", RULESET_DEFAULTS)],
+      },
+    },
+    bypass_actors: [...resolved(ruleset, "bypass_actors", RULESET_DEFAULTS)],
+    rules,
+  };
+}
+
+/**
+ * Read a project's config without failing on its absence.
+ *
+ * A project with no `.lisa.config.json` still gets the default ruleset, which
+ * is what the deleted template gave it. Refusing here would turn "no config"
+ * into "no branch protection", a silent downgrade at exactly the moment
+ * governance is being applied.
+ * @param {string} projectPath The project directory.
+ * @returns {{gates: object, policy: object}} Resolved config.
+ */
+export function readProjectConfig(projectPath) {
+  const { gates, policy } = readGates(projectPath);
+  return { gates, policy };
+}
+
+/**
+ * CLI entry point: print the payload as JSON.
+ */
+function main() {
+  const argv = process.argv.slice(2);
+  const flag = name => {
+    const hit = argv.find(arg => arg.startsWith(`--${name}=`));
+    return hit ? hit.slice(name.length + 3) : null;
+  };
+  const projectPath = flag("project") ?? process.cwd();
+  const { gates, policy } = readProjectConfig(projectPath);
+  process.stdout.write(
+    `${JSON.stringify(
+      buildRulesetPayload({
+        gates,
+        policy,
+        moment: flag("moment") ?? "pull-request",
+      }),
+      null,
+      2
+    )}\n`
+  );
+}
+
+// Not `import.meta.url === process.argv[1]`. Node resolves the module URL
+// through realpath while argv[1] keeps whatever spelling the caller typed, so
+// on a symlinked path — a macOS temp dir, a git worktree — they differ, main()
+// never runs, and this generator prints NOTHING and exits 0. Measured: the
+// applier then read an empty template and skipped the only ruleset carrying
+// branch protection, reporting success.
+if (invokedAsScript(import.meta.url)) {
+  try {
+    main();
+  } catch (err) {
+    console.error(err.message);
+    process.exitCode = 1;
+  }
+}