@leverege/build-tools 2.117.0 → 2.119.0-pedro.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leverege/build-tools",
-  "version": "2.117.0",
+  "version": "2.119.0-pedro.1",
   "description": "A collection of build / support tools for Leverege developers",
   "main": "index.js",
   "repository": {
@@ -19,6 +19,7 @@
     "test-all": "mocha -t 60000 --exit 'test/**/**.mjs'"
   },
   "bin": {
+    "branch-protect-it": "src/branch-protect-it.mjs",
     "build-cnpg-image": "src/build-cnpg-image.mjs",
     "build-tools": "src/build-tools.mjs",
     "chart-compass": "src/chart-compass.mjs",
@@ -103,7 +104,7 @@
     "googleapis": "^176.0.0",
     "handlebars": "^4.7.9",
     "ignore": "^7.0.6",
-    "inquirer": "^14.1.0",
+    "inquirer": "^14.2.0",
     "js-yaml": "^4.2.0",
     "jsdoc": "^4.0.5",
     "ms": "^2.1.3",

package/src/branch-protect-it.mjs

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+import { $ } from 'zx'
+import { program } from 'commander'
+import chalk from 'chalk'
+
+import { enableDebug, errorExit, log, proceed } from './Utils.mjs'
+
+$.verbose = false
+
+const DEFAULT_ORG = 'Leverege'
+const REQUIRED_CHECK_PREFIX = 'node-ci'
+
+program
+  .name( 'branch-protect-it' )
+  .description( chalk.green( 'Applies the standard branch-protection + merge-method bundle to a repo' ) )
+  .argument( '<repo>', 'Repository name (without org prefix)' )
+  .option( '--org <org>', 'GitHub org', DEFAULT_ORG )
+  .option( '--branch <branch>', "Branch to protect (defaults to the repo's actual default branch)" )
+  .option( '--require-approvals <n>', 'Required approving review count', '0' )
+  .option( '--dry-run', 'Show what would be applied without making changes' )
+  .option( '--check', 'Read-only: exits 0 (matches the standard bundle) or 1 (does not) — ' +
+    'no prompt, no writes, no output at all by default. For scripting/dashboards (e.g. ' +
+    'repo-panopticon) that only care about the exit code. Pair with --check-verbose for output.' )
+  .option( '--check-verbose', 'With --check, also print which specific settings are missing/wrong ' +
+    '(or a success line). Has no effect without --check.' )
+  .option( '--debug', 'Enable debug logging' )
+  .addHelpText( 'after', `
+${chalk.yellow( 'What this applies:' )}
+  - Require a pull request before merging (0+ approvals, configurable)
+  - Require the repo's node-ci status check to pass, and the branch to be up to date
+  - Block force pushes and branch deletion
+  - Admins can still bypass (enforce_admins: false) for emergencies
+  - Repo-level merge method restricted to squash-only
+  - Auto-delete head branches on merge (delete_branch_on_merge)
+  - Suggest updating out-of-date PR branches with one click (allow_update_branch)
+
+${chalk.yellow( 'Scope:' )}
+  Only supports repos on the ${chalk.green( 'node-ci' )} reusable workflow for now — it looks up
+  the real check-run name from the target branch's latest commit (never guesses one) and
+  errors out if nothing starting with "node-ci" is found there.
+
+${chalk.yellow( 'Examples:' )}
+  ${chalk.green( 'branch-protect-it secrets' )}
+  ${chalk.green( 'branch-protect-it secrets --dry-run' )}
+  ${chalk.green( 'branch-protect-it secrets --require-approvals 1' )}
+  ${chalk.green( 'branch-protect-it secrets --check && echo protected' )}
+  ${chalk.green( 'branch-protect-it secrets --check --check-verbose' )}
+` )
+  .parse()
+
+const [ repo ] = program.args
+const opts = program.opts()
+if ( opts.debug ) { enableDebug(); $.verbose = true }
+
+const fullRepo = `${opts.org}/${repo}`
+// --check is silent by default (exit code only) — only chatty with --check-verbose.
+// Every other mode (apply/dry-run) always logs normally.
+const quietCheck = opts.check && !opts.checkVerbose
+const checkLog = ( ...args ) => { if ( !quietCheck ) { log( ...args ) } }
+
+// ---------- Resolve branch ----------
+
+let branch = opts.branch
+if ( !branch ) {
+  const { stdout } = await $`gh api -X GET repos/${fullRepo} -q .default_branch`
+  branch = stdout.trim()
+}
+checkLog( chalk.blue( `Target: ${fullRepo}@${branch}` ) )
+
+// ---------- --check: read-only status, exit 0/1, no writes, no prompt ----------
+
+if ( opts.check ) {
+  const reasons = []
+
+  let protection = null
+  try {
+    // .quiet() suppresses gh's own stderr (e.g. "Branch not protected") — that's an
+    // expected, handled outcome here, not something that should leak into --check's output
+    const { stdout } = await $`gh api -X GET repos/${fullRepo}/branches/${branch}/protection`.quiet()
+    protection = JSON.parse( stdout )
+  } catch {
+    reasons.push( 'no branch protection configured at all' )
+  }
+
+  if ( protection ) {
+    if ( !protection.required_pull_request_reviews ) { reasons.push( 'PR not required' ) }
+    if ( !protection.required_status_checks?.strict ) { reasons.push( 'status checks not required / not strict' ) }
+    if ( !protection.required_status_checks?.contexts?.some( c => c.startsWith( REQUIRED_CHECK_PREFIX ) ) ) {
+      reasons.push( `no required check starting with "${REQUIRED_CHECK_PREFIX}"` )
+    }
+    if ( protection.allow_force_pushes?.enabled !== false ) { reasons.push( 'force pushes not blocked' ) }
+    if ( protection.allow_deletions?.enabled !== false ) { reasons.push( 'branch deletion not blocked' ) }
+    if ( protection.enforce_admins?.enabled !== false ) { reasons.push( 'enforce_admins is not false (expected: admins can bypass)' ) }
+  }
+
+  let repoSettings = null
+  try {
+    const { stdout } = await $`gh api -X GET repos/${fullRepo} -q '{allow_squash_merge, allow_merge_commit, allow_rebase_merge, delete_branch_on_merge, allow_update_branch}'`
+    repoSettings = JSON.parse( stdout )
+  } catch ( error ) {
+    reasons.push( `could not read repo merge settings: ${error.stderr ?? error.message ?? error}` )
+  }
+
+  if ( repoSettings ) {
+    if ( repoSettings.allow_squash_merge !== true ) { reasons.push( 'squash merge not enabled' ) }
+    if ( repoSettings.allow_merge_commit !== false ) { reasons.push( 'merge commits not disabled' ) }
+    if ( repoSettings.allow_rebase_merge !== false ) { reasons.push( 'rebase merge not disabled' ) }
+    if ( repoSettings.delete_branch_on_merge !== true ) { reasons.push( 'delete_branch_on_merge not enabled' ) }
+    if ( repoSettings.allow_update_branch !== true ) { reasons.push( 'allow_update_branch not enabled' ) }
+  }
+
+  if ( reasons.length === 0 ) {
+    checkLog( chalk.green( `✔ ${fullRepo}@${branch} matches the standard branch-protection bundle` ) )
+    process.exit( 0 )
+  }
+
+  checkLog( chalk.red( `✘ ${fullRepo}@${branch} does not match the standard bundle:` ) )
+  reasons.forEach( r => checkLog( chalk.red( `  - ${r}` ) ) )
+  process.exit( 1 )
+}
+
+// ---------- Find the real node-ci check name — never guess it ----------
+
+let checkName
+try {
+  const { stdout : shaRaw } = await $`gh api -X GET repos/${fullRepo}/commits/${branch} -q .sha`
+  const sha = shaRaw.trim()
+  const { stdout : checksRaw } = await $`gh api -X GET repos/${fullRepo}/commits/${sha}/check-runs -q '.check_runs[].name'`
+  const checks = checksRaw.trim().split( '\n' ).filter( Boolean )
+  checkName = checks.find( c => c.startsWith( REQUIRED_CHECK_PREFIX ) )
+} catch ( error ) {
+  errorExit( `Failed to look up check runs: ${error.stderr ?? error.message ?? error}` )
+}
+
+if ( !checkName ) {
+  errorExit(
+    `No check run starting with "${REQUIRED_CHECK_PREFIX}" found on ${fullRepo}@${branch}'s latest commit.\n` +
+    '  Has the node-ci workflow actually run on this branch yet? Push something first, ' +
+    'or pass --branch if development is not the right target.'
+  )
+}
+log( chalk.green( `Found check: ${checkName}` ) )
+
+// ---------- Build the payload ----------
+
+const protectionPayload = {
+  required_status_checks : { strict : true, contexts : [ checkName ] },
+  enforce_admins : false,
+  required_pull_request_reviews : { required_approving_review_count : Number( opts.requireApprovals ) },
+  restrictions : null,
+  allow_force_pushes : false,
+  allow_deletions : false,
+}
+
+log( chalk.yellow( '\nWill apply branch protection:' ) )
+log( JSON.stringify( protectionPayload, null, 2 ) )
+log( chalk.yellow( 'Will also set merge method to squash-only ' +
+  '(allow_squash_merge=true, allow_merge_commit=false, allow_rebase_merge=false), ' +
+  'enable auto-delete of head branches on merge (delete_branch_on_merge=true), ' +
+  'and enable the "Update branch" suggestion button on out-of-date PRs (allow_update_branch=true)' ) )
+
+if ( opts.dryRun ) {
+  log( chalk.green( '\n[dry-run] No changes made.' ) )
+  process.exit( 0 )
+}
+
+await proceed( `\nApply this to ${fullRepo}@${branch}?` )
+
+// ---------- Apply ----------
+
+try {
+  await $( { input : JSON.stringify( protectionPayload ) } )`gh api --method PUT repos/${fullRepo}/branches/${branch}/protection --input -`
+  await $`gh api --method PATCH repos/${fullRepo} -F allow_squash_merge=true -F allow_merge_commit=false -F allow_rebase_merge=false -F delete_branch_on_merge=true -F allow_update_branch=true`
+} catch ( error ) {
+  errorExit( `Failed to apply settings: ${error.stderr ?? error.message ?? error}` )
+}
+
+log( chalk.green( `\n✔ Branch protection applied to ${fullRepo}@${branch}` ) )