magus-cli 0.0.0-placeholder → 7.1.0

package/src/cli/install.ts

@@ -0,0 +1,382 @@
+/**
+ * `magus install [profile] [--check] [--yes]`
+ *
+ * Materialize a committed team profile from .claude/profiles.json onto this
+ * machine: register marketplaces, install pinned plugins, install the binaries
+ * plugins declare (requires.bin) plus the profile's cliTools, install skills,
+ * collect required env, then activate the profile via symlinks.
+ *
+ * With no argument it installs the union of every profile's deps and
+ * materializes them all (so `profile switch` needs no reinstall), then
+ * activates one. `--check` is a read-only drift gate for CI. `--yes` skips
+ * the confirmation prompt.
+ */
+
+import path from "node:path";
+import { installPlugin, isClaudeAvailable } from "../services/claude-cli.js";
+import {
+	readInstalledPluginsRegistry,
+	readLocalSettings,
+	writeLocalSettings,
+} from "../services/claude-settings.js";
+import { ensureGitignoreEntries } from "../services/conventions-manager.js";
+import {
+	computeEnvStatus,
+	computeVersionDrift,
+	summarizeClosure,
+} from "../services/install-plan.js";
+import { validateManifest } from "../services/manifest.js";
+import { registerClosureMarketplaces } from "../services/marketplace-sync.js";
+import { materializeProfile } from "../services/profile-materializer.js";
+import { detectProfileDrift } from "../services/profile-sync.js";
+import { resolveAllProfiles, resolveProfile } from "../services/resolver.js";
+import { installSkill } from "../services/skills-manager.js";
+import {
+	PROFILE_GITIGNORE_ENTRIES,
+	activateProfile,
+	activeProfile,
+} from "../services/symlink-manager.js";
+import {
+	TOOLCHAIN_BOOTSTRAP,
+	binInstallCommand,
+	detectToolchains,
+} from "../services/toolchain.js";
+import type {
+	ProfileSkillRef,
+	ResolvedBin,
+	ResolvedClosure,
+	SkillInfo,
+} from "../types/index.js";
+import { formatCommand, resolveExecutable } from "../utils/command-utils.js";
+import { runCommand, runShellScript } from "../utils/run.js";
+import { ensureManifest } from "./bootstrap.js";
+import { confirm, promptValue } from "./prompt.js";
+
+interface InstallFlags {
+	check: boolean;
+	yes: boolean;
+	force: boolean;
+	profile?: string;
+}
+
+function parseArgs(args: string[]): InstallFlags {
+	return {
+		check: args.includes("--check"),
+		yes: args.includes("--yes") || args.includes("-y"),
+		force: args.includes("--force"),
+		profile: args.find((a) => !a.startsWith("-")),
+	};
+}
+
+// ── --check: read-only drift gate ───────────────────────────────────────────
+
+async function runCheck(
+	closure: ResolvedClosure,
+	strict: boolean,
+): Promise<number> {
+	const registry = await readInstalledPluginsRegistry();
+	const drift = computeVersionDrift(closure, registry);
+	if (drift.length === 0) {
+		console.log("✓ No plugin version drift.");
+		return 0;
+	}
+	console.log("Plugin version drift:");
+	for (const d of drift) {
+		console.log(
+			`  ✗ ${d.pluginId}  pinned ${d.pinned}, installed ${d.installed ?? "none"}`,
+		);
+	}
+	if (strict) {
+		console.error("\nstrictVersions is on — failing.");
+		return 1;
+	}
+	console.log("\n(strictVersions is off — reporting only.)");
+	return 0;
+}
+
+// ── install steps ───────────────────────────────────────────────────────────
+
+async function ensureToolchains(
+	closure: ResolvedClosure,
+	yes: boolean,
+): Promise<void> {
+	// Only the binaries actually missing can need a toolchain. Checking all of
+	// them warns "pip isn't installed" on a machine whose pip-provided binaries
+	// are already on PATH — an alarming message about work that will not happen.
+	const missing: ResolvedBin[] = [];
+	for (const bin of closure.bins) {
+		if (!(await resolveExecutable(bin.name))) missing.push(bin);
+	}
+	if (missing.length === 0) return;
+
+	const toolchains = await detectToolchains(missing);
+	for (const tc of toolchains) {
+		if (tc.present) continue;
+		const bootstrap = TOOLCHAIN_BOOTSTRAP[tc.name];
+		if (!bootstrap) {
+			console.warn(
+				`⚠ ${tc.name} is required by ${tc.requiredBy.join(", ")} but isn't installed and can't be auto-installed. Install it and re-run.`,
+			);
+			continue;
+		}
+		const ok =
+			yes ||
+			(await confirm(
+				`${tc.name} is missing (needed by ${tc.requiredBy.join(", ")}). Install it?`,
+			));
+		if (ok) {
+			console.log(`Installing ${tc.name}…`);
+			// A bootstrap line IS shell text — bun's contains a pipe, Homebrew's a
+			// command substitution — and it is a constant in this repo, not
+			// profile data. This is the only legitimate caller.
+			if (!(await runShellScript(bootstrap))) {
+				console.warn(`⚠ Failed to install ${tc.name}. Continuing.`);
+			}
+		}
+	}
+}
+
+/**
+ * Install the closure's plugins at PROJECT scope.
+ *
+ * A profile is a property of one repo, so its plugins must be too. At user
+ * scope, adopting profiles in a single repo would enable that repo's plugins in
+ * every other project on the machine — and since Claude Code resolves
+ * enabledPlugins per id with fall-through, those would stay on everywhere.
+ * Project scope keeps the blast radius to this repo. The plugin *cache* is
+ * global either way, so `profile switch` stays offline.
+ *
+ * Whatever the CLI writes into .claude/settings.json here is transient:
+ * materialization rewrites that file from the manifest, and activation replaces
+ * it with a symlink. The manifest stays authoritative.
+ */
+async function installPlugins(closure: ResolvedClosure): Promise<void> {
+	for (const pluginId of Object.keys(closure.plugins)) {
+		try {
+			console.log(`+ plugin ${pluginId}`);
+			await installPlugin(pluginId, "project");
+		} catch (e) {
+			console.warn(`⚠ plugin ${pluginId}: ${(e as Error).message}`);
+		}
+	}
+}
+
+async function installBins(bins: ResolvedBin[]): Promise<void> {
+	for (const bin of bins) {
+		if (await resolveExecutable(bin.name)) {
+			continue; // already installed and runnable (not a dangling link)
+		}
+		const cmd = binInstallCommand(bin);
+		// Printed rendered, executed as argv. The package name in `cmd.args` came
+		// from a profile or a plugin manifest, so it must never reach a shell.
+		console.log(`+ ${bin.name}  (${formatCommand(cmd)})`);
+		if (!(await runCommand(cmd))) {
+			console.warn(`⚠ failed to install ${bin.name} via ${bin.via}`);
+		}
+	}
+}
+
+/** Map a manifest skill ref to the SkillInfo shape installSkill expects. */
+function toSkillInfo(ref: ProfileSkillRef): SkillInfo {
+	return {
+		id: `${ref.repo}/${ref.path}`,
+		name: ref.name,
+		source: {
+			label: ref.repo,
+			repo: ref.repo,
+			skillsPath: path.dirname(ref.path),
+		},
+		repoPath: ref.path,
+		gitBlobSha: "",
+		frontmatter: null,
+		installed: false,
+		installedScope: null,
+		hasUpdate: false,
+	};
+}
+
+async function installSkills(
+	skills: ProfileSkillRef[],
+	projectPath: string,
+): Promise<void> {
+	for (const ref of skills) {
+		try {
+			console.log(`+ skill ${ref.name}`);
+			await installSkill(toSkillInfo(ref), "project", projectPath);
+		} catch (e) {
+			console.warn(`⚠ skill ${ref.name}: ${(e as Error).message}`);
+		}
+	}
+}
+
+async function collectEnv(
+	closure: ResolvedClosure,
+	projectPath: string,
+	yes: boolean,
+): Promise<void> {
+	const status = computeEnvStatus(closure);
+	if (status.missingRequired.length === 0) return;
+
+	console.log("\nMissing required environment variables:");
+	if (yes) {
+		for (const name of status.missingRequired)
+			console.log(`  ! ${name} (unset)`);
+		console.log(
+			"Run without --yes to enter values, or set them in .claude/settings.local.json.",
+		);
+		return;
+	}
+
+	const local = await readLocalSettings(projectPath);
+	local.env = local.env ?? {};
+	for (const name of status.missingRequired) {
+		const value = await promptValue(`  ${name} = `);
+		if (value) local.env[name] = value;
+	}
+	await writeLocalSettings(local, projectPath);
+	console.log("Saved to .claude/settings.local.json (personal, gitignored).");
+}
+
+// ── entry point ──────────────────────────────────────────────────────────────
+
+export async function runInstallCommand(
+	args: string[],
+	projectPath: string = process.cwd(),
+): Promise<number> {
+	const flags = parseArgs(args);
+
+	// A repo with no manifest is offered adoption rather than an error — see
+	// cli/bootstrap.ts for why there is no manifest-free install path.
+	// `--yes` is deliberately NOT forwarded: it means "do not ask me about the
+	// thing I invoked", and someone running `magus install --yes` in CI
+	// invoked an install, not the authoring of their team's committed manifest.
+	// Creating that file needs a human at the prompt, or `profile init`.
+	const manifest = await ensureManifest(projectPath, {
+		check: flags.check,
+	});
+	if (!manifest) return 1;
+
+	const errors = validateManifest(manifest);
+	if (errors.length > 0) {
+		console.error("Invalid .claude/profiles.json:");
+		for (const e of errors) console.error(`  ${e.path}: ${e.message}`);
+		return 1;
+	}
+
+	const profileIds = Object.keys(manifest.profiles);
+	if (flags.profile && !manifest.profiles[flags.profile]) {
+		console.error(
+			`Profile "${flags.profile}" not found. Available: ${profileIds.join(", ")}`,
+		);
+		return 1;
+	}
+
+	// Closure: a single profile, or the union of all.
+	const closure = flags.profile
+		? await resolveProfile(manifest, flags.profile)
+		: await resolveAllProfiles(manifest);
+
+	if (flags.check) {
+		return runCheck(closure, manifest.strictVersions === true);
+	}
+
+	// Drift guard: refuse to clobber unsynced local edits to the active profile
+	// (materialize would overwrite them) unless --force is given.
+	if (!flags.force) {
+		const active = await activeProfile(projectPath);
+		if (active && (flags.profile === undefined || flags.profile === active)) {
+			const drift = await detectProfileDrift(active, projectPath);
+			if (drift.length > 0) {
+				console.error(
+					`Active profile "${active}" has unsynced local edits that install would overwrite:`,
+				);
+				for (const c of drift) console.error(`  ${c.kind}: ${c.detail}`);
+				console.error(
+					"\nRun `magus profile sync` to promote them into .claude/profiles.json,\n" +
+						"or re-run with --force to discard them.",
+				);
+				return 1;
+			}
+		}
+	}
+
+	// Plan
+	console.log(`\nPlan for ${flags.profile ?? "all profiles"}:`);
+	for (const line of summarizeClosure(closure)) console.log(`  ${line}`);
+	if (closure.conflicts?.length) {
+		console.log(
+			"\n⚠ Version conflicts across profiles (resolved to the higher pin):",
+		);
+		for (const c of closure.conflicts) console.log(`  ${c}`);
+	}
+	console.log();
+
+	if (!flags.yes && !(await confirm("Apply?"))) {
+		console.log("Aborted.");
+		return 0;
+	}
+
+	if (!(await isClaudeAvailable())) {
+		console.error(
+			"claude CLI not found on PATH — cannot install plugins/marketplaces.",
+		);
+		return 1;
+	}
+
+	await ensureToolchains(closure, flags.yes);
+	await registerClosureMarketplaces(closure.marketplaces);
+	await installPlugins(closure);
+	await installBins(closure.bins);
+
+	// Materialize every profile (so `profile switch` needs no reinstall), then
+	// activate the target (or the sole/first profile).
+	//
+	// Every profile is materialized even when one was named: a profile arg scopes
+	// what gets *installed* and which becomes active, not which settings files
+	// exist. It also keeps the union below consistent across all of them — a
+	// profile left holding an older union would stop disabling plugins added
+	// since, silently making `switch` additive again.
+	const unionPluginIds = Object.keys(
+		(flags.profile ? await resolveAllProfiles(manifest) : closure).plugins,
+	);
+	for (const id of profileIds) {
+		const profileClosure = await resolveProfile(manifest, id);
+		await materializeProfile(id, profileClosure, projectPath, unionPluginIds);
+	}
+
+	// Keep the generated dir + active-profile symlinks out of git before
+	// activating (source of truth is .claude/profiles.json).
+	await ensureGitignoreEntries(
+		path.join(projectPath, ".gitignore"),
+		PROFILE_GITIGNORE_ENTRIES,
+		"# magus: generated profile build output + active-profile symlinks",
+	);
+
+	const activeId =
+		flags.profile ?? (await pickActiveProfile(profileIds, flags.yes));
+	if (activeId) {
+		await activateProfile(activeId, projectPath);
+		console.log(`\n✓ Active profile: ${activeId}`);
+		// Skills route through the now-active .claude/skills symlink.
+		const activeClosure = await resolveProfile(manifest, activeId);
+		await installSkills(activeClosure.skills, projectPath);
+		await collectEnv(activeClosure, projectPath, flags.yes);
+	}
+
+	console.log("\nDone.");
+	return 0;
+}
+
+async function pickActiveProfile(
+	profileIds: string[],
+	yes: boolean,
+): Promise<string | undefined> {
+	if (profileIds.length === 0) return undefined;
+	if (profileIds.length === 1) return profileIds[0];
+	if (yes) return profileIds[0];
+	console.log("\nWhich profile should be active?");
+	profileIds.forEach((id, i) => console.log(`  ${i + 1}) ${id}`));
+	const answer = await promptValue("Choose [1]: ");
+	const idx = answer ? Number.parseInt(answer, 10) - 1 : 0;
+	return profileIds[idx] ?? profileIds[0];
+}