magus-cli 0.0.0-placeholder → 7.0.0

package/src/services/gitignore-service.ts

@@ -0,0 +1,167 @@
+/**
+ * TUI-facing wrapper around the gitignore core services. Loads everything
+ * the Gitignore screen needs in one call, and exposes a small set of
+ * action helpers (apply safe fixes, apply one destructive fix, apply a
+ * built-in template).
+ */
+
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { BUILTIN_TEMPLATES } from "../data/gitignore-templates.js";
+import type {
+	GitignoreManifest,
+	ResolvedManifest,
+	Violation,
+} from "../types/gitignore.js";
+import { detectViolations } from "./gitignore-detector.js";
+import {
+	type DestructiveFixResult,
+	type SafeFixResult,
+	applyDestructiveFix as coreApplyDestructiveFix,
+	applySafeFixes as coreApplySafeFixes,
+} from "./gitignore-fixer.js";
+import { resolveGitignore } from "./gitignore-resolver.js";
+
+export interface GitignoreState {
+	resolved: ResolvedManifest;
+	violations: Violation[];
+	/** Logger lines from resolution (malformed JSON, missing template, etc). */
+	warnings: string[];
+}
+
+export async function loadGitignoreState(cwd: string): Promise<GitignoreState> {
+	const warnings: string[] = [];
+	const resolved = await resolveGitignore(cwd, {
+		logger: (m) => warnings.push(m),
+	});
+	const violations = await detectViolations(cwd, resolved);
+	return { resolved, violations, warnings };
+}
+
+export async function applyAllSafeFixes(
+	cwd: string,
+	violations: Violation[],
+): Promise<SafeFixResult> {
+	return coreApplySafeFixes(cwd, violations);
+}
+
+export async function applyDestructiveFix(
+	cwd: string,
+	violation: Violation,
+	rulePattern?: string,
+): Promise<DestructiveFixResult> {
+	return coreApplyDestructiveFix(cwd, violation, rulePattern);
+}
+
+export async function ensureProjectManifestForEdit(
+	cwd: string,
+	resolved: ResolvedManifest,
+): Promise<string> {
+	const projectManifestPath = join(cwd, ".claude", "gitignore.json");
+	if (existsSync(projectManifestPath)) {
+		const existing = await readFile(projectManifestPath, "utf8");
+		if (existing.trim().length > 0) return projectManifestPath;
+	}
+
+	const manifest: GitignoreManifest = { ignore: [], track: [] };
+	for (const rule of resolved.rules) {
+		if (rule.action === "ignore") manifest.ignore.push(rule.pattern);
+		else manifest.track.push(rule.pattern);
+	}
+
+	await mkdir(dirname(projectManifestPath), { recursive: true });
+	await writeFile(
+		projectManifestPath,
+		`${JSON.stringify(manifest, null, 2)}\n`,
+	);
+	return projectManifestPath;
+}
+
+export interface ApplyTemplateResult {
+	appliedTo: string;
+	added: { ignore: string[]; track: string[] };
+	conflicts: string[];
+}
+
+/**
+ * Merge a built-in template into the project manifest at .claude/gitignore.json.
+ * Conflicts (a pattern that already exists with the opposite action) are
+ * skipped and reported back to the caller.
+ */
+export async function applyTemplate(
+	cwd: string,
+	templateName: string,
+): Promise<ApplyTemplateResult> {
+	const tpl = BUILTIN_TEMPLATES[templateName];
+	if (!tpl) throw new Error(`Unknown template: ${templateName}`);
+
+	const projectManifestPath = join(cwd, ".claude", "gitignore.json");
+	const existing = await readManifestOrEmpty(projectManifestPath);
+
+	const existingIgnore = new Set(existing.ignore);
+	const existingTrack = new Set(existing.track);
+
+	const conflicts: string[] = [];
+	const newIgnore: string[] = [];
+	const newTrack: string[] = [];
+
+	for (const p of tpl.ignore) {
+		if (existingTrack.has(p)) {
+			conflicts.push(p);
+			continue;
+		}
+		if (!existingIgnore.has(p)) {
+			newIgnore.push(p);
+			existingIgnore.add(p);
+		}
+	}
+	for (const p of tpl.track) {
+		if (existingIgnore.has(p)) {
+			conflicts.push(p);
+			continue;
+		}
+		if (!existingTrack.has(p)) {
+			newTrack.push(p);
+			existingTrack.add(p);
+		}
+	}
+
+	const merged: GitignoreManifest = {
+		ignore: [...existing.ignore, ...newIgnore],
+		track: [...existing.track, ...newTrack],
+		extends: existing.extends,
+	};
+
+	await mkdir(dirname(projectManifestPath), { recursive: true });
+	await writeFile(projectManifestPath, `${JSON.stringify(merged, null, 2)}\n`);
+
+	return {
+		appliedTo: projectManifestPath,
+		added: { ignore: newIgnore, track: newTrack },
+		conflicts,
+	};
+}
+
+async function readManifestOrEmpty(path: string): Promise<GitignoreManifest> {
+	if (!existsSync(path)) return { ignore: [], track: [] };
+	try {
+		const raw = await readFile(path, "utf8");
+		const parsed = JSON.parse(raw);
+		if (!isManifest(parsed)) return { ignore: [], track: [] };
+		return parsed;
+	} catch {
+		return { ignore: [], track: [] };
+	}
+}
+
+function isManifest(x: unknown): x is GitignoreManifest {
+	if (!x || typeof x !== "object") return false;
+	const m = x as Record<string, unknown>;
+	return (
+		Array.isArray(m.ignore) &&
+		m.ignore.every((p) => typeof p === "string") &&
+		Array.isArray(m.track) &&
+		m.track.every((p) => typeof p === "string")
+	);
+}

