magus-cli 0.0.0-placeholder → 7.1.0

package/src/cli/doctor.ts

@@ -0,0 +1,218 @@
+/**
+ * `magus doctor [--fix]`
+ *
+ * Diagnoses (and with --fix, repairs) project health:
+ *   1. Binary dependencies — every requires.bin / cliTools binary on PATH.
+ *      This is the check that would have caught a dead `tmux-mcp`.
+ *   2. Profile symlink integrity — the active profile's links resolve.
+ *   3. Convention compliance — .gitignore + CLAUDE.md blocks (ported engine).
+ *   4. Model routing — config validity, hook registration, and drift.
+ */
+
+import path from "node:path";
+import fs from "fs-extra";
+import { checkBinaries, missingBinaries } from "../services/doctor-bins.js";
+import { checkProject, fixDoctorIssues } from "../services/doctor.js";
+import {
+	isAgentModelHookRegistered,
+	registerAgentModelHook,
+} from "../services/hook-registration.js";
+import { readManifest } from "../services/manifest.js";
+import {
+	readModelsConfig,
+	readModelsStatus,
+} from "../services/models-manager.js";
+import { resolveAllProfiles } from "../services/resolver.js";
+import { activeProfile, profileDir } from "../services/symlink-manager.js";
+import { resolveExecutable } from "../utils/command-utils.js";
+
+export async function runDoctorCommand(args: string[]): Promise<number> {
+	const fix = args.includes("--fix");
+	const projectPath = process.cwd();
+	let problems = 0;
+
+	// 1. Binary dependencies.
+	const manifest = await readManifest(projectPath);
+	let pluginIds: string[] = [];
+	if (Object.keys(manifest.profiles).length > 0) {
+		const closure = await resolveAllProfiles(manifest);
+		pluginIds = Object.keys(closure.plugins);
+		if (closure.bins.length > 0) {
+			const results = await checkBinaries(closure.bins);
+			const missing = missingBinaries(results);
+			if (missing.length > 0) {
+				console.log("Binary dependencies:");
+				for (const m of missing) {
+					console.log(
+						`  ✗ ${m.name} — run: ${m.installCommand}  (needed by ${m.sources.join(", ")})`,
+					);
+					problems++;
+				}
+			} else {
+				console.log(
+					`✓ All ${closure.bins.length} binary dependencies present.`,
+				);
+			}
+		}
+	}
+
+	// 2. Profile symlink integrity.
+	const active = await activeProfile(projectPath);
+	if (active) {
+		const dangling = await danglingLinks(active, projectPath);
+		if (dangling.length > 0) {
+			console.log(`Profile "${active}" has broken symlinks:`);
+			for (const l of dangling) console.log(`  ✗ ${l}`);
+			console.log(`  Fix: magus install ${active}`);
+			problems += dangling.length;
+		} else {
+			console.log(`✓ Active profile "${active}" symlinks resolve.`);
+		}
+	}
+
+	// 3. Convention compliance — scoped to THIS project only (the ported engine
+	// can scan every registered project; that's noisy for a project command).
+	if (pluginIds.length > 0) {
+		try {
+			const project = await checkProject(projectPath, pluginIds);
+			const actionable = project.checks.filter((c) => c.status !== "pass");
+			if (actionable.length > 0) {
+				console.log("\nConventions:");
+				for (const check of actionable) {
+					console.log(
+						`  ${check.status === "fail" ? "✗" : "•"} ${check.message}`,
+					);
+				}
+				const fixable = actionable.filter((c) => c.fixable).length;
+				const failures = actionable.filter((c) => c.status === "fail").length;
+				if (fix && fixable > 0) {
+					const { fixed, failed } = await fixDoctorIssues({
+						projects: [project],
+						summary: {
+							totalProjects: 1,
+							totalChecks: project.checks.length,
+							passed: 0,
+							warnings: 0,
+							failures,
+							fixable,
+						},
+					});
+					console.log(`\nFixed ${fixed}, failed ${failed}.`);
+				} else if (fixable > 0) {
+					console.log(`\n${fixable} fixable — re-run with --fix.`);
+					problems += failures;
+				}
+			}
+		} catch {
+			// Convention doctor is best-effort; never fail the whole command on it.
+		}
+	}
+
+	// 4. Model routing.
+	problems += await checkModels(projectPath, fix);
+
+	if (problems === 0) console.log("\n✓ No problems found.");
+	return problems > 0 && !fix ? 1 : 0;
+}
+
+/**
+ * Model routing health. Silent when the project has no routing at all — an
+ * absent `models.json` is the normal state, not a finding.
+ *
+ * Ordered by what blocks what: an invalid config routes nothing and cannot be
+ * fixed from here (the values are a human's decision); an unregistered hook
+ * routes nothing no matter how good the config is; drift only matters once
+ * both of those are sound.
+ */
+async function checkModels(projectPath: string, fix: boolean): Promise<number> {
+	const { config, errors, path: file } = await readModelsConfig(projectPath);
+	if (config === null && errors.length === 0) return 0;
+
+	console.log("\nModel routing:");
+	let problems = 0;
+
+	if (errors.length > 0) {
+		console.log(`  ✗ ${file} is invalid — nothing is routed:`);
+		for (const e of errors) {
+			console.log(`      ${e.path || "(root)"}: ${e.message}`);
+		}
+		console.log(
+			"    Not auto-fixable: these are choices, not damage. Edit the file (or",
+		);
+		console.log("    re-run `magus models use <preset>`) and check again.");
+		// An invalid config is worth exactly one problem, not one per message —
+		// the count drives the exit code, not the severity.
+		return 1;
+	}
+
+	// The hook is what applies the routing. Without it the config is inert.
+	if (await isAgentModelHookRegistered()) {
+		console.log("  ✓ agent-model hook registered at user scope.");
+	} else if (fix) {
+		await registerAgentModelHook();
+		console.log("  ✓ agent-model hook registered at user scope (fixed).");
+	} else {
+		console.log(
+			"  ✗ agent-model hook is not registered — the config is there, but nothing runs it.",
+		);
+		console.log("    Fix: magus doctor --fix");
+		problems++;
+	}
+
+	// The hook runs as a bare `magus`, deliberately (an absolute path dies on
+	// the next upgrade) — so PATH has to carry it. Warn only: PATH inside a
+	// Claude Code session is not necessarily PATH here.
+	if (!(await resolveExecutable("magus"))) {
+		console.log(
+			"  • `magus` is not on PATH in this shell. The hook invokes it by name,",
+		);
+		console.log(
+			"    so it must resolve in the shell Claude Code spawns hooks from.",
+		);
+	}
+
+	// No drift check. Settings differing from the config is what a CUSTOM config is, and
+	// `doctor` reports problems — a project running models no shipped preset names has none.
+	// So `doctor --fix` no longer reapplies anything: `invalid` returns early above (those
+	// are choices, not damage) and `unhooked` is repaired by registering the hook. Writing
+	// settings back from the config is `magus models use <preset>`, which is a decision
+	// the user makes, not a repair.
+	const status = await readModelsStatus(projectPath);
+	if (status.state === "on") {
+		console.log("  ✓ routing is applied.");
+	}
+
+	for (const warning of status.warnings) console.log(`  ⚠ ${warning}`);
+
+	return problems;
+}
+
+/** Which of the active profile's expected symlinks are missing or dangling. */
+async function danglingLinks(
+	name: string,
+	projectPath: string,
+): Promise<string[]> {
+	const dir = profileDir(name, projectPath);
+	const checks: Array<{ link: string; target: string }> = [
+		{
+			link: path.join(projectPath, ".claude", "settings.json"),
+			target: path.join(dir, "settings.json"),
+		},
+		{
+			link: path.join(projectPath, ".mcp.json"),
+			target: path.join(dir, "mcp.json"),
+		},
+	];
+	const broken: string[] = [];
+	for (const { link, target } of checks) {
+		try {
+			const stat = await fs.lstat(link);
+			if (stat.isSymbolicLink() && !(await fs.pathExists(target))) {
+				broken.push(path.relative(projectPath, link));
+			}
+		} catch {
+			// link absent — not "broken", the profile may not provide it.
+		}
+	}
+	return broken;
+}

