magus-cli 0.0.0-placeholder → 7.0.0

package/src/services/profiles.ts

@@ -0,0 +1,225 @@
+import os from "node:os";
+import path from "node:path";
+import fs from "fs-extra";
+import type { Profile, ProfileEntry, ProfilesFile } from "../types/index.js";
+
+const PROFILES_FILE = "profiles.json";
+
+// ─── Path helpers ──────────────────────────────────────────────────────────────
+
+export function getUserProfilesPath(): string {
+	return path.join(os.homedir(), ".claude", PROFILES_FILE);
+}
+
+export function getProjectProfilesPath(projectPath?: string): string {
+	const base = projectPath ?? process.cwd();
+	return path.join(base, ".claude", PROFILES_FILE);
+}
+
+// ─── Low-level read/write ──────────────────────────────────────────────────────
+
+export async function readProfiles(
+	scope: "user" | "project",
+	projectPath?: string,
+): Promise<ProfilesFile> {
+	const filePath =
+		scope === "user"
+			? getUserProfilesPath()
+			: getProjectProfilesPath(projectPath);
+	try {
+		if (await fs.pathExists(filePath)) {
+			const data = await fs.readJson(filePath);
+			if (data.version && data.profiles) return data as ProfilesFile;
+		}
+	} catch {
+		// fall through to default
+	}
+	return { version: 1, profiles: {} };
+}
+
+async function writeProfiles(
+	scope: "user" | "project",
+	data: ProfilesFile,
+	projectPath?: string,
+): Promise<void> {
+	const filePath =
+		scope === "user"
+			? getUserProfilesPath()
+			: getProjectProfilesPath(projectPath);
+	await fs.ensureDir(path.dirname(filePath));
+	await fs.writeJson(filePath, data, { spaces: 2 });
+}
+
+// ─── CRUD ──────────────────────────────────────────────────────────────────────
+
+/** Return all profiles from both scopes, merged into a flat list */
+export async function listProfiles(
+	projectPath?: string,
+): Promise<ProfileEntry[]> {
+	const [user, project] = await Promise.all([
+		readProfiles("user"),
+		readProfiles("project", projectPath),
+	]);
+	const entries: ProfileEntry[] = [];
+	for (const [id, p] of Object.entries(user.profiles)) {
+		entries.push({ id, scope: "user", ...p });
+	}
+	for (const [id, p] of Object.entries(project.profiles)) {
+		entries.push({ id, scope: "project", ...p });
+	}
+	// Sort: user profiles first, then project, each by updatedAt desc
+	entries.sort((a, b) => {
+		if (a.scope !== b.scope) return a.scope === "user" ? -1 : 1;
+		return b.updatedAt.localeCompare(a.updatedAt);
+	});
+	return entries;
+}
+
+/**
+ * Save (create or overwrite) a profile.
+ * Returns the generated profile ID.
+ */
+export async function saveProfile(
+	name: string,
+	plugins: Record<string, boolean>,
+	scope: "user" | "project",
+	projectPath?: string,
+): Promise<string> {
+	const data = await readProfiles(scope, projectPath);
+	const id = generateUniqueId(name, data.profiles);
+	const now = new Date().toISOString();
+	data.profiles[id] = {
+		name,
+		plugins,
+		createdAt: now,
+		updatedAt: now,
+	};
+	await writeProfiles(scope, data, projectPath);
+	return id;
+}
+
+/**
+ * Apply a profile: replaces enabledPlugins in the target settings scope.
+ * targetScope is where the settings will be written, independent of where
+ * the profile is stored.
+ */
+export async function applyProfile(
+	profileId: string,
+	profileScope: "user" | "project",
+	targetScope: "user" | "project" | "local",
+	projectPath?: string,
+): Promise<void> {
+	const data = await readProfiles(profileScope, projectPath);
+	const profile = data.profiles[profileId];
+	if (!profile) throw new Error(`Profile "${profileId}" not found`);
+
+	// Import settings functions dynamically to avoid circular deps
+	const {
+		readSettings,
+		writeSettings,
+		readGlobalSettings,
+		writeGlobalSettings,
+	} = await import("./claude-settings.js");
+
+	if (targetScope === "user") {
+		const settings = await readGlobalSettings();
+		settings.enabledPlugins = { ...profile.plugins };
+		await writeGlobalSettings(settings);
+	} else {
+		// project or local both write to project settings.json
+		const settings = await readSettings(projectPath);
+		settings.enabledPlugins = { ...profile.plugins };
+		await writeSettings(settings, projectPath);
+	}
+}
+
+/** Rename a profile in-place (preserves id, createdAt) */
+export async function renameProfile(
+	profileId: string,
+	newName: string,
+	scope: "user" | "project",
+	projectPath?: string,
+): Promise<void> {
+	const data = await readProfiles(scope, projectPath);
+	if (!data.profiles[profileId]) {
+		throw new Error(`Profile "${profileId}" not found in ${scope} scope`);
+	}
+	data.profiles[profileId].name = newName;
+	data.profiles[profileId].updatedAt = new Date().toISOString();
+	await writeProfiles(scope, data, projectPath);
+}
+
+export async function deleteProfile(
+	profileId: string,
+	scope: "user" | "project",
+	projectPath?: string,
+): Promise<void> {
+	const data = await readProfiles(scope, projectPath);
+	if (!data.profiles[profileId]) {
+		throw new Error(`Profile "${profileId}" not found in ${scope} scope`);
+	}
+	delete data.profiles[profileId];
+	await writeProfiles(scope, data, projectPath);
+}
+
+// ─── Import / Export ───────────────────────────────────────────────────────────
+
+/** Serialize a profile to a compact JSON string for clipboard sharing */
+export async function exportProfileToJson(
+	profileId: string,
+	scope: "user" | "project",
+	projectPath?: string,
+): Promise<string> {
+	const data = await readProfiles(scope, projectPath);
+	const profile = data.profiles[profileId];
+	if (!profile) throw new Error(`Profile "${profileId}" not found`);
+	const entry: ProfileEntry = { id: profileId, scope, ...profile };
+	return JSON.stringify(entry, null, 2);
+}
+
+/**
+ * Parse a clipboard JSON string and save into the specified scope.
+ * Returns the saved profile id.
+ */
+export async function importProfileFromJson(
+	json: string,
+	targetScope: "user" | "project",
+	projectPath?: string,
+): Promise<string> {
+	let entry: Partial<ProfileEntry>;
+	try {
+		entry = JSON.parse(json) as Partial<ProfileEntry>;
+	} catch {
+		throw new Error("Invalid JSON — could not parse clipboard content");
+	}
+	if (!entry.name || typeof entry.plugins !== "object") {
+		throw new Error("Invalid profile format — expected { name, plugins }");
+	}
+	return saveProfile(
+		entry.name,
+		entry.plugins as Record<string, boolean>,
+		targetScope,
+		projectPath,
+	);
+}
+
+// ─── Internal helpers ──────────────────────────────────────────────────────────
+
+function slugify(name: string): string {
+	return name
+		.toLowerCase()
+		.trim()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-|-$/g, "");
+}
+
+function generateUniqueId(
+	name: string,
+	existing: Record<string, unknown>,
+): string {
+	const base = slugify(name) || "profile";
+	if (!existing[base]) return base;
+	let n = 2;
+	while (existing[`${base}-${n}`]) n++;
+	return `${base}-${n}`;
+}