package/src/services/hook-registration.ts

@@ -0,0 +1,218 @@
+/**
+ * Register `magus hook agent-model` as a `PreToolUse` hook on the Agent tool.
+ *
+ * The hook is what makes per-subagent routing exist at all: Claude Code has no
+ * per-agent model knob, and a PreToolUse hook rewriting the Agent tool's input
+ * is the only dynamic seam (measured — see `models-core.ts`). A config with no
+ * hook registered routes NOTHING, which is why `computeModelsStatus` reports
+ * `unhooked` ahead of any drift.
+ *
+ * Three rules, each earned:
+ *
+ *  1. **Identity is the command string.** Registration is idempotent because it
+ *     looks for the command, not for a block shape. An existing `Agent` matcher
+ *     block gets the command APPENDED rather than a second block created, so a
+ *     user's own Agent hooks keep running alongside this one.
+ *  2. **The command is BARE, never an absolute path.** `magus upgrade`
+ *     replaces the binary, and on npm the path carries a version directory — an
+ *     absolute path recorded today is a dead path after the next upgrade, and
+ *     the failure is invisible (a hook that cannot start is a hook that
+ *     silently does not route).
+ *  3. **User scope, through `updateSettingsFile`.** NOT
+ *     `readGlobalSettings`/`writeGlobalSettings`: those swallow a parse error
+ *     and return `{}`, so a settings file a human is mid-edit in would be
+ *     overwritten with one hook and nothing else. `updateSettingsFile` refuses
+ *     a file it cannot parse.
+ */
+
+import path from "node:path";
+import { claudeConfigDirOrNull } from "../utils/config-dir.js";
+import { readSettingsFile, updateSettingsFile } from "./settings-file.js";
+
+/** The command Claude Code runs. Bare — see rule 2 above. */
+export const AGENT_MODEL_HOOK_COMMAND = "magus hook agent-model";
+
+/** The tool whose input the hook rewrites. */
+const MATCHER = "Agent";
+
+/**
+ * Seconds. Generous for a process that reads one small JSON file and exits, and
+ * deliberately finite: Claude Code waits for this on every Agent call.
+ */
+const TIMEOUT_SECONDS = 5;
+
+interface HookCommand {
+	type: "command";
+	command: string;
+	timeout?: number;
+}
+
+const isRec = (v: unknown): v is Record<string, unknown> =>
+	typeof v === "object" && v !== null && !Array.isArray(v);
+
+/** The `hooks.PreToolUse` array, or [] for any shape that is not one. */
+function preToolUseBlocks(
+	settings: Record<string, unknown>,
+): Record<string, unknown>[] {
+	const hooks = settings.hooks;
+	if (!isRec(hooks)) return [];
+	const blocks = hooks.PreToolUse;
+	if (!Array.isArray(blocks)) return [];
+	return blocks.filter(isRec);
+}
+
+/** The command entries inside one matcher block. */
+function commandsIn(block: Record<string, unknown>): Record<string, unknown>[] {
+	return Array.isArray(block.hooks) ? block.hooks.filter(isRec) : [];
+}
+
+function isOurCommand(entry: Record<string, unknown>): boolean {
+	return (
+		typeof entry.command === "string" &&
+		entry.command.trim() === AGENT_MODEL_HOOK_COMMAND
+	);
+}
+
+/** Is the agent-model hook already registered in this settings object? */
+export function isHookRegistered(settings: Record<string, unknown>): boolean {
+	return preToolUseBlocks(settings).some((block) =>
+		commandsIn(block).some(isOurCommand),
+	);
+}
+
+function newCommandEntry(): HookCommand {
+	return {
+		type: "command",
+		command: AGENT_MODEL_HOOK_COMMAND,
+		timeout: TIMEOUT_SECONDS,
+	};
+}
+
+/**
+ * Add the hook if it is missing. Returns a NEW settings object — the input is
+ * never mutated, so a caller can diff before deciding to write.
+ */
+export function ensureHookRegistered(settings: Record<string, unknown>): {
+	settings: Record<string, unknown>;
+	changed: boolean;
+} {
+	if (isHookRegistered(settings)) return { settings, changed: false };
+
+	const next = structuredClone(settings);
+	const hooks = isRec(next.hooks) ? next.hooks : {};
+	const blocks = Array.isArray(hooks.PreToolUse) ? [...hooks.PreToolUse] : [];
+
+	// Append into an existing Agent block rather than adding a second one: two
+	// blocks with the same matcher both fire, which works, but it makes the
+	// user's settings file progressively less readable and is indistinguishable
+	// from a bug when they open it.
+	const existing = blocks.findIndex(
+		(b) => isRec(b) && b.matcher === MATCHER && Array.isArray(b.hooks),
+	);
+	if (existing >= 0) {
+		const block = blocks[existing] as Record<string, unknown>;
+		blocks[existing] = {
+			...block,
+			hooks: [...(block.hooks as unknown[]), newCommandEntry()],
+		};
+	} else {
+		blocks.push({ matcher: MATCHER, hooks: [newCommandEntry()] });
+	}
+
+	next.hooks = { ...hooks, PreToolUse: blocks };
+	return { settings: next, changed: true };
+}
+
+/**
+ * Remove every registration of the hook. An Agent block left with no commands
+ * is dropped, so uninstalling leaves no trace; other blocks and other commands
+ * inside a shared Agent block are untouched.
+ */
+export function removeHookRegistration(settings: Record<string, unknown>): {
+	settings: Record<string, unknown>;
+	changed: boolean;
+} {
+	if (!isHookRegistered(settings)) return { settings, changed: false };
+
+	const next = structuredClone(settings);
+	const hooks = next.hooks as Record<string, unknown>;
+	const blocks: unknown[] = [];
+	for (const block of hooks.PreToolUse as unknown[]) {
+		if (!isRec(block) || !Array.isArray(block.hooks)) {
+			blocks.push(block);
+			continue;
+		}
+		const kept = block.hooks.filter((e) => !(isRec(e) && isOurCommand(e)));
+		if (kept.length === 0 && block.matcher === MATCHER) continue;
+		blocks.push({ ...block, hooks: kept });
+	}
+
+	if (blocks.length > 0) {
+		hooks.PreToolUse = blocks;
+	} else {
+		// biome-ignore lint/performance/noDelete: an empty PreToolUse array is noise in a file people read
+		delete hooks.PreToolUse;
+	}
+	if (Object.keys(hooks).length === 0) {
+		// biome-ignore lint/performance/noDelete: same reason — leave no empty husk
+		delete next.hooks;
+	}
+	return { settings: next, changed: true };
+}
+
+/**
+ * The user-scope settings file this writes to.
+ *
+ * `claudeConfigDirOrNull` honours `CLAUDE_CONFIG_DIR` and returns null under
+ * `bun test` when no test has chosen a directory — which is a refusal, not a
+ * fallback: writing a hook into the operator's real `~/.claude/settings.json`
+ * from a test run is exactly the damage that guard exists to prevent.
+ */
+function userSettingsPath(configDir?: string): string {
+	const dir = configDir ?? claudeConfigDirOrNull();
+	if (!dir) {
+		throw new Error(
+			"No Claude config directory resolved. Set CLAUDE_CONFIG_DIR (a test must isolate it) before registering the agent-model hook.",
+		);
+	}
+	return path.join(dir, "settings.json");
+}
+
+/**
+ * Register the hook at user scope, once.
+ *
+ * User scope on purpose: routing is configured per project, but the hook that
+ * applies it has to be running in whatever session opens that project, and a
+ * project-scope hook would only exist for projects magus had already
+ * touched. The hook itself is a no-op for a project with no `models.json`, so
+ * one global registration costs nothing everywhere else.
+ */
+export async function registerAgentModelHook(
+	opts: { configDir?: string } = {},
+): Promise<"registered" | "already"> {
+	const settingsPath = userSettingsPath(opts.configDir);
+	// Read first so an unchanged file is not rewritten (and its mtime not
+	// touched) on every `models use`.
+	if (isHookRegistered(await readSettingsFile(settingsPath))) return "already";
+
+	await updateSettingsFile(settingsPath, (settings) => {
+		return ensureHookRegistered(settings).settings;
+	});
+	return "registered";
+}
+
+/** Is the hook registered in the user-scope settings file? */
+export async function isAgentModelHookRegistered(
+	opts: { configDir?: string } = {},
+): Promise<boolean> {
+	try {
+		return isHookRegistered(
+			await readSettingsFile(userSettingsPath(opts.configDir)),
+		);
+	} catch {
+		// No config dir, or a settings file we cannot parse. Either way we cannot
+		// claim it is registered — and the caller (doctor / status) reports that
+		// as "not routed", which is the honest answer.
+		return false;
+	}
+}

