@ag-eco/agentplate-cli 0.13.0

package/src/commands/hooks.ts

@@ -0,0 +1,263 @@
+/**
+ * CLI command: ap hooks install|uninstall|status
+ *
+ * Manages orchestrator hooks in .claude/settings.local.json.
+ * Hooks are sourced from .agentplate/hooks.json (generated by ap init).
+ *
+ * This keeps the canonical hook configuration in .agentplate/ while placing
+ * a minimal copy in .claude/ only when the user explicitly opts in.
+ * Running `ap init` alone does NOT modify .claude/ — the user must
+ * run `ap hooks install` as a separate step.
+ */
+
+import { mkdir, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { Command } from "commander";
+import { loadConfig } from "../config.ts";
+import { ValidationError } from "../errors.ts";
+import { jsonOutput } from "../json.ts";
+import { printHint, printSuccess, printWarning } from "../logging/color.ts";
+
+interface HookEntry {
+	matcher: string;
+	hooks: ReadonlyArray<{ type: string; command: string }>;
+}
+
+function isDuplicateEntry(a: HookEntry, b: HookEntry): boolean {
+	if (a.matcher !== b.matcher) return false;
+	if (a.hooks.length !== b.hooks.length) return false;
+	return a.hooks.every((cmd, i) => {
+		const bCmd = b.hooks[i];
+		return bCmd !== undefined && bCmd.type === cmd.type && bCmd.command === cmd.command;
+	});
+}
+
+/**
+ * Merge two hook maps by event type, deduplicating entries with identical
+ * matcher + command list pairs. Preserves all existing entries and appends
+ * only non-duplicate incoming entries per event type.
+ */
+export function mergeHooksByEventType(
+	existing: Record<string, unknown[]>,
+	incoming: Record<string, unknown[]>,
+): Record<string, unknown[]> {
+	const merged: Record<string, unknown[]> = { ...existing };
+
+	for (const [eventType, incomingEntries] of Object.entries(incoming)) {
+		if (!(eventType in merged)) {
+			merged[eventType] = incomingEntries;
+			continue;
+		}
+
+		const existingEntries = merged[eventType] ?? [];
+		const toAdd: unknown[] = [];
+
+		for (const entry of incomingEntries) {
+			const incomingEntry = entry as HookEntry;
+			const isDupe = existingEntries.some((e) => isDuplicateEntry(e as HookEntry, incomingEntry));
+			if (!isDupe) {
+				toAdd.push(entry);
+			}
+		}
+
+		merged[eventType] = [...existingEntries, ...toAdd];
+	}
+
+	return merged;
+}
+
+/**
+ * Install orchestrator hooks from .agentplate/hooks.json to .claude/settings.local.json.
+ *
+ * Reads the canonical hook config from .agentplate/hooks.json and writes it to
+ * .claude/settings.local.json where Claude Code discovers it. Preserves any
+ * existing non-hooks keys in the target file.
+ */
+async function installHooks(force: boolean): Promise<void> {
+	const cwd = process.cwd();
+	const config = await loadConfig(cwd);
+	const projectRoot = config.project.root;
+
+	// Read source hooks from .agentplate/hooks.json
+	const sourcePath = join(projectRoot, ".agentplate", "hooks.json");
+	const sourceFile = Bun.file(sourcePath);
+	if (!(await sourceFile.exists())) {
+		throw new ValidationError("No hooks.json found in .agentplate/. Run 'ap init' first.", {
+			field: "source",
+		});
+	}
+
+	const sourceContent = await sourceFile.text();
+	const sourceHooks = JSON.parse(sourceContent) as Record<string, unknown>;
+
+	// Check target .claude/settings.local.json
+	const targetDir = join(projectRoot, ".claude");
+	const targetPath = join(targetDir, "settings.local.json");
+	const targetFile = Bun.file(targetPath);
+
+	let targetConfig: Record<string, unknown> = {};
+	if (await targetFile.exists()) {
+		const existingContent = await targetFile.text();
+		const existing = JSON.parse(existingContent) as Record<string, unknown>;
+
+		if (existing.hooks && !force) {
+			process.stdout.write(
+				"Hooks already present in .claude/settings.local.json\nUse --force to overwrite.\n",
+			);
+			return;
+		}
+
+		// Preserve non-hooks keys (e.g., env settings)
+		targetConfig = existing;
+	}
+
+	// Merge: set hooks from source, preserve other keys
+	const existingHooks = targetConfig.hooks as Record<string, unknown[]> | undefined;
+	const incomingHooks = sourceHooks.hooks as Record<string, unknown[]>;
+	targetConfig.hooks = existingHooks
+		? mergeHooksByEventType(existingHooks, incomingHooks)
+		: incomingHooks;
+
+	// Write
+	await mkdir(targetDir, { recursive: true });
+	await Bun.write(targetPath, `${JSON.stringify(targetConfig, null, "\t")}\n`);
+
+	printSuccess("Installed orchestrator hooks");
+	printHint("Source: .agentplate/hooks.json");
+}
+
+/**
+ * Remove orchestrator hooks from .claude/settings.local.json.
+ *
+ * If hooks were the only content, removes the file entirely.
+ * Otherwise, preserves other keys and only removes the hooks key.
+ */
+async function uninstallHooks(): Promise<void> {
+	const cwd = process.cwd();
+	const config = await loadConfig(cwd);
+	const projectRoot = config.project.root;
+
+	const targetPath = join(projectRoot, ".claude", "settings.local.json");
+	const targetFile = Bun.file(targetPath);
+
+	if (!(await targetFile.exists())) {
+		printWarning("No .claude/settings.local.json found", "nothing to uninstall");
+		return;
+	}
+
+	const content = await targetFile.text();
+	const parsed = JSON.parse(content) as Record<string, unknown>;
+
+	if (!parsed.hooks) {
+		process.stdout.write(
+			"No hooks found in .claude/settings.local.json \u2014 nothing to uninstall.\n",
+		);
+		return;
+	}
+
+	// Separate hooks from other settings
+	const { hooks: _hooks, ...rest } = parsed;
+
+	const remainingKeys = Object.keys(rest);
+	if (remainingKeys.length === 0) {
+		await unlink(targetPath);
+		printSuccess("Removed hooks from settings.local.json");
+	} else {
+		await Bun.write(targetPath, `${JSON.stringify(rest, null, "\t")}\n`);
+		printSuccess("Removed hooks from settings.local.json");
+	}
+}
+
+/**
+ * Show hooks installation status.
+ */
+async function statusHooks(json: boolean): Promise<void> {
+	const cwd = process.cwd();
+	const config = await loadConfig(cwd);
+	const projectRoot = config.project.root;
+
+	const sourcePath = join(projectRoot, ".agentplate", "hooks.json");
+	const targetPath = join(projectRoot, ".claude", "settings.local.json");
+
+	const sourceExists = await Bun.file(sourcePath).exists();
+	const targetExists = await Bun.file(targetPath).exists();
+
+	let installed = false;
+	if (targetExists) {
+		const content = await Bun.file(targetPath).text();
+		const parsed = JSON.parse(content) as Record<string, unknown>;
+		installed = !!parsed.hooks;
+	}
+
+	if (json) {
+		jsonOutput("hooks status", { sourceExists, installed });
+	} else {
+		process.stdout.write(
+			`Hooks source (.agentplate/hooks.json): ${sourceExists ? "present" : "missing"}\n`,
+		);
+		process.stdout.write(
+			`Hooks installed (.claude/settings.local.json): ${installed ? "yes" : "no"}\n`,
+		);
+		if (!installed && sourceExists) {
+			printHint("Run ap hooks install to install");
+		}
+	}
+}
+
+export function createHooksCommand(): Command {
+	const cmd = new Command("hooks").description("Manage orchestrator hooks");
+
+	cmd
+		.command("install")
+		.description("Install orchestrator hooks to .claude/settings.local.json")
+		.option("--force", "Overwrite existing hooks")
+		.action(async (opts: { force?: boolean }) => {
+			await installHooks(opts.force ?? false);
+		});
+
+	cmd
+		.command("uninstall")
+		.description("Remove orchestrator hooks from .claude/settings.local.json")
+		.action(async () => {
+			await uninstallHooks();
+		});
+
+	cmd
+		.command("status")
+		.description("Check if hooks are installed")
+		.option("--json", "Output as JSON")
+		.action(async (opts: { json?: boolean }) => {
+			await statusHooks(opts.json ?? false);
+		});
+
+	return cmd;
+}
+
+/**
+ * Entry point for `ap hooks <subcommand>`.
+ */
+export async function hooksCommand(args: string[]): Promise<void> {
+	const cmd = createHooksCommand();
+	cmd.exitOverride();
+
+	if (args.length === 0) {
+		process.stdout.write(cmd.helpInformation());
+		return;
+	}
+
+	try {
+		await cmd.parseAsync(args, { from: "user" });
+	} catch (err: unknown) {
+		if (err && typeof err === "object" && "code" in err) {
+			const code = (err as { code: string }).code;
+			if (code === "commander.helpDisplayed" || code === "commander.version") {
+				return;
+			}
+			if (code === "commander.unknownCommand") {
+				const message = err instanceof Error ? err.message : String(err);
+				throw new ValidationError(message, { field: "subcommand" });
+			}
+		}
+		throw err;
+	}
+}