@catladder/cli 0.0.0-next-e95e1f20 → 0.0.0-next-ca8f99e2

package/package.json

@@ -53,7 +53,7 @@
     }
   ],
   "license": "MIT",
-  "version": "0.0.0-next-e95e1f20",
+  "version": "0.0.0-next-ca8f99e2",
   "scripts": {
     "lint": "eslint \"src/**/*.ts\"",
     "lint:fix": "eslint \"src/**/*.ts\" --fix",

package/src/apps/cli/commands/project/doctor/checkGithub.ts

@@ -1,5 +1,6 @@
 import type { Config } from "@catladder/pipeline";
 import {
+  AGGREGATE_CHECK_JOB_NAME,
   getEnabledPipelineTypes,
   getPipelineGitRemote,
 } from "@catladder/pipeline";
@@ -9,6 +10,7 @@ import {
 } from "../../../../../commands/project/commandSecretsSyncGithub";
 import { mapWithConcurrency } from "../../../../../utils/concurrency";
 import {
+  ghApiJson,
   isGhAuthenticated,
   listGithubEnvironments,
   listGithubSecretNames,
@@ -153,4 +155,57 @@ export const checkGithub = async (report: DoctorReport, config: Config) => {
       );
     }
   }
+
+  await checkGithubMergeGating(report, repo);
+};
+
+/**
+ * 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.
+ */
+const checkGithubMergeGating = async (report: DoctorReport, repo: string) => {
+  let repoInfo: { default_branch: string; allow_auto_merge: boolean };
+  try {
+    repoInfo = await ghApiJson("GET", `repos/${repo}`);
+  } catch (e) {
+    report.warn(`could not read repo settings of ${repo} (${e.message})`);
+    return;
+  }
+  if (repoInfo.allow_auto_merge) {
+    report.ok("auto-merge enabled");
+  } else {
+    report.fail(
+      "auto-merge disabled — the merge-when-pipeline-succeeds button cannot appear",
+      "run: catladder project setup",
+    );
+  }
+
+  const branch = repoInfo.default_branch;
+  const protection = await ghApiJson<any>(
+    "GET",
+    `repos/${repo}/branches/${branch}/protection`,
+  ).catch(() => null);
+  const checks: Array<{ context: string }> =
+    protection?.required_status_checks?.checks ?? [];
+  if (checks.some((c) => c.context === AGGREGATE_CHECK_JOB_NAME)) {
+    report.ok(`'${AGGREGATE_CHECK_JOB_NAME}' required on ${branch}`);
+  } else {
+    report.fail(
+      `'${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",
+    );
+  }
+  const stale = checks.filter((c) => c.context !== AGGREGATE_CHECK_JOB_NAME);
+  if (stale.length > 0) {
+    report.warn(
+      `${branch} requires ${stale.length} additional named check(s) (${stale
+        .map((c) => c.context)
+        .join(
+          ", ",
+        )}) — job names change with components; prefer only '${AGGREGATE_CHECK_JOB_NAME}'`,
+    );
+  }
 };

package/src/apps/cli/commands/project/setup/index.ts

@@ -1,4 +1,8 @@
-import { createCatenvContext, generateAgentSkills } from "@catladder/pipeline";
+import {
+  createCatenvContext,
+  generateAgentSkills,
+  getEnabledPipelineTypes,
+} from "@catladder/pipeline";
 import type { IO } from "../../../../../core/types";
 import {
   getAllPipelineContexts,
@@ -8,6 +12,7 @@ import { setupAccessTokens } from "./setupAccessTokens";
 import { setupContext } from "./setupContext";
 import { setupTopic } from "./setupTopic";
 import { setupAgents } from "./setupAgents";
+import { setupGithub } from "./setupGithub";
 import { logSection } from "./logSection";
 import { ensureGcloudProjectNumbers } from "./ensureGcloudProjectNumbers";
 
@@ -33,17 +38,25 @@ export const setupProject = async (
     instance.log(` - ${context.name}:${context.env}`);
   });
 
+  const enabledPipelines = config ? getEnabledPipelineTypes(config) : [];
   await logSection(instance, "base setup", async () => {
-    await setupAccessTokens(instance);
+    // gitlab-specific provisioning (access token, agent webhooks) —
+    // meaningless (and failing) on a github-only project
+    if (enabledPipelines.includes("gitlab")) {
+      await setupAccessTokens(instance);
+      await setupAgents(instance);
+    }
     await setupTopic(instance);
-    await setupAgents(instance);
+    if (config) {
+      await setupGithub(instance, config);
+    }
   });
   for (const context of allContext) {
     await setupContext(instance, context);
   }
 
   instance.log("");
-  instance.log("gitlab is ready! 🥂");
+  instance.log(`${enabledPipelines.join(" + ") || "gitlab"} is ready! 🥂`);
   instance.log("\n");
   instance.log("do not forget to make sure that:");
   [

package/src/apps/cli/commands/project/setup/setupGithub.ts

@@ -0,0 +1,117 @@
+import type { Config } from "@catladder/pipeline";
+import {
+  AGGREGATE_CHECK_JOB_NAME,
+  getEnabledPipelineTypes,
+  getPipelineGitRemote,
+} from "@catladder/pipeline";
+import { getConfiguredGithubRepo } from "../../../../../commands/project/commandSecretsSyncGithub";
+import type { IO } from "../../../../../core/types";
+import { ghApiJson, isGhAuthenticated } from "../../../../../utils/github";
+
+/**
+ * configures github merge gating — the sane default gitlab ships
+ * built-in and a fresh github repository lacks entirely: without it a
+ * PR is mergeable the moment it opens, checks still running, and the
+ * auto-merge button never appears.
+ *
+ * - repo settings: allow auto-merge, delete merged head branches
+ * - branch protection on the default branch: require the generated
+ *   `catladder ✅` aggregate check (the one stable context — individual
+ *   job names change with every component add/rename)
+ *
+ * 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.
+ */
+export const setupGithub = async (instance: IO, config: Config) => {
+  if (!getEnabledPipelineTypes(config).includes("github")) {
+    return;
+  }
+  if (!(await isGhAuthenticated())) {
+    instance.log(
+      "⚠️ github cli (gh) not authenticated — skipping github merge-gating setup (run: gh auth login)",
+    );
+    return;
+  }
+  const repo = await getConfiguredGithubRepo();
+  if (!repo) {
+    instance.log(
+      `⚠️ no github repository found on the '${getPipelineGitRemote(config, "github")}' remote — skipping github merge-gating setup`,
+    );
+    return;
+  }
+
+  const repoInfo = await ghApiJson<{
+    default_branch: string;
+    allow_auto_merge: boolean;
+    delete_branch_on_merge: boolean;
+  }>("GET", `repos/${repo}`);
+
+  if (!repoInfo.allow_auto_merge || !repoInfo.delete_branch_on_merge) {
+    await ghApiJson("PATCH", `repos/${repo}`, {
+      allow_auto_merge: true,
+      delete_branch_on_merge: true,
+    });
+    instance.log("✅ auto-merge + delete-merged-branches enabled");
+  } else {
+    instance.log("✅ auto-merge already enabled");
+  }
+
+  const branch = repoInfo.default_branch;
+  const protection = await ghApiJson<any>(
+    "GET",
+    `repos/${repo}/branches/${branch}/protection`,
+  ).catch(() => null); // 404: branch not protected yet
+
+  const existingChecks: Array<{ context: string; app_id?: number }> =
+    protection?.required_status_checks?.checks ?? [];
+  if (existingChecks.some((c) => c.context === AGGREGATE_CHECK_JOB_NAME)) {
+    instance.log(
+      `✅ '${AGGREGATE_CHECK_JOB_NAME}' already required on ${branch}`,
+    );
+    return;
+  }
+
+  // merge into whatever protection exists; PUT replaces the whole rule,
+  // so every preserved setting must be carried over explicitly
+  await ghApiJson("PUT", `repos/${repo}/branches/${branch}/protection`, {
+    required_status_checks: {
+      strict: protection?.required_status_checks?.strict ?? false,
+      checks: [
+        ...existingChecks.map(({ context, app_id }) => ({
+          context,
+          ...(app_id !== undefined ? { app_id } : {}),
+        })),
+        { context: AGGREGATE_CHECK_JOB_NAME },
+      ],
+    },
+    enforce_admins: protection?.enforce_admins?.enabled ?? false,
+    required_pull_request_reviews: protection?.required_pull_request_reviews
+      ? {
+          required_approving_review_count:
+            protection.required_pull_request_reviews
+              .required_approving_review_count ?? 0,
+          dismiss_stale_reviews:
+            protection.required_pull_request_reviews.dismiss_stale_reviews ??
+            false,
+          require_code_owner_reviews:
+            protection.required_pull_request_reviews
+              .require_code_owner_reviews ?? false,
+        }
+      : null,
+    restrictions: protection?.restrictions
+      ? {
+          users: protection.restrictions.users.map((u: any) => u.login),
+          teams: protection.restrictions.teams.map((t: any) => t.slug),
+          apps: protection.restrictions.apps.map((a: any) => a.slug),
+        }
+      : null,
+    allow_force_pushes: protection?.allow_force_pushes?.enabled ?? false,
+    allow_deletions: protection?.allow_deletions?.enabled ?? false,
+  });
+  instance.log(
+    `✅ branch protection on ${branch}: '${AGGREGATE_CHECK_JOB_NAME}' required (merges now wait for the pipeline)`,
+  );
+};

package/src/utils/github.ts

@@ -167,3 +167,33 @@ export const ensureGithubEnvironment = async (
           ),
     );
   });
+
+/** runs `gh api` with an optional JSON body and returns the parsed response */
+export const ghApiJson = async <T = any>(
+  method: "GET" | "PATCH" | "PUT",
+  path: string,
+  body?: unknown,
+): Promise<T> => {
+  const args = ["api", "-X", method, path];
+  const child = spawn("gh", [...args, ...(body ? ["--input", "-"] : [])], {
+    stdio: [body ? "pipe" : "ignore", "pipe", "pipe"],
+  });
+  let stdout = "";
+  let stderr = "";
+  child.stdout?.on("data", (data) => (stdout += data));
+  child.stderr?.on("data", (data) => (stderr += data));
+  if (body) {
+    child.stdin?.write(JSON.stringify(body));
+    child.stdin?.end();
+  }
+  return new Promise<T>((resolve, reject) => {
+    child.on("error", reject);
+    child.on("close", (code) =>
+      code === 0
+        ? resolve(stdout ? JSON.parse(stdout) : (undefined as T))
+        : reject(
+            new Error(`gh api ${method} ${path} failed: ${stderr.trim()}`),
+          ),
+    );
+  });
+};