package/src/services/install-plan.ts

@@ -0,0 +1,107 @@
+/**
+ * Pure planning helpers for `magus install`.
+ *
+ * The impure "what does this machine already have" probing lives in the command
+ * (cli/install.ts); everything here is a pure function of a ResolvedClosure and
+ * some captured machine state, so it can be unit-tested and reused by
+ * `install --check` (the CI drift gate).
+ */
+
+import semver from "semver";
+import type {
+	InstalledPluginsRegistry,
+	ResolvedClosure,
+} from "../types/index.js";
+
+export interface VersionDrift {
+	pluginId: string;
+	/** The version the manifest pins. */
+	pinned: string;
+	/** The highest installed version, or null if not installed. */
+	installed: string | null;
+}
+
+/** Highest valid semver in a list, or the raw first value if none parse. */
+function maxVersion(versions: string[]): string | null {
+	const valid = versions.filter((v) => semver.valid(v));
+	const highest = valid.sort(semver.rcompare)[0];
+	return highest ?? versions[0] ?? null;
+}
+
+/**
+ * Compare the closure's pinned plugin versions against the installed registry.
+ * Only plugins with an explicit pin (not "latest") are checked. Returns the set
+ * of plugins whose installed version doesn't match the pin — the signal
+ * `install --check` fails on.
+ */
+export function computeVersionDrift(
+	closure: ResolvedClosure,
+	registry: InstalledPluginsRegistry,
+): VersionDrift[] {
+	const drifts: VersionDrift[] = [];
+	for (const [pluginId, pinned] of Object.entries(closure.plugins)) {
+		if (pinned === "latest") continue;
+		const entries = registry.plugins?.[pluginId] ?? [];
+		const installed = entries.length
+			? maxVersion(entries.map((e) => e.version))
+			: null;
+		if (installed !== pinned) {
+			drifts.push({ pluginId, pinned, installed });
+		}
+	}
+	return drifts;
+}
+
+export interface EnvStatus {
+	required: { name: string; present: boolean }[];
+	optional: { name: string; present: boolean }[];
+	/** Required vars that are unset — must be collected before the profile works. */
+	missingRequired: string[];
+}
+
+/** Which of the closure's declared env vars are present in `env` (process.env). */
+export function computeEnvStatus(
+	closure: ResolvedClosure,
+	env: Record<string, string | undefined> = process.env,
+): EnvStatus {
+	const check = (name: string) => ({
+		name,
+		present: typeof env[name] === "string" && env[name] !== "",
+	});
+	const required = closure.env.required.map(check);
+	const optional = closure.env.optional.map(check);
+	return {
+		required,
+		optional,
+		missingRequired: required.filter((e) => !e.present).map((e) => e.name),
+	};
+}
+
+/**
+ * A one-line-per-item human summary of what a closure contains, for the
+ * pre-install plan display. Machine-state annotations (already installed, etc.)
+ * are layered on by the caller.
+ */
+export function summarizeClosure(closure: ResolvedClosure): string[] {
+	const lines: string[] = [];
+	const mps = Object.keys(closure.marketplaces);
+	if (mps.length) lines.push(`marketplaces  ${mps.join(", ")}`);
+	const plugins = Object.entries(closure.plugins).map(([id, v]) =>
+		v === "latest" ? id : `${id}@${v}`,
+	);
+	if (plugins.length) lines.push(`plugins       ${plugins.join(", ")}`);
+	const mcps = Object.keys(closure.mcpServers);
+	if (mcps.length) lines.push(`mcp servers   ${mcps.join(", ")}`);
+	if (closure.bins.length) {
+		lines.push(
+			`cli tools     ${closure.bins.map((b) => (b.version ? `${b.name}@${b.version}` : b.name)).join(", ")}`,
+		);
+	}
+	if (closure.skills.length) {
+		lines.push(`skills        ${closure.skills.map((s) => s.name).join(", ")}`);
+	}
+	if (closure.env.required.length) {
+		lines.push(`env           ${closure.env.required.join(", ")}`);
+	}
+	return lines;
+}