package/src/cli/hook.ts

@@ -0,0 +1,129 @@
+/**
+ * `magus hook agent-model` — the PreToolUse hook Claude Code runs on every Agent call.
+ *
+ * This is the hottest path magus has: Claude Code spawns it once per subagent dispatch, in
+ * every session on the machine, and waits for it. Two consequences shape the whole file.
+ *
+ * IT MUST BE FAST. `main.tsx` routes here before it loads the project's `.env` and before it
+ * imports the router or the TUI, so nothing in this module may import `src/ui/` or anything
+ * that pulls in `@opentui`. `src/__tests__/hook-import-policy.test.ts` fails the build if that
+ * ever regresses. Measured: 0.02s on this path against 0.16s once the router is loaded.
+ *
+ * IT MUST FAIL OPEN. Every error path exits 0 with empty stdout, which Claude Code reads as
+ * "no opinion". A hook that throws, blocks, or exits non-zero takes the user's subagents with
+ * it, and the failure would surface as delegation mysteriously not working — in every project,
+ * not just the one with the bad config. Silence is always the safe answer, so it is the
+ * default and the fallback.
+ *
+ * It never writes a file, never exits 2, and never reads a `.env`.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, parse } from "node:path";
+import {
+	type ModelsConfig,
+	evaluateAgentHook,
+	validateModelsConfig,
+} from "../services/models-core.js";
+
+/** How far up the tree to look for a config before giving up. */
+const MAX_WALK_UP = 32;
+
+/**
+ * Find the nearest `.claude/models.json` at or above `startDir`.
+ *
+ * The walk matters: a session's cwd is frequently a subdirectory of the project, and this repo
+ * in particular runs most work inside git worktrees. Anchoring on the hook payload's `cwd`
+ * rather than `process.cwd()` is deliberate — Claude Code tells us where the session is, and
+ * that is not necessarily where this process was started.
+ */
+export function findModelsConfig(startDir: string): string | null {
+	let dir = startDir;
+	const root = parse(dir).root;
+	for (let i = 0; i < MAX_WALK_UP; i += 1) {
+		const candidate = join(dir, ".claude", "models.json");
+		if (existsSync(candidate)) return candidate;
+		if (dir === root) return null;
+		const parent = dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+	return null;
+}
+
+/**
+ * Read and validate a config. Returns null for every unusable state — missing, unreadable,
+ * unparseable, or invalid — because the hook's answer to all four is the same: do nothing.
+ *
+ * An invalid config is NOT an error here even though it is one everywhere else. `models use`
+ * refuses to write one, `magus install` refuses to apply one, and `doctor` reports one; by
+ * the time a session is running, the only useful behaviour left is to get out of the way.
+ */
+export function loadConfig(path: string): ModelsConfig | null {
+	let raw: unknown;
+	try {
+		raw = JSON.parse(readFileSync(path, "utf8"));
+	} catch {
+		return null;
+	}
+	if (validateModelsConfig(raw).length > 0) return null;
+	return raw as ModelsConfig;
+}
+
+async function readStdin(): Promise<string> {
+	// A hook always receives its payload on stdin. Guard the TTY case anyway so that a human
+	// typing the subcommand by hand gets an immediate no-op instead of a hang.
+	if (process.stdin.isTTY) return "";
+	const chunks: Uint8Array[] = [];
+	for await (const chunk of Bun.stdin.stream()) chunks.push(chunk);
+	return Buffer.concat(chunks).toString("utf8");
+}
+
+export async function runHookCommand(args: string[]): Promise<number> {
+	// `hook` with no recognised name is a no-op rather than a usage error: this process is
+	// wired into someone's session, and printing to stdout would be interpreted as a decision.
+	if (args[0] !== "agent-model") {
+		await readStdin();
+		return 0;
+	}
+
+	try {
+		const raw = await readStdin();
+		if (raw.trim().length === 0) return 0;
+
+		let payload: Record<string, unknown>;
+		try {
+			payload = JSON.parse(raw) as Record<string, unknown>;
+		} catch {
+			return 0;
+		}
+
+		// `cwd` is the session's directory, which is not this process's cwd.
+		const cwd =
+			typeof payload.cwd === "string" && payload.cwd.length > 0
+				? payload.cwd
+				: process.cwd();
+		const configPath = findModelsConfig(cwd);
+		const config = configPath === null ? null : loadConfig(configPath);
+
+		const decision = evaluateAgentHook(
+			{
+				tool_name:
+					typeof payload.tool_name === "string" ? payload.tool_name : undefined,
+				tool_input:
+					typeof payload.tool_input === "object" && payload.tool_input !== null
+						? (payload.tool_input as Record<string, unknown>)
+						: undefined,
+				cwd,
+			},
+			config,
+		);
+
+		if (decision.kind === "update")
+			process.stdout.write(JSON.stringify(decision.output));
+		return 0;
+	} catch {
+		// Belt and braces. Nothing above should throw, and if it ever does the session must
+		// not notice.
+		return 0;
+	}
+}