@catladder/cli 0.0.0-main-e76cf00d → 0.0.0-main-bd7c0346

package/dist/bundles/cli/index.js

@@ -619,6 +619,7 @@ const pipeline_1 = __nccwpck_require__(53695);
 const commandSecretsSyncGithub_1 = __nccwpck_require__(27565);
 const concurrency_1 = __nccwpck_require__(59723);
 const github_1 = __nccwpck_require__(41353);
+const githubMergeGating_1 = __nccwpck_require__(14966);
 /** marker for repo-level (environment-less) targets, see collectSecretTargets */
 const REPO_LEVEL = "";
 /**
@@ -722,10 +723,13 @@ const checkGithub = async (report, config) => {
 exports.checkGithub = checkGithub;
 /**
  * verifies the merge gating `project setup` configures: auto-merge
- * enabled and the generated `catladder ✅` aggregate check required on
- * the default branch. Without it a PR is mergeable while its checks
- * are still running — gitlab ships this behavior built-in, github
- * silently does not.
+ * enabled and the `catladder merge gating` ruleset requiring the
+ * generated `catladder ✅` aggregate check on the default branch (with
+ * the bypass that lets the release job push). Without the check a PR
+ * is mergeable while its checks are still running — gitlab ships this
+ * behavior built-in, github silently does not. The check required via
+ * classic branch protection instead is flagged: that setup rejects the
+ * release job's own push (GH006).
  */
 const checkGithubMergeGating = async (report, repo) => {
     var _a, _b;
@@ -744,17 +748,35 @@ const checkGithubMergeGating = async (report, repo) => {
         report.fail("auto-merge disabled — the merge-when-pipeline-succeeds button cannot appear", "run: catladder project setup");
     }
     const branch = repoInfo.default_branch;
+    let rulesets;
+    try {
+        rulesets = await (0, github_1.ghApiJson)("GET", `repos/${repo}/rulesets?per_page=100`);
+    }
+    catch (e) {
+        report.warn(`could not list rulesets of ${repo} (${e.message})`);
+        return;
+    }
+    const named = rulesets.find((r) => r.name === githubMergeGating_1.MERGE_GATING_RULESET_NAME);
+    const ruleset = named
+        ? await (0, github_1.ghApiJson)("GET", `repos/${repo}/rulesets/${named.id}`).catch(() => null)
+        : null;
+    if (ruleset && (0, githubMergeGating_1.rulesetProvidesMergeGating)(ruleset)) {
+        report.ok(`ruleset '${githubMergeGating_1.MERGE_GATING_RULESET_NAME}': '${pipeline_1.AGGREGATE_CHECK_JOB_NAME}' required on ${branch}, release job can push`);
+    }
+    else if (ruleset) {
+        report.fail(`ruleset '${githubMergeGating_1.MERGE_GATING_RULESET_NAME}' exists but is incomplete (inactive, check not required, or release-job bypass missing)`, "run: catladder project setup");
+    }
+    else {
+        report.fail(`no '${githubMergeGating_1.MERGE_GATING_RULESET_NAME}' ruleset on ${repo} — PRs can merge while the pipeline is red or still running`, "run: catladder project setup");
+    }
     const protection = await (0, github_1.ghApiJson)("GET", `repos/${repo}/branches/${branch}/protection`).catch(() => null);
     const checks = (_b = (_a = protection === null || protection === void 0 ? void 0 : protection.required_status_checks) === null || _a === void 0 ? void 0 : _a.checks) !== null && _b !== void 0 ? _b : [];
     if (checks.some((c) => c.context === pipeline_1.AGGREGATE_CHECK_JOB_NAME)) {
-        report.ok(`'${pipeline_1.AGGREGATE_CHECK_JOB_NAME}' required on ${branch}`);
-    }
-    else {
-        report.fail(`'${pipeline_1.AGGREGATE_CHECK_JOB_NAME}' is not a required check on ${branch} — PRs can merge while the pipeline is red or still running`, "run: catladder project setup");
+        report.fail(`'${pipeline_1.AGGREGATE_CHECK_JOB_NAME}' is still required via classic branch protection on ${branch} — that rejects the release job's push (GH006)`, "run: catladder project setup");
     }
     const stale = checks.filter((c) => c.context !== pipeline_1.AGGREGATE_CHECK_JOB_NAME);
     if (stale.length > 0) {
-        report.warn(`${branch} requires ${stale.length} additional named check(s) (${stale
+        report.warn(`${branch} requires ${stale.length} additional named check(s) via classic branch protection (${stale
             .map((c) => c.context)
             .join(", ")}) — job names change with components; prefer only '${pipeline_1.AGGREGATE_CHECK_JOB_NAME}'`);
     }
@@ -950,6 +972,84 @@ exports.doctorProject = doctorProject;
 
 /***/ }),
 
+/***/ 14966:
+/***/ ((__unused_webpack_module, exports, __nccwpck_require__) => {
+
+"use strict";
+
+Object.defineProperty(exports, "__esModule", ({ value: true }));
+exports.rulesetProvidesMergeGating = exports.desiredMergeGatingRuleset = exports.MERGE_GATING_RULESET_NAME = exports.GITHUB_ACTIONS_APP_ID = void 0;
+const pipeline_1 = __nccwpck_require__(53695);
+/**
+ * github merge gating — shared between `project setup` (writes it) and
+ * `project doctor` (verifies it).
+ *
+ * The gating lives in a repository RULESET, not classic branch
+ * protection: only rulesets can carry bypass actors, and the release
+ * job needs one. It pushes the release commit and tag straight to the
+ * default branch with the workflow token — under classic protection
+ * the required `catladder ✅` check rejects that push (GH006), because
+ * the fresh release commit cannot have a passing check yet. The bypass
+ * covers the GitHub Actions app, i.e. pushes made by workflows, while
+ * PRs and humans stay gated. (Gitlab's counterpart is the
+ * maintainer-role project access token, which may push to protected
+ * branches by default — the same trade-off, made by the platform.)
+ */
+/** the app id of GitHub Actions — the actor workflow tokens act as */
+exports.GITHUB_ACTIONS_APP_ID = 15368;
+exports.MERGE_GATING_RULESET_NAME = "catladder merge gating";
+/** the ruleset `project setup` creates (and restores on drift) */
+const desiredMergeGatingRuleset = () => ({
+    name: exports.MERGE_GATING_RULESET_NAME,
+    target: "branch",
+    enforcement: "active",
+    conditions: { ref_name: { include: ["~DEFAULT_BRANCH"], exclude: [] } },
+    rules: [
+        {
+            type: "required_status_checks",
+            parameters: {
+                strict_required_status_checks_policy: false,
+                do_not_enforce_on_create: false,
+                required_status_checks: [
+                    {
+                        context: pipeline_1.AGGREGATE_CHECK_JOB_NAME,
+                        integration_id: exports.GITHUB_ACTIONS_APP_ID,
+                    },
+                ],
+            },
+        },
+    ],
+    bypass_actors: [
+        {
+            actor_id: exports.GITHUB_ACTIONS_APP_ID,
+            actor_type: "Integration",
+            bypass_mode: "always",
+        },
+    ],
+});
+exports.desiredMergeGatingRuleset = desiredMergeGatingRuleset;
+/**
+ * whether a ruleset provides working merge gating: active, requires
+ * the aggregate check, and lets the release job (GitHub Actions app)
+ * bypass it. Extra rules or bypass actors someone added are fine.
+ */
+const rulesetProvidesMergeGating = (ruleset) => {
+    var _a, _b;
+    return ruleset.enforcement === "active" &&
+        ((_a = ruleset.rules) !== null && _a !== void 0 ? _a : []).some((rule) => {
+            var _a, _b;
+            return rule.type === "required_status_checks" &&
+                ((_b = (_a = rule.parameters) === null || _a === void 0 ? void 0 : _a.required_status_checks) !== null && _b !== void 0 ? _b : []).some((check) => check.context === pipeline_1.AGGREGATE_CHECK_JOB_NAME);
+        }) &&
+        ((_b = ruleset.bypass_actors) !== null && _b !== void 0 ? _b : []).some((actor) => actor.actor_type === "Integration" &&
+            actor.actor_id === exports.GITHUB_ACTIONS_APP_ID &&
+            actor.bypass_mode === "always");
+};
+exports.rulesetProvidesMergeGating = rulesetProvidesMergeGating;
+//# sourceMappingURL=githubMergeGating.js.map
+
+/***/ }),
+
 /***/ 2231:
 /***/ ((__unused_webpack_module, exports, __nccwpck_require__) => {
 
@@ -1436,6 +1536,7 @@ exports.setupGithub = void 0;
 const pipeline_1 = __nccwpck_require__(53695);
 const commandSecretsSyncGithub_1 = __nccwpck_require__(27565);
 const github_1 = __nccwpck_require__(41353);
+const githubMergeGating_1 = __nccwpck_require__(14966);
 /**
  * configures github merge gating — the sane default gitlab ships
  * built-in and a fresh github repository lacks entirely: without it a
@@ -1443,18 +1544,19 @@ const github_1 = __nccwpck_require__(41353);
  * auto-merge button never appears.
  *
  * - repo settings: allow auto-merge, delete merged head branches
- * - branch protection on the default branch: require the generated
+ * - a repository ruleset on the default branch requiring the generated
  *   `catladder ✅` aggregate check (the one stable context — individual
- *   job names change with every component add/rename)
+ *   job names change with every component add/rename), with a bypass
+ *   for the GitHub Actions app so the release job can push the release
+ *   commit and tag (see githubMergeGating.ts for the full rationale)
  *
- * Deliberately non-destructive: existing protection settings
- * (enforce-admins, required reviews, restrictions, strictness) are
- * preserved; the aggregate context is merged into the required checks
- * rather than replacing them. Admins can still bypass per PR — this is
- * a default, not a cage.
+ * Earlier versions required the check via classic branch protection,
+ * which has no bypass list — the release job's direct push to the
+ * default branch bounced off catladder's own gating (GH006). Setup
+ * migrates that away: the aggregate context is removed from an
+ * existing classic rule, everything else in it is preserved.
  */
 const setupGithub = async (instance, config) => {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o;
     if (!(0, pipeline_1.getEnabledPipelineTypes)(config).includes("github")) {
         return;
     }
@@ -1479,33 +1581,75 @@ const setupGithub = async (instance, config) => {
         instance.log("✅ auto-merge already enabled");
     }
     const branch = repoInfo.default_branch;
-    const protection = await (0, github_1.ghApiJson)("GET", `repos/${repo}/branches/${branch}/protection`).catch(() => null); // 404: branch not protected yet
-    const existingChecks = (_b = (_a = protection === null || protection === void 0 ? void 0 : protection.required_status_checks) === null || _a === void 0 ? void 0 : _a.checks) !== null && _b !== void 0 ? _b : [];
-    if (existingChecks.some((c) => c.context === pipeline_1.AGGREGATE_CHECK_JOB_NAME)) {
-        instance.log(`✅ '${pipeline_1.AGGREGATE_CHECK_JOB_NAME}' already required on ${branch}`);
+    const rulesets = await (0, github_1.ghApiJson)("GET", `repos/${repo}/rulesets?per_page=100`);
+    const existing = rulesets.find((r) => r.name === githubMergeGating_1.MERGE_GATING_RULESET_NAME);
+    if (!existing) {
+        await (0, github_1.ghApiJson)("POST", `repos/${repo}/rulesets`, (0, githubMergeGating_1.desiredMergeGatingRuleset)());
+        instance.log(`✅ ruleset '${githubMergeGating_1.MERGE_GATING_RULESET_NAME}': '${pipeline_1.AGGREGATE_CHECK_JOB_NAME}' required on ${branch} — merges wait for the pipeline, the release job can push`);
+    }
+    else {
+        const detail = await (0, github_1.ghApiJson)("GET", `repos/${repo}/rulesets/${existing.id}`);
+        if ((0, githubMergeGating_1.rulesetProvidesMergeGating)(detail)) {
+            instance.log(`✅ ruleset '${githubMergeGating_1.MERGE_GATING_RULESET_NAME}' already in place on ${branch}`);
+        }
+        else {
+            await (0, github_1.ghApiJson)("PUT", `repos/${repo}/rulesets/${existing.id}`, (0, githubMergeGating_1.desiredMergeGatingRuleset)());
+            instance.log(`✅ ruleset '${githubMergeGating_1.MERGE_GATING_RULESET_NAME}' restored — '${pipeline_1.AGGREGATE_CHECK_JOB_NAME}' required, release-job bypass in place`);
+        }
+    }
+    await migrateAwayFromClassicProtection(instance, repo, branch);
+};
+exports.setupGithub = setupGithub;
+/**
+ * removes the aggregate check from a classic branch protection rule
+ * set up by earlier catladder versions — with the check now required
+ * via the ruleset, the classic one would still reject the release
+ * job's push. Everything else in the rule is preserved; the whole rule
+ * is deleted when the check was all it carried.
+ */
+const migrateAwayFromClassicProtection = async (instance, repo, branch) => {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z, _0, _1;
+    const protection = await (0, github_1.ghApiJson)("GET", `repos/${repo}/branches/${branch}/protection`).catch(() => null); // 404: branch not protected
+    const checks = (_b = (_a = protection === null || protection === void 0 ? void 0 : protection.required_status_checks) === null || _a === void 0 ? void 0 : _a.checks) !== null && _b !== void 0 ? _b : [];
+    if (!checks.some((c) => c.context === pipeline_1.AGGREGATE_CHECK_JOB_NAME)) {
+        return;
+    }
+    const remaining = checks.filter((c) => c.context !== pipeline_1.AGGREGATE_CHECK_JOB_NAME);
+    const carriesAnythingElse = remaining.length > 0 ||
+        ((_c = protection === null || protection === void 0 ? void 0 : protection.enforce_admins) === null || _c === void 0 ? void 0 : _c.enabled) ||
+        (protection === null || protection === void 0 ? void 0 : protection.required_pull_request_reviews) ||
+        (protection === null || protection === void 0 ? void 0 : protection.restrictions) ||
+        ((_d = protection === null || protection === void 0 ? void 0 : protection.required_linear_history) === null || _d === void 0 ? void 0 : _d.enabled) ||
+        ((_e = protection === null || protection === void 0 ? void 0 : protection.required_conversation_resolution) === null || _e === void 0 ? void 0 : _e.enabled) ||
+        ((_f = protection === null || protection === void 0 ? void 0 : protection.required_signatures) === null || _f === void 0 ? void 0 : _f.enabled) ||
+        ((_g = protection === null || protection === void 0 ? void 0 : protection.lock_branch) === null || _g === void 0 ? void 0 : _g.enabled) ||
+        ((_h = protection === null || protection === void 0 ? void 0 : protection.allow_force_pushes) === null || _h === void 0 ? void 0 : _h.enabled) ||
+        ((_j = protection === null || protection === void 0 ? void 0 : protection.allow_deletions) === null || _j === void 0 ? void 0 : _j.enabled);
+    if (!carriesAnythingElse) {
+        await (0, github_1.ghApiJson)("DELETE", `repos/${repo}/branches/${branch}/protection`);
+        instance.log(`✅ classic branch protection on ${branch} removed — '${pipeline_1.AGGREGATE_CHECK_JOB_NAME}' was all it carried, and it is now required via the ruleset`);
         return;
     }
-    // merge into whatever protection exists; PUT replaces the whole rule,
-    // so every preserved setting must be carried over explicitly
+    // PUT replaces the whole rule, so every preserved setting must be
+    // carried over explicitly
     await (0, github_1.ghApiJson)("PUT", `repos/${repo}/branches/${branch}/protection`, {
-        required_status_checks: {
-            strict: (_d = (_c = protection === null || protection === void 0 ? void 0 : protection.required_status_checks) === null || _c === void 0 ? void 0 : _c.strict) !== null && _d !== void 0 ? _d : false,
-            checks: [
-                ...existingChecks.map(({ context, app_id }) => ({
+        required_status_checks: remaining.length > 0
+            ? {
+                strict: (_l = (_k = protection === null || protection === void 0 ? void 0 : protection.required_status_checks) === null || _k === void 0 ? void 0 : _k.strict) !== null && _l !== void 0 ? _l : false,
+                checks: remaining.map(({ context, app_id }) => ({
                     context,
                     ...(app_id !== undefined ? { app_id } : {}),
                 })),
-                { context: pipeline_1.AGGREGATE_CHECK_JOB_NAME },
-            ],
-        },
-        enforce_admins: (_f = (_e = protection === null || protection === void 0 ? void 0 : protection.enforce_admins) === null || _e === void 0 ? void 0 : _e.enabled) !== null && _f !== void 0 ? _f : false,
+            }
+            : null,
+        enforce_admins: (_o = (_m = protection === null || protection === void 0 ? void 0 : protection.enforce_admins) === null || _m === void 0 ? void 0 : _m.enabled) !== null && _o !== void 0 ? _o : false,
         required_pull_request_reviews: (protection === null || protection === void 0 ? void 0 : protection.required_pull_request_reviews)
             ? {
-                required_approving_review_count: (_g = protection.required_pull_request_reviews
-                    .required_approving_review_count) !== null && _g !== void 0 ? _g : 0,
-                dismiss_stale_reviews: (_h = protection.required_pull_request_reviews.dismiss_stale_reviews) !== null && _h !== void 0 ? _h : false,
-                require_code_owner_reviews: (_j = protection.required_pull_request_reviews
-                    .require_code_owner_reviews) !== null && _j !== void 0 ? _j : false,
+                required_approving_review_count: (_p = protection.required_pull_request_reviews
+                    .required_approving_review_count) !== null && _p !== void 0 ? _p : 0,
+                dismiss_stale_reviews: (_q = protection.required_pull_request_reviews.dismiss_stale_reviews) !== null && _q !== void 0 ? _q : false,
+                require_code_owner_reviews: (_r = protection.required_pull_request_reviews
+                    .require_code_owner_reviews) !== null && _r !== void 0 ? _r : false,
             }
             : null,
         restrictions: (protection === null || protection === void 0 ? void 0 : protection.restrictions)
@@ -1515,12 +1659,14 @@ const setupGithub = async (instance, config) => {
                 apps: protection.restrictions.apps.map((a) => a.slug),
             }
             : null,
-        allow_force_pushes: (_l = (_k = protection === null || protection === void 0 ? void 0 : protection.allow_force_pushes) === null || _k === void 0 ? void 0 : _k.enabled) !== null && _l !== void 0 ? _l : false,
-        allow_deletions: (_o = (_m = protection === null || protection === void 0 ? void 0 : protection.allow_deletions) === null || _m === void 0 ? void 0 : _m.enabled) !== null && _o !== void 0 ? _o : false,
+        required_linear_history: (_t = (_s = protection === null || protection === void 0 ? void 0 : protection.required_linear_history) === null || _s === void 0 ? void 0 : _s.enabled) !== null && _t !== void 0 ? _t : false,
+        required_conversation_resolution: (_v = (_u = protection === null || protection === void 0 ? void 0 : protection.required_conversation_resolution) === null || _u === void 0 ? void 0 : _u.enabled) !== null && _v !== void 0 ? _v : false,
+        lock_branch: (_x = (_w = protection === null || protection === void 0 ? void 0 : protection.lock_branch) === null || _w === void 0 ? void 0 : _w.enabled) !== null && _x !== void 0 ? _x : false,
+        allow_force_pushes: (_z = (_y = protection === null || protection === void 0 ? void 0 : protection.allow_force_pushes) === null || _y === void 0 ? void 0 : _y.enabled) !== null && _z !== void 0 ? _z : false,
+        allow_deletions: (_1 = (_0 = protection === null || protection === void 0 ? void 0 : protection.allow_deletions) === null || _0 === void 0 ? void 0 : _0.enabled) !== null && _1 !== void 0 ? _1 : false,
     });
-    instance.log(`✅ branch protection on ${branch}: '${pipeline_1.AGGREGATE_CHECK_JOB_NAME}' required (merges now wait for the pipeline)`);
+    instance.log(`✅ '${pipeline_1.AGGREGATE_CHECK_JOB_NAME}' removed from classic branch protection on ${branch} — now required via the ruleset; the rest of the rule is preserved`);
 };
-exports.setupGithub = setupGithub;
 //# sourceMappingURL=setupGithub.js.map
 
 /***/ }),

package/dist/bundles/skills/catladder-migrate-ci-backend/SKILL.md

@@ -260,13 +260,17 @@ now-wrong `gitRemote`, regenerate once more, and finish with
   PR is mergeable the moment it opens, checks still running, and the
   auto-merge button does not even appear. `yarn catladder project setup`
   configures it: auto-merge + delete-merged-branches on the repo, and a
-  branch protection rule on the default branch requiring the generated
-  **`catladder ✅`** aggregate check (the one stable context — never
-  require individual job names, they change with every component
-  add/rename and a stale required name blocks its own PR forever).
-  `project doctor` verifies it. Two things stay human choices: "Do not
-  allow bypassing" (leave it off — generated CI means a generation bug
-  can only be fixed via the admin bypass) and required reviews.
+  repository **ruleset** (`catladder merge gating`) on the default
+  branch requiring the generated **`catladder ✅`** aggregate check
+  (the one stable context — never require individual job names, they
+  change with every component add/rename and a stale required name
+  blocks its own PR forever). The ruleset carries a bypass for the
+  GitHub Actions app: the release job pushes the release commit and
+  tag straight to the default branch with the workflow token, which a
+  required check would otherwise reject (GH006 — classic branch
+  protection has no bypass list, which is why setup uses a ruleset and
+  migrates old classic-protection gating away). `project doctor`
+  verifies all of it. Required reviews stay a human choice.
 - Tell the team where the pipeline lives now and how manual actions
   work there (on GitHub, manual jobs are dispatch workflows in the
   Actions sidebar — `🚀 catladder create release`, `▶️ catladder deploy`,

package/dist/skills/catladder-migrate-ci-backend/SKILL.md

@@ -260,13 +260,17 @@ now-wrong `gitRemote`, regenerate once more, and finish with
   PR is mergeable the moment it opens, checks still running, and the
   auto-merge button does not even appear. `yarn catladder project setup`
   configures it: auto-merge + delete-merged-branches on the repo, and a
-  branch protection rule on the default branch requiring the generated
-  **`catladder ✅`** aggregate check (the one stable context — never
-  require individual job names, they change with every component
-  add/rename and a stale required name blocks its own PR forever).
-  `project doctor` verifies it. Two things stay human choices: "Do not
-  allow bypassing" (leave it off — generated CI means a generation bug
-  can only be fixed via the admin bypass) and required reviews.
+  repository **ruleset** (`catladder merge gating`) on the default
+  branch requiring the generated **`catladder ✅`** aggregate check
+  (the one stable context — never require individual job names, they
+  change with every component add/rename and a stale required name
+  blocks its own PR forever). The ruleset carries a bypass for the
+  GitHub Actions app: the release job pushes the release commit and
+  tag straight to the default branch with the workflow token, which a
+  required check would otherwise reject (GH006 — classic branch
+  protection has no bypass list, which is why setup uses a ruleset and
+  migrates old classic-protection gating away). `project doctor`
+  verifies all of it. Required reviews stay a human choice.
 - Tell the team where the pipeline lives now and how manual actions
   work there (on GitHub, manual jobs are dispatch workflows in the
   Actions sidebar — `🚀 catladder create release`, `▶️ catladder deploy`,