claude-attribution 1.1.1 → 1.1.2

package/package.json

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

package/src/commands/pr.ts

@@ -133,11 +133,25 @@ async function main() {
 		body = template.trimEnd() + "\n\n" + metricsBlock;
 	}
 
-	// Push branch to remote if not already pushed
+	// Push branch to remote. If the branch already has a remote tracking ref,
+	// push any new commits (no-op if up-to-date). Otherwise set tracking with -u.
 	try {
-		await execFileAsync("git", ["push", "-u", "origin", "HEAD"], {
-			cwd: repoRoot,
-		});
+		const hasUpstream = await execFileAsync(
+			"git",
+			["rev-parse", "--abbrev-ref", "@{upstream}"],
+			{ cwd: repoRoot },
+		).then(
+			() => true,
+			() => false,
+		);
+		if (hasUpstream) {
+			// Branch already pushed — push any new commits, ignore "already up-to-date"
+			await execFileAsync("git", ["push"], { cwd: repoRoot }).catch(() => {});
+		} else {
+			await execFileAsync("git", ["push", "-u", "origin", "HEAD"], {
+				cwd: repoRoot,
+			});
+		}
 	} catch (err) {
 		const msg = err instanceof Error ? err.message : String(err);
 		console.error(`Error pushing branch: ${msg}`);

package/src/hooks/pre-tool-use.ts

@@ -17,6 +17,7 @@ import {
 	writeCurrentSession,
 } from "../attribution/checkpoint.ts";
 import { readStdin, WRITE_TOOLS, getFilePath } from "../lib/hooks.ts";
+import { maybeAutoUpgrade } from "../lib/auto-upgrade.ts";
 import {
 	otelEndpoint,
 	otelHeaders,
@@ -44,13 +45,21 @@ async function main() {
 	}
 
 	const { session_id, tool_name, tool_input } = payload;
+	const repoRoot = resolve(process.cwd());
+
+	// Auto-upgrade: runs at most once per session, non-fatal
+	try {
+		await maybeAutoUpgrade(repoRoot, session_id);
+	} catch {
+		// Never block Claude
+	}
+
 	if (!WRITE_TOOLS.has(tool_name)) process.exit(0);
 
 	const filePath = getFilePath(tool_input);
 	if (!filePath) process.exit(0);
 
 	const absPath = resolve(filePath);
-	const repoRoot = resolve(process.cwd());
 
 	try {
 		// Only save before-checkpoint if one doesn't already exist for this session+file.

package/src/lib/auto-upgrade.ts

@@ -0,0 +1,110 @@
+/**
+ * Auto-upgrade — transparently applies structural hook/command updates when
+ * the installed CLI version in a repo is older than the running CLI version.
+ *
+ * Called from pre-tool-use.ts on the first tool invocation of each session.
+ * Never throws — all errors are swallowed silently.
+ */
+import { readFile, writeFile, mkdir } from "fs/promises";
+import { existsSync } from "fs";
+import { join, dirname } from "path";
+import { SESSION_ID_RE } from "../attribution/checkpoint.ts";
+import {
+	ATTRIBUTION_ROOT,
+	mergeHooks,
+	installGitHook,
+	installSlashCommands,
+	installCiWorkflow,
+	type HooksConfig,
+} from "../setup/shared.ts";
+
+const CHECKPOINT_BASE = "/tmp/claude-attribution";
+
+/** Returns true if semver string `a` is strictly greater than `b`. */
+function newerThan(a: string, b: string): boolean {
+	const pa = a.split(".").map(Number);
+	const pb = b.split(".").map(Number);
+	for (let i = 0; i < 3; i++) {
+		if ((pa[i] ?? 0) > (pb[i] ?? 0)) return true;
+		if ((pa[i] ?? 0) < (pb[i] ?? 0)) return false;
+	}
+	return false;
+}
+
+/**
+ * Check whether the repo's installed claude-attribution version is older than
+ * the running CLI, and if so apply structural updates (hooks, slash commands,
+ * git hook, CI workflow). Runs at most once per session via a tmp flag file.
+ */
+export async function maybeAutoUpgrade(
+	repoRoot: string,
+	sessionId: string,
+): Promise<void> {
+	try {
+		// Validate sessionId before use as a filesystem path component
+		if (!SESSION_ID_RE.test(sessionId)) return;
+
+		// Session-scoped dedup: only run once per session
+		const sessionTmpDir = join(CHECKPOINT_BASE, sessionId);
+		const flagFile = join(sessionTmpDir, "upgrade-checked");
+		if (existsSync(flagFile)) return;
+
+		await mkdir(CHECKPOINT_BASE, { recursive: true });
+		await mkdir(sessionTmpDir, { recursive: true, mode: 0o700 });
+		await writeFile(flagFile, "");
+
+		const versionFile = join(
+			repoRoot,
+			".claude",
+			"attribution-state",
+			"installed-version",
+		);
+
+		// Read CLI version
+		const pkg = JSON.parse(
+			await readFile(join(ATTRIBUTION_ROOT, "package.json"), "utf8"),
+		) as { version: string };
+		const cliVersion = pkg.version;
+
+		if (!existsSync(versionFile)) {
+			// Pre-existing install that predates version tracking. Bootstrap the
+			// file so future upgrades work automatically — no structural changes yet.
+			await mkdir(dirname(versionFile), { recursive: true });
+			await writeFile(versionFile, cliVersion);
+			return;
+		}
+
+		const installedVersion = (await readFile(versionFile, "utf8")).trim();
+		if (!installedVersion || !newerThan(cliVersion, installedVersion)) return;
+
+		// Apply structural updates — each step is best-effort
+		const settingsPath = join(repoRoot, ".claude", "settings.json");
+		const hooksConfig = JSON.parse(
+			await readFile(
+				join(ATTRIBUTION_ROOT, "src", "setup", "templates", "hooks.json"),
+				"utf8",
+			),
+		) as HooksConfig;
+
+		try {
+			await mergeHooks(settingsPath, hooksConfig);
+		} catch {}
+		try {
+			await installSlashCommands(repoRoot);
+		} catch {}
+		try {
+			await installGitHook(repoRoot);
+		} catch {}
+		try {
+			await installCiWorkflow(repoRoot);
+		} catch {}
+
+		await mkdir(dirname(versionFile), { recursive: true });
+		await writeFile(versionFile, cliVersion);
+		process.stderr.write(
+			`claude-attribution: auto-upgraded ${installedVersion} → ${cliVersion}\n`,
+		);
+	} catch {
+		// Never block Claude
+	}
+}

package/src/setup/install.ts

@@ -5,140 +5,25 @@
  *
  * If no path is given, installs into the current working directory.
  */
-import { readFile, writeFile, appendFile, chmod, mkdir } from "fs/promises";
+import { readFile, writeFile, appendFile, mkdir } from "fs/promises";
 import { existsSync } from "fs";
 import { execFile } from "child_process";
 import { promisify } from "util";
-import { resolve, join, dirname } from "path";
-import { fileURLToPath } from "url";
+import { resolve, join } from "path";
+import {
+	ATTRIBUTION_ROOT,
+	mergeHooks,
+	installGitHook,
+	installSlashCommands,
+	installCiWorkflow,
+	detectHookManager,
+	type HooksConfig,
+} from "./shared.ts";
 
 const execFileAsync = promisify(execFile);
 
-const ATTRIBUTION_ROOT = resolve(
-	dirname(fileURLToPath(import.meta.url)),
-	"..",
-	"..",
-);
 const CLI_BIN = resolve(ATTRIBUTION_ROOT, "bin", "claude-attribution");
 
-interface HookEntry {
-	matcher: string;
-	hooks: Array<{ type: string; command: string }>;
-}
-
-type HooksConfig = Record<string, HookEntry[]>;
-
-interface ClaudeSettings {
-	hooks?: HooksConfig;
-	[key: string]: unknown;
-}
-
-async function mergeHooks(
-	settingsPath: string,
-	newHooks: HooksConfig,
-): Promise<void> {
-	let settings: ClaudeSettings = {};
-	if (existsSync(settingsPath)) {
-		const raw = await readFile(settingsPath, "utf8");
-		settings = JSON.parse(raw) as ClaudeSettings;
-	}
-
-	const existing = settings.hooks ?? {};
-
-	for (const [event, entries] of Object.entries(newHooks)) {
-		const current = existing[event] ?? [];
-		// Remove any existing claude-attribution entries, then push all new ones
-		const filtered = current.filter(
-			(e) => !e.hooks.some((h) => h.command.includes("claude-attribution")),
-		);
-		filtered.push(...entries);
-		existing[event] = filtered;
-	}
-
-	settings.hooks = existing;
-	await writeFile(settingsPath, JSON.stringify(settings, null, 2) + "\n");
-}
-
-/**
- * Detect whether the repo uses Husky or Lefthook to manage git hooks.
- * These tools own .git/hooks/ themselves — we must not write there directly.
- * Instead we register via their config files.
- */
-function detectHookManager(repoRoot: string): "husky" | "lefthook" | "none" {
-	if (existsSync(join(repoRoot, ".husky"))) return "husky";
-	if (
-		existsSync(join(repoRoot, "lefthook.yml")) ||
-		existsSync(join(repoRoot, "lefthook.yaml")) ||
-		existsSync(join(repoRoot, "lefthook.json")) ||
-		existsSync(join(repoRoot, ".lefthook.yml")) ||
-		existsSync(join(repoRoot, ".lefthook.json"))
-	)
-		return "lefthook";
-	return "none";
-}
-
-async function installGitHook(repoRoot: string): Promise<void> {
-	const manager = detectHookManager(repoRoot);
-	const runLine = `claude-attribution hook post-commit || true`;
-
-	if (manager === "husky") {
-		// Husky: add post-commit file to .husky/ directory
-		const huskyHook = join(repoRoot, ".husky", "post-commit");
-		if (existsSync(huskyHook)) {
-			const existing = await readFile(huskyHook, "utf8");
-			if (!existing.includes("claude-attribution")) {
-				await writeFile(
-					huskyHook,
-					existing.trimEnd() + "\n\n# claude-attribution\n" + runLine + "\n",
-				);
-				console.log("  (appended to existing .husky/post-commit)");
-			}
-		} else {
-			await writeFile(
-				huskyHook,
-				`#!/bin/sh\n# claude-attribution\n${runLine}\n`,
-			);
-			await chmod(huskyHook, 0o755);
-		}
-		return;
-	}
-
-	if (manager === "lefthook") {
-		// Lefthook: instruct the user — auto-editing YAML is fragile
-		console.log("");
-		console.log("  ⚠️  Lefthook detected. Add this to lefthook.yml manually:");
-		console.log("  post-commit:");
-		console.log("    commands:");
-		console.log("      claude-attribution:");
-		console.log(`        run: ${runLine}`);
-		console.log("");
-		return;
-	}
-
-	// Plain git hooks
-	const hookDest = join(repoRoot, ".git", "hooks", "post-commit");
-	const template = await readFile(
-		join(ATTRIBUTION_ROOT, "src", "setup", "templates", "post-commit.sh"),
-		"utf8",
-	);
-
-	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;
-		}
-		// Already ours — replace
-	}
-
-	await writeFile(hookDest, template);
-	await chmod(hookDest, 0o755);
-}
-
 async function main() {
 	const targetRepo = resolve(process.argv[2] ?? process.cwd());
 
@@ -182,8 +67,31 @@ async function main() {
 	console.log("✓ Merged hooks into .claude/settings.json");
 
 	// 2. Install post-commit git hook
-	await installGitHook(targetRepo);
-	console.log("✓ Installed .git/hooks/post-commit");
+	const manager = detectHookManager(targetRepo);
+	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("    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}`);
+	} else {
+		// unchanged
+		console.log("✓ post-commit hook already up to date");
+	}
 
 	// Configure git push to also push notes by default (avoids needing a separate push).
 	// Use --unset-all first so re-running install doesn't accumulate duplicate refspecs,
@@ -211,51 +119,28 @@ async function main() {
 		);
 	}
 
-	// 3. Install /metrics slash command
-	const commandsDir = join(claudeDir, "commands");
-	await mkdir(commandsDir, { recursive: true });
-	const metricsTemplate = await readFile(
-		join(ATTRIBUTION_ROOT, "src", "setup", "templates", "metrics-command.md"),
-		"utf8",
-	);
-	await writeFile(join(commandsDir, "metrics.md"), metricsTemplate);
+	// 3. Install slash commands
+	await installSlashCommands(targetRepo);
 	console.log("✓ Installed .claude/commands/metrics.md (/metrics command)");
-
-	const startTemplate = await readFile(
-		join(ATTRIBUTION_ROOT, "src", "setup", "templates", "start-command.md"),
-		"utf8",
-	);
-	await writeFile(join(commandsDir, "start.md"), startTemplate);
 	console.log("✓ Installed .claude/commands/start.md (/start command)");
-
-	const prTemplate = await readFile(
-		join(ATTRIBUTION_ROOT, "src", "setup", "templates", "pr-command.md"),
-		"utf8",
-	);
-	await writeFile(join(commandsDir, "pr.md"), prTemplate);
 	console.log("✓ Installed .claude/commands/pr.md (/pr command)");
 
 	// 4. Install GitHub Actions workflow for automatic PR metrics injection
-	const workflowsDir = join(targetRepo, ".github", "workflows");
-	await mkdir(workflowsDir, { recursive: true });
-	const workflowTemplate = await readFile(
-		join(
-			ATTRIBUTION_ROOT,
-			"src",
-			"setup",
-			"templates",
-			"pr-metrics-workflow.yml",
-		),
-		"utf8",
-	);
-	await writeFile(
-		join(workflowsDir, "claude-attribution-pr.yml"),
-		workflowTemplate,
-	);
+	await installCiWorkflow(targetRepo);
 	console.log(
 		"✓ Installed .github/workflows/claude-attribution-pr.yml (auto-injects metrics on PR open)",
 	);
 
+	// 5. Record installed version for auto-upgrade tracking
+	const pkg = JSON.parse(
+		await readFile(join(ATTRIBUTION_ROOT, "package.json"), "utf8"),
+	) as { version: string };
+	await writeFile(
+		join(claudeDir, "attribution-state", "installed-version"),
+		pkg.version,
+	);
+	console.log(`✓ Recorded installed version: ${pkg.version}`);
+
 	console.log("\nDone! claude-attribution is active for this repo.");
 	console.log(
 		"Commit .claude/settings.json and .github/workflows/claude-attribution-pr.yml to share with the team.",

package/src/setup/shared.ts

@@ -0,0 +1,189 @@
+/**
+ * Shared setup utilities — used by both install.ts and auto-upgrade.ts.
+ *
+ * No top-level side effects. No console.log — logging is the caller's
+ * responsibility.
+ */
+import { readFile, writeFile, chmod, mkdir } from "fs/promises";
+import { existsSync } from "fs";
+import { resolve, join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+export const ATTRIBUTION_ROOT = resolve(
+	dirname(fileURLToPath(import.meta.url)),
+	"..",
+	"..",
+);
+
+export interface HookEntry {
+	matcher: string;
+	hooks: Array<{ type: string; command: string }>;
+}
+
+export type HooksConfig = Record<string, HookEntry[]>;
+
+export interface ClaudeSettings {
+	hooks?: HooksConfig;
+	[key: string]: unknown;
+}
+
+/**
+ * Merge new hook entries into .claude/settings.json.
+ * Removes any existing claude-attribution entries for each event, then
+ * appends the new ones — safe to call repeatedly.
+ */
+export async function mergeHooks(
+	settingsPath: string,
+	newHooks: HooksConfig,
+): Promise<void> {
+	let settings: ClaudeSettings = {};
+	if (existsSync(settingsPath)) {
+		const raw = await readFile(settingsPath, "utf8");
+		settings = JSON.parse(raw) as ClaudeSettings;
+	}
+
+	const existing = settings.hooks ?? {};
+
+	for (const [event, entries] of Object.entries(newHooks)) {
+		const current = existing[event] ?? [];
+		const filtered = current.filter(
+			(e) => !e.hooks.some((h) => h.command.includes("claude-attribution")),
+		);
+		filtered.push(...entries);
+		existing[event] = filtered;
+	}
+
+	settings.hooks = existing;
+	await writeFile(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+}
+
+/**
+ * Detect whether the repo uses Husky or Lefthook to manage git hooks.
+ * These tools own .git/hooks/ themselves — we must not write there directly.
+ */
+export function detectHookManager(
+	repoRoot: string,
+): "husky" | "lefthook" | "none" {
+	if (existsSync(join(repoRoot, ".husky"))) return "husky";
+	if (
+		existsSync(join(repoRoot, "lefthook.yml")) ||
+		existsSync(join(repoRoot, "lefthook.yaml")) ||
+		existsSync(join(repoRoot, "lefthook.json")) ||
+		existsSync(join(repoRoot, ".lefthook.yml")) ||
+		existsSync(join(repoRoot, ".lefthook.json"))
+	)
+		return "lefthook";
+	return "none";
+}
+
+/** Result returned by installGitHook describing what action was taken. */
+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
+
+/**
+ * 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.
+ */
+export async function installGitHook(
+	repoRoot: string,
+): Promise<GitHookInstallResult> {
+	const manager = detectHookManager(repoRoot);
+	const runLine = `claude-attribution hook post-commit || true`;
+
+	if (manager === "husky") {
+		const huskyHook = join(repoRoot, ".husky", "post-commit");
+		if (existsSync(huskyHook)) {
+			const existing = await readFile(huskyHook, "utf8");
+			if (!existing.includes("claude-attribution")) {
+				await writeFile(
+					huskyHook,
+					existing.trimEnd() + "\n\n# claude-attribution\n" + runLine + "\n",
+				);
+				return "appended";
+			}
+			return "unchanged";
+		} else {
+			await writeFile(
+				huskyHook,
+				`#!/bin/sh\n# claude-attribution\n${runLine}\n`,
+			);
+			await chmod(huskyHook, 0o755);
+			return "created";
+		}
+	}
+
+	if (manager === "lefthook") {
+		// Cannot safely auto-edit YAML — caller should inform the user
+		return "noop";
+	}
+
+	// Plain git hooks
+	const hookDest = join(repoRoot, ".git", "hooks", "post-commit");
+	const template = await readFile(
+		join(ATTRIBUTION_ROOT, "src", "setup", "templates", "post-commit.sh"),
+		"utf8",
+	);
+
+	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";
+		}
+		// Already ours — replace with latest template
+	}
+
+	await writeFile(hookDest, template);
+	await chmod(hookDest, 0o755);
+	return "created";
+}
+
+/**
+ * Install (or overwrite) the slash command files into .claude/commands/.
+ */
+export async function installSlashCommands(repoRoot: string): Promise<void> {
+	const commandsDir = join(repoRoot, ".claude", "commands");
+	await mkdir(commandsDir, { recursive: true });
+
+	const commands = [
+		{ template: "metrics-command.md", dest: "metrics.md" },
+		{ template: "start-command.md", dest: "start.md" },
+		{ template: "pr-command.md", dest: "pr.md" },
+	];
+
+	for (const { template, dest } of commands) {
+		const content = await readFile(
+			join(ATTRIBUTION_ROOT, "src", "setup", "templates", template),
+			"utf8",
+		);
+		await writeFile(join(commandsDir, dest), content);
+	}
+}
+
+/**
+ * Install (or overwrite) the GitHub Actions PR metrics workflow.
+ */
+export async function installCiWorkflow(repoRoot: string): Promise<void> {
+	const workflowsDir = join(repoRoot, ".github", "workflows");
+	await mkdir(workflowsDir, { recursive: true });
+	const content = await readFile(
+		join(
+			ATTRIBUTION_ROOT,
+			"src",
+			"setup",
+			"templates",
+			"pr-metrics-workflow.yml",
+		),
+		"utf8",
+	);
+	await writeFile(join(workflowsDir, "claude-attribution-pr.yml"), content);
+}

package/src/setup/uninstall.ts

@@ -174,6 +174,17 @@ async function main() {
 		console.log("✓ Removed .github/workflows/claude-attribution-pr.yml");
 	}
 
+	// 7. Remove installed-version tracking file
+	const versionFile = join(
+		targetRepo,
+		".claude",
+		"attribution-state",
+		"installed-version",
+	);
+	if (await removeFile(versionFile)) {
+		console.log("✓ Removed .claude/attribution-state/installed-version");
+	}
+
 	console.log("\nDone! claude-attribution has been removed from this repo.");
 	console.log(
 		"Note: .claude/logs/ and .claude/attribution-state/ are preserved.",