claude-attribution 1.2.5 → 1.2.8

package/src/setup/branch-protection.ts

@@ -0,0 +1,432 @@
+/**
+ * Branch protection utilities for claude-attribution install.
+ *
+ * Handles both classic branch protection rules and GitHub rulesets.
+ * After installing the workflow, detects what protection is active on the
+ * default branch and interactively offers to add our workflow job as a
+ * required status check.
+ *
+ * Design:
+ *   - Classic protection: PATCH .../required_status_checks (preserves existing)
+ *   - Rulesets: PUT .../rulesets/{id} with updated rules (preserves all other rules)
+ *   - Both present: numbered prompt so user chooses where to add
+ *   - Already configured: silent skip for that protection type
+ *   - Any failure: graceful fallback to informational note, never breaks install
+ */
+import { execFile } from "child_process";
+import { promisify } from "util";
+import { writeFile, unlink, rmdir, mkdtemp } from "fs/promises";
+import { tmpdir } from "os";
+import { join } from "path";
+import { createInterface } from "readline";
+
+const execFileAsync = promisify(execFile);
+
+/** The GitHub Actions job name — must match `jobs.metrics.name` in the workflow template. */
+export const WORKFLOW_CHECK_NAME = "Claude Code Attribution Metrics";
+
+/** GitHub Actions app ID — used so the check shows "GitHub Actions" rather than "any source". */
+const GITHUB_ACTIONS_APP_ID = 15368;
+
+type Check = { context: string; app_id: number };
+
+interface ClassicStatus {
+	branch: string;
+	strict: boolean;
+	checks: Check[];
+	hasOurCheck: boolean;
+}
+
+interface RulesetStatus {
+	id: number;
+	name: string;
+	hasOurCheck: boolean;
+	/** Full raw ruleset object — re-submitted on PUT to preserve all fields. */
+	raw: RawRuleset;
+}
+
+interface RawRuleset {
+	name: string;
+	target?: string;
+	enforcement?: string;
+	conditions?: unknown;
+	bypass_actors?: unknown[];
+	rules?: RawRule[];
+}
+
+interface RawRule {
+	type: string;
+	parameters?: {
+		strict_required_status_checks_policy?: boolean;
+		required_status_checks?: Array<{
+			context: string;
+			integration_id?: number;
+		}>;
+		[key: string]: unknown;
+	};
+}
+
+// ─── GitHub API helpers ───────────────────────────────────────────────────────
+
+async function ghGet(path: string): Promise<unknown> {
+	try {
+		const { stdout } = (await execFileAsync("gh", [
+			"api",
+			path,
+		])) as unknown as { stdout: string };
+		return JSON.parse(stdout) as unknown;
+	} catch {
+		return null;
+	}
+}
+
+async function ghPut(path: string, body: unknown): Promise<void> {
+	const tmpDir = await mkdtemp(join(tmpdir(), "claude-attribution-api-"));
+	const tmpFile = join(tmpDir, "body.json");
+	try {
+		await writeFile(tmpFile, JSON.stringify(body), { flag: "wx" });
+		await execFileAsync("gh", [
+			"api",
+			path,
+			"--method",
+			"PUT",
+			"--input",
+			tmpFile,
+		]);
+	} finally {
+		await unlink(tmpFile).catch(() => {});
+		await rmdir(tmpDir).catch(() => {});
+	}
+}
+
+async function ghPatch(path: string, body: unknown): Promise<void> {
+	const tmpDir = await mkdtemp(join(tmpdir(), "claude-attribution-api-"));
+	const tmpFile = join(tmpDir, "body.json");
+	try {
+		await writeFile(tmpFile, JSON.stringify(body), { flag: "wx" });
+		await execFileAsync("gh", [
+			"api",
+			path,
+			"--method",
+			"PATCH",
+			"--input",
+			tmpFile,
+		]);
+	} finally {
+		await unlink(tmpFile).catch(() => {});
+		await rmdir(tmpDir).catch(() => {});
+	}
+}
+
+// ─── Detection ────────────────────────────────────────────────────────────────
+
+async function getClassicStatus(
+	slug: string,
+	branch: string,
+): Promise<ClassicStatus | null> {
+	const data = await ghGet(`repos/${slug}/branches/${branch}/protection`);
+	if (!data) return null;
+
+	const prot = data as {
+		required_status_checks?: {
+			strict: boolean;
+			contexts?: string[];
+			checks?: Check[];
+		};
+	};
+
+	const rsc = prot.required_status_checks;
+	if (!rsc) {
+		// Protection exists but no required status checks configured yet
+		return {
+			branch,
+			strict: false,
+			checks: [],
+			hasOurCheck: false,
+		};
+	}
+
+	const checks: Check[] =
+		rsc.checks && rsc.checks.length > 0
+			? rsc.checks
+			: (rsc.contexts ?? []).map((c) => ({ context: c, app_id: -1 }));
+
+	return {
+		branch,
+		strict: rsc.strict,
+		checks,
+		hasOurCheck: checks.some((c) => c.context === WORKFLOW_CHECK_NAME),
+	};
+}
+
+async function getRulesetStatuses(slug: string): Promise<RulesetStatus[]> {
+	const list = await ghGet(`repos/${slug}/rulesets`);
+	if (!Array.isArray(list) || list.length === 0) return [];
+
+	// Fetch full details for each ruleset in parallel (rules not in list response)
+	const results = await Promise.all(
+		(list as Array<{ id: number }>).map(async (rs) => {
+			const full = (await ghGet(
+				`repos/${slug}/rulesets/${rs.id}`,
+			)) as RawRuleset | null;
+			if (!full) return null;
+
+			const statusCheckRule = full.rules?.find(
+				(r) => r.type === "required_status_checks",
+			);
+			const hasOurCheck =
+				statusCheckRule?.parameters?.required_status_checks?.some(
+					(c) => c.context === WORKFLOW_CHECK_NAME,
+				) ?? false;
+
+			return {
+				id: rs.id,
+				name: full.name,
+				hasOurCheck,
+				raw: full,
+			} satisfies RulesetStatus;
+		}),
+	);
+
+	return results.filter((r): r is RulesetStatus => r !== null);
+}
+
+/** Extract "owner/repo" from SSH or HTTPS origin remote URL. */
+export function remoteUrlToSlug(url: string): string | null {
+	const m =
+		url.match(/github\.com[:/]([^/]+\/[^/]+?)(?:\.git)?$/) ??
+		url.match(/github\.com\/([^/]+\/[^/]+?)(?:\.git)?$/);
+	return m?.[1] ?? null;
+}
+
+// ─── Modification ─────────────────────────────────────────────────────────────
+
+async function addToClassic(
+	classic: ClassicStatus,
+	slug: string,
+): Promise<void> {
+	await ghPatch(
+		`repos/${slug}/branches/${classic.branch}/protection/required_status_checks`,
+		{
+			strict: classic.strict,
+			checks: [
+				...classic.checks,
+				{ context: WORKFLOW_CHECK_NAME, app_id: GITHUB_ACTIONS_APP_ID },
+			],
+		},
+	);
+}
+
+async function addToRuleset(rs: RulesetStatus, slug: string): Promise<void> {
+	const rules = rs.raw.rules ?? [];
+	const existingRule = rules.find((r) => r.type === "required_status_checks");
+
+	let updatedRules: RawRule[];
+	if (existingRule) {
+		const existingChecks =
+			existingRule.parameters?.required_status_checks ?? [];
+		updatedRules = rules.map((r) =>
+			r.type === "required_status_checks"
+				? {
+						...r,
+						parameters: {
+							...r.parameters,
+							required_status_checks: [
+								...existingChecks,
+								{
+									context: WORKFLOW_CHECK_NAME,
+									integration_id: GITHUB_ACTIONS_APP_ID,
+								},
+							],
+						},
+					}
+				: r,
+		);
+	} else {
+		// No required_status_checks rule yet — add one
+		updatedRules = [
+			...rules,
+			{
+				type: "required_status_checks",
+				parameters: {
+					strict_required_status_checks_policy: false,
+					required_status_checks: [
+						{
+							context: WORKFLOW_CHECK_NAME,
+							integration_id: GITHUB_ACTIONS_APP_ID,
+						},
+					],
+				},
+			},
+		];
+	}
+
+	await ghPut(`repos/${slug}/rulesets/${rs.id}`, {
+		...rs.raw,
+		rules: updatedRules,
+	});
+}
+
+// ─── Prompts ──────────────────────────────────────────────────────────────────
+
+async function promptYesNo(question: string): Promise<boolean> {
+	if (!process.stdin.isTTY) return false;
+	const rl = createInterface({ input: process.stdin, output: process.stdout });
+	return new Promise((resolve) => {
+		rl.question(question, (answer) => {
+			rl.close();
+			resolve(answer.trim().toLowerCase() === "y");
+		});
+	});
+}
+
+async function promptChoice(
+	question: string,
+	options: string[],
+): Promise<number> {
+	if (!process.stdin.isTTY) return -1;
+	const rl = createInterface({ input: process.stdin, output: process.stdout });
+	return new Promise((resolve) => {
+		const numbered = options.map((o, i) => `    [${i + 1}] ${o}`).join("\n");
+		rl.question(`${question}\n${numbered}\n  Choice [1]: `, (answer) => {
+			rl.close();
+			const n = parseInt(answer.trim() || "1", 10);
+			resolve(n >= 1 && n <= options.length ? n - 1 : -1);
+		});
+	});
+}
+
+function printNote(branch: string): void {
+	console.log(
+		`\n  ℹ️  To block merges when this workflow fails, add '${WORKFLOW_CHECK_NAME}'`,
+	);
+	console.log(
+		`      to required status checks for '${branch}' in Settings → Branches or Rules.`,
+	);
+}
+
+// ─── Main entry point ─────────────────────────────────────────────────────────
+
+/**
+ * Detect branch protection on the repo's default branch and offer to add
+ * the workflow job as a required status check. Called from install.ts after
+ * the workflow file is written. Never throws — all errors fall back to a note.
+ */
+export async function configureRequiredCheck(repoRoot: string): Promise<void> {
+	try {
+		const { stdout: remoteOut } = (await execFileAsync(
+			"git",
+			["remote", "get-url", "origin"],
+			{ cwd: repoRoot },
+		)) as unknown as { stdout: string };
+		const slug = remoteUrlToSlug(remoteOut.trim());
+		if (!slug) return;
+
+		const repoData = await ghGet(`repos/${slug}`);
+		const branch = (repoData as { default_branch?: string } | null)
+			?.default_branch;
+		if (!branch) return;
+
+		// Detect both protection types in parallel
+		const [classic, rulesets] = await Promise.all([
+			getClassicStatus(slug, branch),
+			getRulesetStatuses(slug),
+		]);
+
+		// Determine what needs to be added
+		const classicNeeded = classic !== null && !classic.hasOurCheck;
+		const rulesetsNeeded = rulesets.filter((rs) => !rs.hasOurCheck);
+
+		// Already fully configured
+		if (!classicNeeded && rulesetsNeeded.length === 0) {
+			if (classic?.hasOurCheck || rulesets.some((rs) => rs.hasOurCheck)) {
+				console.log(
+					`✓ '${WORKFLOW_CHECK_NAME}' already a required status check`,
+				);
+			}
+			return;
+		}
+
+		// Build the list of targets that need our check
+		const targets: Array<
+			| { kind: "classic"; classic: ClassicStatus }
+			| { kind: "ruleset"; rs: RulesetStatus }
+		> = [];
+		if (classicNeeded) targets.push({ kind: "classic", classic });
+		for (const rs of rulesetsNeeded) targets.push({ kind: "ruleset", rs });
+
+		let chosen: typeof targets;
+
+		if (targets.length === 1) {
+			// Single target — simple yes/no
+			const target = targets[0]!;
+			const label =
+				target.kind === "classic"
+					? `branch protection rule on '${branch}'`
+					: `ruleset '${target.rs.name}'`;
+			console.log(`\n  Branch protection is active on '${branch}'.`);
+			const yes = await promptYesNo(
+				`  Add '${WORKFLOW_CHECK_NAME}' to ${label}? [y/N] `,
+			);
+			if (!yes) {
+				printNote(branch);
+				return;
+			}
+			chosen = targets;
+		} else {
+			// Multiple targets — numbered choice
+			const options = [
+				...targets.map((t) =>
+					t.kind === "classic"
+						? `Branch protection rule on '${branch}'`
+						: `Ruleset: '${t.rs.name}'`,
+				),
+				"Both",
+				"Skip",
+			];
+			console.log(
+				`\n  Multiple branch protection rules active on '${branch}'.`,
+			);
+			console.log(
+				`  Where should '${WORKFLOW_CHECK_NAME}' be added as a required check?`,
+			);
+			const idx = await promptChoice("", options);
+			if (idx === -1 || idx === options.length - 1) {
+				// Skip
+				printNote(branch);
+				return;
+			}
+			if (idx === options.length - 2) {
+				// Both
+				chosen = targets;
+			} else {
+				chosen = [targets[idx]!];
+			}
+		}
+
+		// Apply changes
+		for (const target of chosen) {
+			if (target.kind === "classic") {
+				await addToClassic(target.classic, slug);
+				console.log(
+					`✓ Added '${WORKFLOW_CHECK_NAME}' to branch protection on '${branch}'`,
+				);
+			} else {
+				await addToRuleset(target.rs, slug);
+				console.log(
+					`✓ Added '${WORKFLOW_CHECK_NAME}' to ruleset '${target.rs.name}'`,
+				);
+			}
+		}
+	} catch {
+		console.log(
+			`\n  ℹ️  Could not configure required status checks automatically.`,
+		);
+		console.log(
+			`      To block merges on workflow failure, add '${WORKFLOW_CHECK_NAME}'`,
+		);
+		console.log(
+			`      to required status checks in your branch protection settings.`,
+		);
+	}
+}