claude-attribution 1.2.2 → 1.2.5

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "claude-attribution",
-	"version": "1.2.2",
+	"version": "1.2.5",
 	"description": "AI code attribution tracking for Claude Code sessions — checkpoint-based line diff approach",
 	"type": "module",
 	"bin": {

package/src/setup/install.ts

@@ -5,11 +5,21 @@
  *
  * If no path is given, installs into the current working directory.
  */
-import { readFile, writeFile, appendFile, mkdir } from "fs/promises";
+import {
+	readFile,
+	writeFile,
+	appendFile,
+	mkdir,
+	mkdtemp,
+	unlink,
+	rmdir,
+} from "fs/promises";
 import { existsSync } from "fs";
 import { execFile } from "child_process";
 import { promisify } from "util";
 import { resolve, join } from "path";
+import { tmpdir } from "os";
+import { createInterface } from "readline";
 import {
 	ATTRIBUTION_ROOT,
 	mergeHooks,
@@ -24,6 +34,208 @@ const execFileAsync = promisify(execFile);
 
 const CLI_BIN = resolve(ATTRIBUTION_ROOT, "bin", "claude-attribution");
 
+/**
+ * The exact GitHub Actions job name written into our workflow template.
+ * Must match the `name:` field of the `metrics` job in pr-metrics-workflow.yml.
+ */
+const WORKFLOW_CHECK_NAME = "Claude Code Attribution Metrics";
+
+/** Extract "owner/repo" from an origin remote URL (SSH or HTTPS). */
+function remoteUrlToSlug(url: string): string | null {
+	const m =
+		url.match(/github\.com[:/]([^/]+\/[^/]+?)(?:\.git)?$/) ??
+		url.match(/github\.com\/([^/]+\/[^/]+?)(?:\.git)?$/);
+	return m?.[1] ?? null;
+}
+
+/** Call `gh api <path>` and return parsed JSON, or null on any error. */
+async function ghApiGet(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;
+	}
+}
+
+/** Prompt the user for a yes/no answer. Returns false in non-TTY contexts. */
+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");
+		});
+	});
+}
+
+function printRequiredCheckNote(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.`,
+	);
+}
+
+/**
+ * PATCH the required status checks for a branch via the GitHub API.
+ * Writes the JSON body to a temp file to avoid arg-length issues.
+ */
+async function patchRequiredChecks(
+	slug: string,
+	branch: 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",
+			`repos/${slug}/branches/${branch}/protection/required_status_checks`,
+			"--method",
+			"PATCH",
+			"--input",
+			tmpFile,
+		]);
+	} finally {
+		await unlink(tmpFile).catch(() => {});
+		await rmdir(tmpDir).catch(() => {});
+	}
+}
+
+/**
+ * After installing the workflow, check branch protection / rulesets and offer
+ * to add our workflow job as a required status check.
+ *
+ * - Classic branch protection: fully automatic (detect → prompt → PATCH)
+ * - Rulesets: detect only → informational note (ruleset API requires full PUT)
+ * - Any error or non-TTY: fall back to informational note
+ */
+async function maybeAddRequiredCheck(repoRoot: string): Promise<void> {
+	try {
+		// Resolve the GitHub slug from the origin remote
+		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;
+
+		// Get the default branch name
+		const repoData = await ghApiGet(`repos/${slug}`);
+		const branch = (repoData as { default_branch?: string } | null)
+			?.default_branch;
+		if (!branch) return;
+
+		// --- Classic branch protection ---
+		const protection = await ghApiGet(
+			`repos/${slug}/branches/${branch}/protection`,
+		);
+
+		if (!protection) {
+			// No classic protection — check rulesets (detect-only)
+			const rulesets = await ghApiGet(`repos/${slug}/rulesets`);
+			if (Array.isArray(rulesets) && rulesets.length > 0) {
+				// Check if any ruleset already requires our check
+				const alreadyRequired = (
+					rulesets as Array<{
+						rules?: Array<{
+							type: string;
+							parameters?: {
+								required_status_checks?: Array<{ context: string }>;
+							};
+						}>;
+					}>
+				).some((rs) =>
+					rs.rules?.some(
+						(r) =>
+							r.type === "required_status_checks" &&
+							r.parameters?.required_status_checks?.some(
+								(c) => c.context === WORKFLOW_CHECK_NAME,
+							),
+					),
+				);
+				if (alreadyRequired) {
+					console.log(
+						`✓ '${WORKFLOW_CHECK_NAME}' already a required status check`,
+					);
+					return;
+				}
+				console.log(
+					`\n  ℹ️  Ruleset branch protection detected on '${branch}'.`,
+				);
+				console.log(
+					`      Add '${WORKFLOW_CHECK_NAME}' to required status checks`,
+				);
+				console.log(
+					`      in Settings → Rules to block merges on workflow failure.`,
+				);
+			}
+			return;
+		}
+
+		// Extract current required check names from classic protection
+		type Check = { context: string; app_id: number };
+		const prot = protection as {
+			required_status_checks?: {
+				strict: boolean;
+				contexts?: string[];
+				checks?: Check[];
+			};
+		};
+		const existingChecks: Check[] =
+			prot.required_status_checks?.checks ??
+			(prot.required_status_checks?.contexts ?? []).map((c) => ({
+				context: c,
+				app_id: -1,
+			}));
+		const strict = prot.required_status_checks?.strict ?? false;
+
+		if (existingChecks.some((c) => c.context === WORKFLOW_CHECK_NAME)) {
+			console.log(`✓ '${WORKFLOW_CHECK_NAME}' already a required status check`);
+			return;
+		}
+
+		// Prompt
+		console.log(`\n  Branch protection is active on '${branch}'.`);
+		const yes = await promptYesNo(
+			`  Add '${WORKFLOW_CHECK_NAME}' as a required status check? [y/N] `,
+		);
+		if (!yes) {
+			printRequiredCheckNote(branch);
+			return;
+		}
+
+		await patchRequiredChecks(slug, branch, {
+			strict,
+			checks: [...existingChecks, { context: WORKFLOW_CHECK_NAME, app_id: -1 }],
+		});
+		console.log(
+			`✓ Added '${WORKFLOW_CHECK_NAME}' as a required status check on '${branch}'`,
+		);
+	} catch {
+		// Any failure — don't break install, just print the note
+		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.`,
+		);
+	}
+}
+
 async function main() {
 	const args = process.argv.slice(2);
 	const runnerFlagIdx = args.findIndex((a: string) => a === "--runner");
@@ -78,23 +290,34 @@ async function main() {
 	const hookResult = await installGitHook(targetRepo);
 	if (hookResult === "noop") {
 		console.log("");
-		console.log("  ⚠️  Lefthook detected. Add this to lefthook.yml manually:");
-		console.log("  post-commit:");
+		console.log(
+			"  ⚠️  Could not auto-edit lefthook config (unusual structure).",
+		);
+		console.log(
+			"  Add this to your lefthook config under post-commit manually:",
+		);
 		console.log("    commands:");
 		console.log("      claude-attribution:");
 		console.log("        run: claude-attribution hook post-commit || true");
 		console.log("");
-		console.log(
-			"  (skipped automatic hook install — Lefthook manages .git/hooks/)",
-		);
 	} else if (hookResult === "created") {
 		const hookPath =
 			manager === "husky" ? ".husky/post-commit" : ".git/hooks/post-commit";
 		console.log(`✓ Created ${hookPath}`);
 	} else if (hookResult === "appended") {
-		const hookPath =
-			manager === "husky" ? ".husky/post-commit" : ".git/hooks/post-commit";
-		console.log(`✓ Appended to existing ${hookPath}`);
+		const lefthookConfigFile =
+			manager === "lefthook"
+				? (["lefthook.yml", "lefthook.yaml", ".lefthook.yml"].find((name) =>
+						existsSync(join(targetRepo, name)),
+					) ?? "lefthook.yml")
+				: undefined;
+		const hookFile =
+			manager === "husky"
+				? ".husky/post-commit"
+				: manager === "lefthook"
+					? lefthookConfigFile!
+					: ".git/hooks/post-commit";
+		console.log(`✓ Added post-commit entry to ${hookFile}`);
 	} else {
 		// unchanged
 		console.log("✓ post-commit hook already up to date");
@@ -163,7 +386,10 @@ async function main() {
 		`✓ Installed .github/workflows/claude-attribution-pr.yml — runner: ${runsOn}${detectedNote}`,
 	);
 
-	// 5. Record installed version for auto-upgrade tracking
+	// 5. Check branch protection and offer to add required status check
+	await maybeAddRequiredCheck(targetRepo);
+
+	// 6. Record installed version for auto-upgrade tracking
 	const pkg = JSON.parse(
 		await readFile(join(ATTRIBUTION_ROOT, "package.json"), "utf8"),
 	) as { version: string };

package/src/setup/shared.ts

@@ -81,13 +81,111 @@ export type GitHookInstallResult =
 	| "created" // wrote a new hook file
 	| "appended" // appended to an existing hook file
 	| "unchanged" // hook already contained our entry; nothing written
-	| "noop"; // Lefthook detected — manual config required, nothing written
+	| "noop"; // could not auto-edit (complex YAML structure) — manual config required
+
+/** Lefthook config filenames, in priority order. Only YAML files are auto-edited. */
+const LEFTHOOK_CONFIG_FILES = [
+	"lefthook.yml",
+	"lefthook.yaml",
+	".lefthook.yml",
+	"lefthook.json", // JSON files: detect-only, never auto-edited
+	".lefthook.json",
+];
+
+/**
+ * Attempt to add our post-commit entry to a lefthook YAML config file.
+ *
+ * Cases handled automatically:
+ *   1. No post-commit section → append our block at end of file
+ *   2. post-commit + commands section exists → detect indentation, insert entry
+ *
+ * Falls back to "noop" only when the post-commit section has an unrecognised
+ * structure (e.g. uses `scripts:` instead of `commands:`, or non-standard YAML).
+ * Returns "unchanged" if already configured.
+ */
+async function tryInstallLefthookYaml(
+	configPath: string,
+): Promise<GitHookInstallResult> {
+	const content = await readFile(configPath, "utf8");
+
+	if (content.includes("claude-attribution")) return "unchanged";
+
+	const RUN_CMD = "claude-attribution hook post-commit || true";
+
+	// Case 1: no post-commit section — append entire block at the end.
+	if (!/^post-commit:/m.test(content)) {
+		await writeFile(
+			configPath,
+			content.trimEnd() +
+				"\n\npost-commit:\n  commands:\n    claude-attribution:\n      run: " +
+				RUN_CMD +
+				"\n",
+		);
+		return "appended";
+	}
+
+	// Case 2: post-commit section exists — find the commands: block and insert.
+	const lines = content.split("\n");
+	const postCommitIdx = lines.findIndex((l) => /^post-commit:/.test(l ?? ""));
+	if (postCommitIdx === -1) return "noop";
+
+	// Find the commands: line within the post-commit block.
+	let commandsIdx = -1;
+	for (let i = postCommitIdx + 1; i < lines.length; i++) {
+		const line = lines[i] ?? "";
+		if (!line.trim()) continue;
+		if (/^\S/.test(line)) break; // hit another top-level key
+		if (/^\s+commands:\s*$/.test(line)) {
+			commandsIdx = i;
+			break;
+		}
+	}
+	if (commandsIdx === -1) return "noop"; // uses scripts: or unusual structure
+
+	// Detect indentation from the commands: line itself.
+	const commandsLine = lines[commandsIdx] ?? "";
+	const baseIndent = commandsLine.match(/^(\s+)/)?.[1] ?? "  ";
+	const cmdIndent = baseIndent + "  ";
+	const propIndent = cmdIndent + "  ";
+
+	// Find the last indented line of the commands block.
+	// Stop when we reach a top-level key OR when indentation returns to
+	// baseIndent.length or less (i.e. a sibling key of commands:, such as
+	// parallel: or runner:, that would otherwise be treated as a command entry).
+	let insertAfterIdx = commandsIdx;
+	for (let i = commandsIdx + 1; i < lines.length; i++) {
+		const line = lines[i] ?? "";
+		if (!line.trim()) continue;
+		if (/^\S/.test(line)) break;
+		const indentLength = (line.match(/^(\s*)/) ?? ["", ""])[1]?.length ?? 0;
+		if (indentLength <= baseIndent.length) break;
+		insertAfterIdx = i;
+	}
+
+	const entry = [
+		`${cmdIndent}claude-attribution:`,
+		`${propIndent}run: ${RUN_CMD}`,
+	];
+	const newLines = [
+		...lines.slice(0, insertAfterIdx + 1),
+		...entry,
+		...lines.slice(insertAfterIdx + 1),
+	];
+	await writeFile(configPath, newLines.join("\n"));
+	return "appended";
+}
 
 /**
  * Install the post-commit git hook, respecting husky/lefthook if present.
  * Idempotent — safe to call on already-installed repos.
- * Note: for Lefthook repos this is a no-op (manual config required).
- * Returns a GitHookInstallResult describing what was done.
+ *
+ * Lefthook: auto-edits the YAML config to add our command entry. Falls back
+ * to "noop" (with manual instructions) only for unusual config structures.
+ *
+ * Husky: appends to .husky/post-commit if present; creates it if not.
+ *
+ * Plain git hooks: surgically appends our entry. Returns "unchanged" if
+ * already present — never clobbers hooks written by other tools.
  */
 export async function installGitHook(
 	repoRoot: string,
@@ -118,11 +216,31 @@ export async function installGitHook(
 	}
 
 	if (manager === "lefthook") {
-		// Cannot safely auto-edit YAML — caller should inform the user
+		// Try to auto-edit the YAML config; fall back to noop for JSON or
+		// complex structures that are not safe to modify programmatically.
+		for (const configFile of LEFTHOOK_CONFIG_FILES) {
+			const configPath = join(repoRoot, configFile);
+			if (!existsSync(configPath)) continue;
+			if (!configFile.endsWith(".yml") && !configFile.endsWith(".yaml")) {
+				// JSON config: detect-only, never auto-edit
+				try {
+					const content = await readFile(configPath, "utf8");
+					if (content.includes("claude-attribution")) return "unchanged";
+				} catch {
+					// skip
+				}
+				continue;
+			}
+			try {
+				return await tryInstallLefthookYaml(configPath);
+			} catch {
+				return "noop";
+			}
+		}
 		return "noop";
 	}
 
-	// Plain git hooks
+	// Plain git hooks — surgical append only, never overwrite the whole file.
 	const hookDest = join(repoRoot, ".git", "hooks", "post-commit");
 	const template = await readFile(
 		join(ATTRIBUTION_ROOT, "src", "setup", "templates", "post-commit.sh"),
@@ -131,15 +249,16 @@ export async function installGitHook(
 
 	if (existsSync(hookDest)) {
 		const existing = await readFile(hookDest, "utf8");
-		if (!existing.includes("claude-attribution")) {
-			await writeFile(
-				hookDest,
-				existing.trimEnd() + "\n\n# claude-attribution\n" + template,
-			);
-			await chmod(hookDest, 0o755);
-			return "appended";
+		if (existing.includes("claude-attribution")) {
+			// Already present — do not overwrite other hooks in the file.
+			return "unchanged";
 		}
-		// Already ours — replace with latest template
+		await writeFile(
+			hookDest,
+			existing.trimEnd() + "\n\n# claude-attribution\n" + template,
+		);
+		await chmod(hookDest, 0o755);
+		return "appended";
 	}
 
 	await writeFile(hookDest, template);