package/src/services/resolver.ts

@@ -0,0 +1,344 @@
+/**
+ * Profile resolver — compute the install closure for a team profile.
+ *
+ * Turns a manifest entry into a fully-resolved {@link ResolvedClosure}: the
+ * marketplaces, plugins, MCP servers, binary deps, skills, settings, and env a
+ * machine must have to match the profile. Binary deps are the union of the
+ * profile's own `cliTools` and every enabled plugin's declared `requires.bin`,
+ * deduped by executable name with the project's pin winning.
+ */
+
+import semver from "semver";
+import { cliTools } from "../data/cli-tools.js";
+import { getMarketplaceByName } from "../data/marketplaces.js";
+import { PREDEFINED_PROFILES } from "../data/predefined-profiles.js";
+import type {
+	BinRequirement,
+	ProfileManifest,
+	ProfileManifestEntry,
+	ResolvedBin,
+	ResolvedClosure,
+} from "../types/index.js";
+import { resolvePluginBinRequirements } from "./plugin-requires.js";
+
+export interface ResolveOptions {
+	/**
+	 * Resolve a plugin id to its declared binary requirements. Injectable for
+	 * tests; defaults to reading plugin.json from the marketplace cache.
+	 */
+	binResolver?: (pluginId: string) => Promise<BinRequirement[]>;
+}
+
+/** Normalize a manifest plugins map to pluginId -> version ("latest" for true). */
+function normalizePlugins(
+	plugins: Record<string, string | boolean> | undefined,
+): Record<string, string> {
+	const out: Record<string, string> = {};
+	for (const [id, ver] of Object.entries(plugins ?? {})) {
+		if (ver === false) continue; // explicitly disabled
+		out[id] = ver === true || ver === "" ? "latest" : String(ver);
+	}
+	return out;
+}
+
+/**
+ * Merge a predefined profile (referenced via `extends`) UNDER an entry: the
+ * entry's own plugins/settings take precedence. Predefined skills are bare
+ * display names without repo/path, so they are NOT installable and are skipped.
+ */
+export function resolveExtends(
+	entry: ProfileManifestEntry,
+): ProfileManifestEntry {
+	if (!entry.extends) return entry;
+	const base = PREDEFINED_PROFILES.find((p) => p.id === entry.extends);
+	if (!base) return entry;
+
+	const inheritedPlugins: Record<string, string | boolean> = {};
+	for (const name of base.magusPlugins) {
+		// Entries may pin a marketplace explicitly (e.g. "image-generate@magus-marketing")
+		// for plugins that ship on a channel other than magus. Bare names
+		// still default to @magus.
+		inheritedPlugins[name.includes("@") ? name : `${name}@magus`] = "latest";
+	}
+	for (const name of base.anthropicPlugins) {
+		inheritedPlugins[`${name}@claude-plugins-official`] = "latest";
+	}
+
+	return {
+		...entry,
+		// Entry values win over inherited ones.
+		plugins: { ...inheritedPlugins, ...(entry.plugins ?? {}) },
+		settings: { ...base.settings, ...(entry.settings ?? {}) },
+		// `models` inherits by whole object, not key-by-key: a ModelsConfig is
+		// validated as a complete unit (every grade present, one effort per
+		// model), so a half-inherited merge could produce a config neither side
+		// wrote and neither side validated.
+		...((entry.models ?? base.models)
+			? { models: entry.models ?? base.models }
+			: {}),
+	};
+}
+
+/**
+ * Map a manifest cliTools entry (name -> version) to a BinRequirement.
+ *
+ * Exported so the TUI's CLI Tools screen maps a catalogue tool the same way the
+ * resolver does, rather than keeping a second copy of the mapping.
+ */
+export function cliToolToBin(name: string, version: string): BinRequirement {
+	const tool = cliTools.find((t) => t.name === name);
+	const pinned = version && version !== "latest" ? version : undefined;
+	if (tool) {
+		return {
+			name,
+			via: tool.packageManager,
+			package: tool.packageName,
+			check: tool.checkCommand,
+			version: pinned,
+		};
+	}
+	// Unknown tool: default to bun (magus's toolchain) with name as package.
+	return {
+		name,
+		via: "bun",
+		package: name,
+		check: `${name} --version`,
+		version: pinned,
+	};
+}
+
+/**
+ * Dedupe binary requirements by executable name. Entries are processed in the
+ * order given, so callers put higher-precedence sources first (project pins
+ * before plugin-declared deps); the first entry's installer/version wins and
+ * later ones only contribute provenance.
+ */
+export function dedupeBins(
+	entries: Array<{ bin: BinRequirement; source: string }>,
+): ResolvedBin[] {
+	const byName = new Map<string, ResolvedBin>();
+	for (const { bin, source } of entries) {
+		const existing = byName.get(bin.name);
+		if (existing) {
+			if (!existing.sources.includes(source)) existing.sources.push(source);
+			// A later entry only fills a version the winner left unset.
+			if (existing.version === undefined && bin.version !== undefined) {
+				existing.version = bin.version;
+			}
+			continue;
+		}
+		byName.set(bin.name, { ...bin, sources: [source] });
+	}
+	return [...byName.values()];
+}
+
+/** Collect the binary requirements for a resolved plugin set + profile cliTools. */
+async function resolveBins(
+	entry: ProfileManifestEntry,
+	pluginIds: string[],
+	binResolver: (pluginId: string) => Promise<BinRequirement[]>,
+): Promise<ResolvedBin[]> {
+	const collected: Array<{ bin: BinRequirement; source: string }> = [];
+
+	// Project pins first (highest precedence).
+	for (const [name, version] of Object.entries(entry.cliTools ?? {})) {
+		collected.push({
+			bin: cliToolToBin(name, version),
+			source: `profile:${entry.name}.cliTools`,
+		});
+	}
+
+	// Then each plugin's declared binary deps.
+	for (const pluginId of pluginIds) {
+		const bins = await binResolver(pluginId);
+		for (const bin of bins) {
+			collected.push({ bin, source: `plugin:${pluginId}` });
+		}
+	}
+
+	return dedupeBins(collected);
+}
+
+/** Resolve a single profile (applying `extends`) into an install closure. */
+/**
+ * Add the marketplace every plugin id already names.
+ *
+ * A plugin id carries its marketplace — `dev@magus`, `image-generate@magus-marketing` —
+ * so requiring the manifest to ALSO declare that marketplace is redundant, and
+ * forgetting to is silent: the plugin resolves against a marketplace that was
+ * never registered. `extends` made this the default failure, because it
+ * inherits plugins from a predefined profile and no marketplaces at all.
+ *
+ * Only marketplaces magus already knows are derived, since a repo is needed
+ * to register one. An unknown suffix is left alone for the manifest to declare.
+ * An explicit entry always wins: deriving must never override a pin.
+ */
+export function withDerivedMarketplaces(
+	declared: ProfileManifestEntry["marketplaces"],
+	plugins: Record<string, string>,
+): NonNullable<ProfileManifestEntry["marketplaces"]> {
+	const out = { ...(declared ?? {}) };
+	for (const id of Object.keys(plugins)) {
+		const at = id.lastIndexOf("@");
+		if (at <= 0) continue;
+		const name = id.slice(at + 1);
+		if (out[name]) continue;
+		const known = getMarketplaceByName(name);
+		if (!known?.source.repo) continue;
+		out[name] = { source: "github", repo: known.source.repo };
+	}
+	return out;
+}
+
+export async function resolveProfile(
+	manifest: ProfileManifest,
+	profileId: string,
+	opts: ResolveOptions = {},
+): Promise<ResolvedClosure> {
+	const raw = manifest.profiles[profileId];
+	if (!raw) throw new Error(`Profile "${profileId}" not found in manifest`);
+	const entry = resolveExtends(raw);
+	const binResolver = opts.binResolver ?? resolvePluginBinRequirements;
+
+	const plugins = normalizePlugins(entry.plugins);
+	const bins = await resolveBins(entry, Object.keys(plugins), binResolver);
+
+	return {
+		marketplaces: withDerivedMarketplaces(entry.marketplaces, plugins),
+		plugins,
+		mcpServers: { ...(entry.mcpServers ?? {}) },
+		bins,
+		skills: [...(entry.skills ?? [])],
+		settings: { ...(entry.settings ?? {}) },
+		...(entry.models ? { models: entry.models } : {}),
+		env: {
+			required: [...(entry.env?.required ?? [])],
+			optional: [...(entry.env?.optional ?? [])],
+		},
+	};
+}
+
+/**
+ * Deterministically pick between two version specs for the same id. "latest"
+ * always yields to an explicit pin; two DIFFERENT explicit pins are a conflict,
+ * resolved to the higher semver (order-independent) and reported.
+ */
+function pickVersion(
+	id: string,
+	a: string,
+	b: string,
+): { chosen: string; conflict?: string } {
+	if (a === b) return { chosen: a };
+	if (a === "latest") return { chosen: b };
+	if (b === "latest") return { chosen: a };
+	const higher =
+		semver.valid(a) && semver.valid(b)
+			? semver.gt(a, b)
+				? a
+				: b
+			: a > b
+				? a
+				: b; // lexical fallback for non-semver pins
+	return {
+		chosen: higher,
+		conflict: `${id}: profiles pin ${a} and ${b}; using ${higher}`,
+	};
+}
+
+/**
+ * Merge closure `b` into `a` (union). Version conflicts (plugins and bins) are
+ * resolved deterministically to the higher pin — NOT by profile order — and
+ * collected into `conflicts` so `install`/`profile show` can surface them.
+ */
+function mergeClosures(
+	a: ResolvedClosure,
+	b: ResolvedClosure,
+): ResolvedClosure {
+	const conflicts = [...(a.conflicts ?? []), ...(b.conflicts ?? [])];
+
+	// Plugins: deterministic version pick per id.
+	const plugins: Record<string, string> = { ...a.plugins };
+	for (const [id, ver] of Object.entries(b.plugins)) {
+		const existing = plugins[id];
+		if (existing === undefined) {
+			plugins[id] = ver;
+			continue;
+		}
+		const { chosen, conflict } = pickVersion(id, existing, ver);
+		plugins[id] = chosen;
+		if (conflict) conflicts.push(conflict);
+	}
+
+	// Bins: union by name, deterministic version pick; keep the winning entry's
+	// installer/fields and accumulate provenance from both.
+	const binByName = new Map<string, ResolvedBin>();
+	for (const bin of [...a.bins, ...b.bins]) {
+		const existing = binByName.get(bin.name);
+		if (!existing) {
+			binByName.set(bin.name, { ...bin, sources: [...bin.sources] });
+			continue;
+		}
+		const mergedSources = [...new Set([...existing.sources, ...bin.sources])];
+		const va = existing.version;
+		const vb = bin.version;
+		if (va === undefined && vb === undefined) {
+			existing.sources = mergedSources;
+		} else if (va === undefined) {
+			binByName.set(bin.name, { ...bin, sources: mergedSources });
+		} else if (vb === undefined) {
+			existing.sources = mergedSources;
+		} else {
+			const { chosen, conflict } = pickVersion(bin.name, va, vb);
+			const winner = chosen === va ? existing : bin;
+			binByName.set(bin.name, { ...winner, sources: mergedSources });
+			if (conflict) conflicts.push(conflict);
+		}
+	}
+
+	// Skills: union by repo+path.
+	const skillKey = (s: { repo: string; path: string }) => `${s.repo}#${s.path}`;
+	const skillMap = new Map(b.skills.map((s) => [skillKey(s), s]));
+	for (const s of a.skills) skillMap.set(skillKey(s), s);
+
+	return {
+		marketplaces: { ...b.marketplaces, ...a.marketplaces },
+		plugins,
+		mcpServers: { ...b.mcpServers, ...a.mcpServers },
+		bins: [...binByName.values()],
+		skills: [...skillMap.values()],
+		settings: { ...b.settings, ...a.settings },
+		// Same precedence as settings: `a` wins. Whole-object, for the reason
+		// given in resolveExtends — half a routing config is not a routing config.
+		...((a.models ?? b.models) ? { models: a.models ?? b.models } : {}),
+		env: {
+			required: [...new Set([...a.env.required, ...b.env.required])],
+			optional: [...new Set([...a.env.optional, ...b.env.optional])],
+		},
+		...(conflicts.length > 0 ? { conflicts: [...new Set(conflicts)] } : {}),
+	};
+}
+
+/**
+ * Resolve the union of ALL profiles in a manifest — the closure `magus
+ * install` (no argument) materializes so every profile's deps are present.
+ */
+export async function resolveAllProfiles(
+	manifest: ProfileManifest,
+	opts: ResolveOptions = {},
+): Promise<ResolvedClosure> {
+	const ids = Object.keys(manifest.profiles);
+	let union: ResolvedClosure = {
+		marketplaces: {},
+		plugins: {},
+		mcpServers: {},
+		bins: [],
+		skills: [],
+		settings: {},
+		env: { required: [], optional: [] },
+	};
+	for (const id of ids) {
+		const closure = await resolveProfile(manifest, id, opts);
+		union = mergeClosures(union, closure);
+	}
+	return union;
+}

