@katyella/legio 0.1.0

package/src/commands/hooks.test.ts

@@ -0,0 +1,292 @@
+/**
+ * Tests for legio hooks install/uninstall/status command.
+ *
+ * Uses real temp directories and real filesystem (no mocks needed).
+ * Each test gets an isolated temp directory with minimal .legio/
+ * and .claude/ scaffolding.
+ */
+
+import { access, mkdir, readFile, realpath, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { ValidationError } from "../errors.ts";
+import { cleanupTempDir, createTempGitRepo } from "../test-helpers.ts";
+import { hooksCommand } from "./hooks.ts";
+
+let tempDir: string;
+const originalCwd = process.cwd();
+
+/** Orchestrator hooks content for .legio/hooks.json. */
+const SAMPLE_HOOKS = {
+	hooks: {
+		SessionStart: [
+			{
+				matcher: "",
+				hooks: [{ type: "command", command: "legio prime --agent orchestrator" }],
+			},
+		],
+		Stop: [
+			{
+				matcher: "",
+				hooks: [{ type: "command", command: "legio log session-end --agent orchestrator" }],
+			},
+		],
+	},
+};
+
+/** Capture stdout.write output during a function call. */
+async function captureStdout(fn: () => Promise<void>): Promise<string> {
+	const chunks: string[] = [];
+	const originalWrite = process.stdout.write;
+	process.stdout.write = ((chunk: string) => {
+		chunks.push(chunk);
+		return true;
+	}) as typeof process.stdout.write;
+	try {
+		await fn();
+	} finally {
+		process.stdout.write = originalWrite;
+	}
+	return chunks.join("");
+}
+
+beforeEach(async () => {
+	process.chdir(originalCwd);
+	tempDir = await realpath(await createTempGitRepo());
+
+	// Create minimal .legio/ with config.yaml
+	const legioDir = join(tempDir, ".legio");
+	await mkdir(legioDir, { recursive: true });
+	await writeFile(
+		join(legioDir, "config.yaml"),
+		["project:", "  name: test-project", `  root: ${tempDir}`, "  canonicalBranch: main"].join(
+			"\n",
+		),
+	);
+
+	process.chdir(tempDir);
+});
+
+afterEach(async () => {
+	process.chdir(originalCwd);
+	await cleanupTempDir(tempDir);
+});
+
+describe("hooksCommand help", () => {
+	test("--help outputs help text", async () => {
+		const output = await captureStdout(() => hooksCommand(["--help"]));
+		expect(output).toContain("legio hooks");
+		expect(output).toContain("install");
+		expect(output).toContain("uninstall");
+		expect(output).toContain("status");
+	});
+
+	test("empty args outputs help text", async () => {
+		const output = await captureStdout(() => hooksCommand([]));
+		expect(output).toContain("legio hooks");
+	});
+
+	test("unknown subcommand throws ValidationError", async () => {
+		await expect(hooksCommand(["frobnicate"])).rejects.toThrow(ValidationError);
+	});
+});
+
+describe("hooks install", () => {
+	test("installs hooks from .legio/hooks.json to .claude/settings.local.json", async () => {
+		// Write source hooks
+		await writeFile(
+			join(tempDir, ".legio", "hooks.json"),
+			`${JSON.stringify(SAMPLE_HOOKS, null, "\t")}\n`,
+		);
+
+		await captureStdout(() => hooksCommand(["install"]));
+
+		// Verify target file was created
+		const targetPath = join(tempDir, ".claude", "settings.local.json");
+		const content = await readFile(targetPath, "utf-8");
+		const parsed = JSON.parse(content) as Record<string, unknown>;
+		expect(parsed.hooks).toBeDefined();
+		expect(content).toContain("legio prime");
+	});
+
+	test("preserves existing non-hooks keys in settings.local.json", async () => {
+		await writeFile(
+			join(tempDir, ".legio", "hooks.json"),
+			`${JSON.stringify(SAMPLE_HOOKS, null, "\t")}\n`,
+		);
+
+		// Write existing settings.local.json with non-hooks content
+		const claudeDir = join(tempDir, ".claude");
+		await mkdir(claudeDir, { recursive: true });
+		await writeFile(
+			join(claudeDir, "settings.local.json"),
+			`${JSON.stringify({ env: { SOME_VAR: "1" } }, null, "\t")}\n`,
+		);
+
+		await captureStdout(() => hooksCommand(["install"]));
+
+		const content = await readFile(join(claudeDir, "settings.local.json"), "utf-8");
+		const parsed = JSON.parse(content) as Record<string, unknown>;
+		expect(parsed.hooks).toBeDefined();
+		expect(parsed.env).toEqual({ SOME_VAR: "1" });
+	});
+
+	test("warns when hooks already exist without --force", async () => {
+		await writeFile(
+			join(tempDir, ".legio", "hooks.json"),
+			`${JSON.stringify(SAMPLE_HOOKS, null, "\t")}\n`,
+		);
+
+		const claudeDir = join(tempDir, ".claude");
+		await mkdir(claudeDir, { recursive: true });
+		await writeFile(
+			join(claudeDir, "settings.local.json"),
+			`${JSON.stringify({ hooks: { old: "hooks" } }, null, "\t")}\n`,
+		);
+
+		const output = await captureStdout(() => hooksCommand(["install"]));
+		expect(output).toContain("already present");
+		expect(output).toContain("--force");
+
+		// Verify hooks were NOT overwritten
+		const content = await readFile(join(claudeDir, "settings.local.json"), "utf-8");
+		expect(content).toContain("old");
+	});
+
+	test("--force overwrites existing hooks", async () => {
+		await writeFile(
+			join(tempDir, ".legio", "hooks.json"),
+			`${JSON.stringify(SAMPLE_HOOKS, null, "\t")}\n`,
+		);
+
+		const claudeDir = join(tempDir, ".claude");
+		await mkdir(claudeDir, { recursive: true });
+		await writeFile(
+			join(claudeDir, "settings.local.json"),
+			`${JSON.stringify({ hooks: { old: "hooks" } }, null, "\t")}\n`,
+		);
+
+		await captureStdout(() => hooksCommand(["install", "--force"]));
+
+		const content = await readFile(join(claudeDir, "settings.local.json"), "utf-8");
+		expect(content).not.toContain("old");
+		expect(content).toContain("legio prime");
+	});
+
+	test("throws when .legio/hooks.json does not exist", async () => {
+		await expect(hooksCommand(["install"])).rejects.toThrow(ValidationError);
+	});
+
+	test("writes JSON with trailing newline", async () => {
+		await writeFile(
+			join(tempDir, ".legio", "hooks.json"),
+			`${JSON.stringify(SAMPLE_HOOKS, null, "\t")}\n`,
+		);
+
+		await captureStdout(() => hooksCommand(["install"]));
+
+		const content = await readFile(join(tempDir, ".claude", "settings.local.json"), "utf-8");
+		expect(content.endsWith("\n")).toBe(true);
+	});
+});
+
+describe("hooks uninstall", () => {
+	test("removes hooks-only settings.local.json file entirely", async () => {
+		const claudeDir = join(tempDir, ".claude");
+		await mkdir(claudeDir, { recursive: true });
+		await writeFile(
+			join(claudeDir, "settings.local.json"),
+			`${JSON.stringify({ hooks: { some: "hooks" } }, null, "\t")}\n`,
+		);
+
+		const output = await captureStdout(() => hooksCommand(["uninstall"]));
+		expect(output).toContain("Removed");
+
+		const exists = await access(join(claudeDir, "settings.local.json"))
+			.then(() => true)
+			.catch(() => false);
+		expect(exists).toBe(false);
+	});
+
+	test("preserves non-hooks keys when uninstalling", async () => {
+		const claudeDir = join(tempDir, ".claude");
+		await mkdir(claudeDir, { recursive: true });
+		await writeFile(
+			join(claudeDir, "settings.local.json"),
+			`${JSON.stringify({ hooks: { some: "hooks" }, env: { KEY: "val" } }, null, "\t")}\n`,
+		);
+
+		const output = await captureStdout(() => hooksCommand(["uninstall"]));
+		expect(output).toContain("preserved other settings");
+
+		const content = await readFile(join(claudeDir, "settings.local.json"), "utf-8");
+		const parsed = JSON.parse(content) as Record<string, unknown>;
+		expect(parsed.hooks).toBeUndefined();
+		expect(parsed.env).toEqual({ KEY: "val" });
+	});
+
+	test("handles missing settings.local.json gracefully", async () => {
+		const output = await captureStdout(() => hooksCommand(["uninstall"]));
+		expect(output).toContain("nothing to uninstall");
+	});
+
+	test("handles settings.local.json with no hooks key", async () => {
+		const claudeDir = join(tempDir, ".claude");
+		await mkdir(claudeDir, { recursive: true });
+		await writeFile(
+			join(claudeDir, "settings.local.json"),
+			`${JSON.stringify({ env: { KEY: "val" } }, null, "\t")}\n`,
+		);
+
+		const output = await captureStdout(() => hooksCommand(["uninstall"]));
+		expect(output).toContain("No hooks found");
+	});
+});
+
+describe("hooks status", () => {
+	test("reports source missing when .legio/hooks.json does not exist", async () => {
+		const output = await captureStdout(() => hooksCommand(["status"]));
+		expect(output).toContain("missing");
+	});
+
+	test("reports installed:false when no hooks in .claude/", async () => {
+		await writeFile(
+			join(tempDir, ".legio", "hooks.json"),
+			`${JSON.stringify(SAMPLE_HOOKS, null, "\t")}\n`,
+		);
+
+		const output = await captureStdout(() => hooksCommand(["status"]));
+		expect(output).toContain("present");
+		expect(output).toContain("no");
+		expect(output).toContain("legio hooks install");
+	});
+
+	test("reports installed:true when hooks present in .claude/", async () => {
+		await writeFile(
+			join(tempDir, ".legio", "hooks.json"),
+			`${JSON.stringify(SAMPLE_HOOKS, null, "\t")}\n`,
+		);
+
+		const claudeDir = join(tempDir, ".claude");
+		await mkdir(claudeDir, { recursive: true });
+		await writeFile(
+			join(claudeDir, "settings.local.json"),
+			`${JSON.stringify({ hooks: {} }, null, "\t")}\n`,
+		);
+
+		const output = await captureStdout(() => hooksCommand(["status"]));
+		expect(output).toContain("yes");
+	});
+
+	test("--json outputs correct fields", async () => {
+		await writeFile(
+			join(tempDir, ".legio", "hooks.json"),
+			`${JSON.stringify(SAMPLE_HOOKS, null, "\t")}\n`,
+		);
+
+		const output = await captureStdout(() => hooksCommand(["status", "--json"]));
+		const parsed = JSON.parse(output) as Record<string, unknown>;
+		expect(parsed.sourceExists).toBe(true);
+		expect(parsed.installed).toBe(false);
+	});
+});

package/src/commands/hooks.ts

@@ -0,0 +1,210 @@
+/**
+ * CLI command: legio hooks install|uninstall|status
+ *
+ * Manages orchestrator hooks in .claude/settings.local.json.
+ * Hooks are sourced from .legio/hooks.json (generated by legio init).
+ *
+ * This keeps the canonical hook configuration in .legio/ while placing
+ * a minimal copy in .claude/ only when the user explicitly opts in.
+ * Running `legio init` alone does NOT modify .claude/ — the user must
+ * run `legio hooks install` as a separate step.
+ */
+
+import { access, mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { loadConfig } from "../config.ts";
+import { ValidationError } from "../errors.ts";
+
+const HOOKS_HELP = `legio hooks — Manage orchestrator hooks
+
+Usage: legio hooks <subcommand>
+
+Subcommands:
+  install                  Install orchestrator hooks to .claude/settings.local.json
+  uninstall                Remove orchestrator hooks from .claude/settings.local.json
+  status                   Check if hooks are installed
+
+Options:
+  --force                  Overwrite existing hooks in .claude/settings.local.json
+  --json                   Output as JSON
+  --help, -h               Show this help
+
+Hooks source: .legio/hooks.json (generated by legio init)
+Hooks target: .claude/settings.local.json (read by Claude Code)`;
+
+/**
+ * Check if a file exists using access().
+ */
+async function fileExists(path: string): Promise<boolean> {
+	try {
+		await access(path);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Install orchestrator hooks from .legio/hooks.json to .claude/settings.local.json.
+ *
+ * Reads the canonical hook config from .legio/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(args: string[]): Promise<void> {
+	const force = args.includes("--force");
+	const cwd = process.cwd();
+	const config = await loadConfig(cwd);
+	const projectRoot = config.project.root;
+
+	// Read source hooks from .legio/hooks.json
+	const sourcePath = join(projectRoot, ".legio", "hooks.json");
+	if (!(await fileExists(sourcePath))) {
+		throw new ValidationError("No hooks.json found in .legio/. Run 'legio init' first.", {
+			field: "source",
+		});
+	}
+
+	const sourceContent = await readFile(sourcePath, "utf-8");
+	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");
+
+	let targetConfig: Record<string, unknown> = {};
+	if (await fileExists(targetPath)) {
+		const existingContent = await readFile(targetPath, "utf-8");
+		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
+	targetConfig.hooks = sourceHooks.hooks;
+
+	// Write
+	await mkdir(targetDir, { recursive: true });
+	await writeFile(targetPath, `${JSON.stringify(targetConfig, null, "\t")}\n`);
+
+	process.stdout.write("\u2713 Installed orchestrator hooks to .claude/settings.local.json\n");
+	process.stdout.write("  Source: .legio/hooks.json\n");
+}
+
+/**
+ * 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(_args: string[]): Promise<void> {
+	const cwd = process.cwd();
+	const config = await loadConfig(cwd);
+	const projectRoot = config.project.root;
+
+	const targetPath = join(projectRoot, ".claude", "settings.local.json");
+
+	if (!(await fileExists(targetPath))) {
+		process.stdout.write("No .claude/settings.local.json found \u2014 nothing to uninstall.\n");
+		return;
+	}
+
+	const content = await readFile(targetPath, "utf-8");
+	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);
+		process.stdout.write("\u2713 Removed .claude/settings.local.json (was hooks-only)\n");
+	} else {
+		await writeFile(targetPath, `${JSON.stringify(rest, null, "\t")}\n`);
+		process.stdout.write(
+			"\u2713 Removed hooks from .claude/settings.local.json (preserved other settings)\n",
+		);
+	}
+}
+
+/**
+ * Show hooks installation status.
+ */
+async function statusHooks(args: string[]): Promise<void> {
+	const json = args.includes("--json");
+	const cwd = process.cwd();
+	const config = await loadConfig(cwd);
+	const projectRoot = config.project.root;
+
+	const sourcePath = join(projectRoot, ".legio", "hooks.json");
+	const targetPath = join(projectRoot, ".claude", "settings.local.json");
+
+	const sourceExists = await fileExists(sourcePath);
+	const targetExists = await fileExists(targetPath);
+
+	let installed = false;
+	if (targetExists) {
+		const content = await readFile(targetPath, "utf-8");
+		const parsed = JSON.parse(content) as Record<string, unknown>;
+		installed = !!parsed.hooks;
+	}
+
+	if (json) {
+		process.stdout.write(`${JSON.stringify({ sourceExists, installed })}\n`);
+	} else {
+		process.stdout.write(
+			`Hooks source (.legio/hooks.json): ${sourceExists ? "present" : "missing"}\n`,
+		);
+		process.stdout.write(
+			`Hooks installed (.claude/settings.local.json): ${installed ? "yes" : "no"}\n`,
+		);
+		if (!installed && sourceExists) {
+			process.stdout.write(`\nRun 'legio hooks install' to install.\n`);
+		}
+	}
+}
+
+/**
+ * Entry point for `legio hooks <subcommand>`.
+ */
+export async function hooksCommand(args: string[]): Promise<void> {
+	if (args.includes("--help") || args.includes("-h") || args.length === 0) {
+		process.stdout.write(`${HOOKS_HELP}\n`);
+		return;
+	}
+
+	const subcommand = args[0];
+	const subArgs = args.slice(1);
+
+	switch (subcommand) {
+		case "install":
+			await installHooks(subArgs);
+			break;
+		case "uninstall":
+			await uninstallHooks(subArgs);
+			break;
+		case "status":
+			await statusHooks(subArgs);
+			break;
+		default:
+			throw new ValidationError(
+				`Unknown hooks subcommand: ${subcommand}. Run 'legio hooks --help' for usage.`,
+				{ field: "subcommand", value: subcommand },
+			);
+	}
+}