package/src/services/settings-file.ts

@@ -0,0 +1,69 @@
+/**
+ * Read/modify/write a Claude Code `settings.json`, in place.
+ *
+ * Two rules, and both exist because of damage they prevent:
+ *
+ *  1. **Write IN PLACE, never remove-and-recreate.** `.claude/settings.json` is
+ *     a SYMLINK into `.claude/_profiles/<name>/` whenever a profile is active,
+ *     and `writeFile` follows it — which is what we want. Unlinking the file
+ *     first would break the link and silently detach the project from its
+ *     profile, leaving the next read looking at a fresh, empty file.
+ *  2. **Unparseable is an ERROR, not an empty object.** A settings file that
+ *     fails to parse is a file we do not understand, usually because a human is
+ *     mid-edit. Treating it as `{}` and writing our one key back is how a
+ *     user's whole configuration disappears. We refuse and say so.
+ *
+ * A MISSING file is different from an unparseable one: nothing is lost by
+ * starting from `{}`, so that is what a missing (or empty) file reads as.
+ */
+
+import path from "node:path";
+import fs from "fs-extra";
+
+/**
+ * Parse `settingsPath`. Missing or empty reads as `{}`; unparseable throws.
+ *
+ * Exported for callers that only need the read half — the refusal wording is
+ * the same either way, so nothing has to reimplement it.
+ */
+export async function readSettingsFile(
+	settingsPath: string,
+): Promise<Record<string, unknown>> {
+	if (!(await fs.pathExists(settingsPath))) return {};
+
+	const raw = (await fs.readFile(settingsPath, "utf8")).trim();
+	if (!raw) return {};
+
+	try {
+		return JSON.parse(raw) as Record<string, unknown>;
+	} catch (error) {
+		throw new Error(
+			`${settingsPath} is not valid JSON, refusing to overwrite it: ${String(error)}`,
+		);
+	}
+}
+
+/**
+ * Read, apply `mutate`, write back — preserving every key we did not touch.
+ *
+ * `mutate` may edit the object in place and return nothing, or return a
+ * replacement object. Nothing is written when the read throws, so a settings
+ * file we cannot parse is left exactly as the user left it.
+ */
+export async function updateSettingsFile(
+	settingsPath: string,
+	// biome-ignore lint/suspicious/noConfusingVoidType: the union IS the contract — mutate in place and return nothing, or return a replacement
+	mutate: (settings: Record<string, unknown>) => Record<string, unknown> | void,
+): Promise<void> {
+	const settings = await readSettingsFile(settingsPath);
+	const next =
+		(mutate(settings) as Record<string, unknown> | undefined) ?? settings;
+
+	await fs.ensureDir(path.dirname(settingsPath));
+	// writeFile, never remove-then-create: see rule 1 above.
+	await fs.writeFile(
+		settingsPath,
+		`${JSON.stringify(next, null, 2)}\n`,
+		"utf8",
+	);
+}