claudeup 4.18.0 → 4.22.0

package/src/services/profile-materializer.ts

@@ -0,0 +1,61 @@
+/**
+ * Materialize a resolved profile into `.claude/_profiles/<name>/`.
+ *
+ * Writes the shared config the symlink manager later points at:
+ *   _profiles/<name>/settings.json  — enabledPlugins + the profile's settings
+ *   _profiles/<name>/mcp.json       — the profile's MCP servers
+ *   _profiles/<name>/skills/        — created empty; skills install into it
+ *                                     (through the activated symlink)
+ *
+ * This is pure output derived from a ResolvedClosure — it performs no installs
+ * and touches no global state, so it is fully testable with a temp dir.
+ */
+
+import fs from "fs-extra";
+import path from "node:path";
+import type { ResolvedClosure } from "../types/index.js";
+import { profileDir } from "./symlink-manager.js";
+
+/**
+ * Build the settings.json contents for a profile: every resolved plugin
+ * enabled, merged with the profile's declared settings. The profile's settings
+ * win over the derived enabledPlugins only if it explicitly sets that key
+ * (it normally won't).
+ */
+export function buildProfileSettings(
+	closure: ResolvedClosure,
+): Record<string, unknown> {
+	const enabledPlugins: Record<string, boolean> = {};
+	for (const pluginId of Object.keys(closure.plugins)) {
+		enabledPlugins[pluginId] = true;
+	}
+	return { enabledPlugins, ...closure.settings };
+}
+
+/** Build the .mcp.json contents for a profile. */
+export function buildProfileMcp(
+	closure: ResolvedClosure,
+): { mcpServers: Record<string, unknown> } {
+	return { mcpServers: { ...closure.mcpServers } };
+}
+
+/**
+ * Write `_profiles/<name>/` from a resolved closure. Idempotent: overwrites
+ * settings.json / mcp.json and ensures skills/ exists. Returns the dir path.
+ */
+export async function materializeProfile(
+	name: string,
+	closure: ResolvedClosure,
+	projectPath?: string,
+): Promise<string> {
+	const dir = profileDir(name, projectPath);
+	await fs.ensureDir(dir);
+	await fs.writeJson(path.join(dir, "settings.json"), buildProfileSettings(closure), {
+		spaces: 2,
+	});
+	await fs.writeJson(path.join(dir, "mcp.json"), buildProfileMcp(closure), {
+		spaces: 2,
+	});
+	await fs.ensureDir(path.join(dir, "skills"));
+	return dir;
+}

package/src/services/profile-sync.ts

@@ -0,0 +1,150 @@
+/**
+ * `profile sync` — promote edits made to the active profile dir back into the
+ * committed manifest.
+ *
+ * `.claude/_profiles/<name>/` is generated build output, so an edit to the
+ * symlinked settings.json / mcp.json would be lost on the next `install`. Sync
+ * reverse-materializes those files into `.claude/profiles.json` so the change
+ * becomes a reviewable manifest diff instead of silent, throwaway drift.
+ */
+
+import fs from "fs-extra";
+import path from "node:path";
+import type {
+	McpServerConfig,
+	ProfileManifest,
+	ProfileManifestEntry,
+} from "../types/index.js";
+import { readManifest, writeManifest } from "./manifest.js";
+import { profileDir } from "./symlink-manager.js";
+
+export interface SyncChange {
+	kind: "plugin-added" | "plugin-removed" | "settings-changed" | "mcp-changed";
+	detail: string;
+}
+
+/**
+ * Merge a materialized profile's settings.json + mcp.json back into a manifest
+ * entry. Pure: returns the updated entry and the list of changes.
+ *
+ * - enabledPlugins present but not in the entry -> added as "latest".
+ * - entry plugins that are no longer enabled -> removed.
+ * - an existing version PIN is preserved (enabled != downgrade-to-latest).
+ * - non-enabledPlugins settings keys replace the entry's settings.
+ * - mcpServers replace the entry's mcpServers when they differ.
+ */
+export function computeSync(
+	entry: ProfileManifestEntry,
+	materializedSettings: Record<string, unknown>,
+	materializedMcp: { mcpServers?: Record<string, McpServerConfig> },
+	now: string = new Date().toISOString(),
+): { entry: ProfileManifestEntry; changes: SyncChange[] } {
+	const changes: SyncChange[] = [];
+	const next: ProfileManifestEntry = { ...entry };
+
+	const enabled = (materializedSettings.enabledPlugins ?? {}) as Record<
+		string,
+		boolean
+	>;
+	const currentPlugins = { ...(entry.plugins ?? {}) };
+
+	// Additions: enabled plugins the manifest doesn't list.
+	for (const [id, on] of Object.entries(enabled)) {
+		if (on && !(id in currentPlugins)) {
+			currentPlugins[id] = "latest";
+			changes.push({ kind: "plugin-added", detail: id });
+		}
+	}
+	// Removals: manifest plugins no longer enabled.
+	for (const id of Object.keys(entry.plugins ?? {})) {
+		if (!enabled[id]) {
+			delete currentPlugins[id];
+			changes.push({ kind: "plugin-removed", detail: id });
+		}
+	}
+	next.plugins = currentPlugins;
+
+	// Settings = everything in the materialized file except enabledPlugins.
+	const { enabledPlugins: _drop, ...settings } = materializedSettings;
+	if (JSON.stringify(settings) !== JSON.stringify(entry.settings ?? {})) {
+		if (Object.keys(settings).length > 0) next.settings = settings;
+		else delete next.settings;
+		changes.push({ kind: "settings-changed", detail: "settings updated" });
+	}
+
+	// MCP servers.
+	const mcp = materializedMcp.mcpServers ?? {};
+	if (JSON.stringify(mcp) !== JSON.stringify(entry.mcpServers ?? {})) {
+		if (Object.keys(mcp).length > 0) next.mcpServers = mcp;
+		else delete next.mcpServers;
+		changes.push({ kind: "mcp-changed", detail: "mcp servers updated" });
+	}
+
+	// Refresh the timestamp when anything changed. `now` is injectable so
+	// callers/tests control it (and computeSync stays pure).
+	if (changes.length > 0) next.updatedAt = now;
+
+	return { entry: next, changes };
+}
+
+/**
+ * Detect drift between a materialized profile and the manifest WITHOUT writing.
+ * Returns the changes `sync` would promote (empty = in sync). Returns [] if the
+ * profile isn't materialized (nothing to lose).
+ */
+export async function detectProfileDrift(
+	name: string,
+	projectPath?: string,
+): Promise<SyncChange[]> {
+	const manifest = await readManifest(projectPath);
+	const entry = manifest.profiles[name];
+	if (!entry) return [];
+
+	const dir = profileDir(name, projectPath);
+	const settingsPath = path.join(dir, "settings.json");
+	if (!(await fs.pathExists(settingsPath))) return [];
+
+	const mcpPath = path.join(dir, "mcp.json");
+	const materializedSettings = await fs.readJson(settingsPath);
+	const materializedMcp = (await fs.pathExists(mcpPath))
+		? await fs.readJson(mcpPath)
+		: { mcpServers: {} };
+
+	return computeSync(entry, materializedSettings, materializedMcp).changes;
+}
+
+/**
+ * Read the materialized active profile, merge it into the manifest, and write
+ * the manifest back if anything changed. Returns the applied changes.
+ */
+export async function syncProfile(
+	name: string,
+	projectPath?: string,
+): Promise<{ changes: SyncChange[]; wrote: boolean }> {
+	const manifest: ProfileManifest = await readManifest(projectPath);
+	const entry = manifest.profiles[name];
+	if (!entry) throw new Error(`Profile "${name}" not found in manifest`);
+
+	const dir = profileDir(name, projectPath);
+	const settingsPath = path.join(dir, "settings.json");
+	const mcpPath = path.join(dir, "mcp.json");
+	if (!(await fs.pathExists(settingsPath))) {
+		throw new Error(`Profile "${name}" isn't materialized (${settingsPath} missing).`);
+	}
+
+	const materializedSettings = await fs.readJson(settingsPath);
+	const materializedMcp = (await fs.pathExists(mcpPath))
+		? await fs.readJson(mcpPath)
+		: { mcpServers: {} };
+
+	const { entry: nextEntry, changes } = computeSync(
+		entry,
+		materializedSettings,
+		materializedMcp,
+	);
+	if (changes.length === 0) return { changes: [], wrote: false };
+
+	manifest.profiles[name] = nextEntry;
+	await writeManifest(manifest, projectPath);
+	return { changes, wrote: true };
+}

package/src/services/resolver.ts

@@ -0,0 +1,293 @@
+/**
+ * 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 type {
+	BinRequirement,
+	ProfileManifest,
+	ProfileManifestEntry,
+	ResolvedBin,
+	ResolvedClosure,
+} from "../types/index.js";
+import { cliTools } from "../data/cli-tools.js";
+import { PREDEFINED_PROFILES } from "../data/predefined-profiles.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. "seo@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 ?? {}) },
+	};
+}
+
+/** Map a manifest cliTools entry (name -> version) to a BinRequirement. */
+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 (claudeup'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. */
+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: { ...(entry.marketplaces ?? {}) },
+		plugins,
+		mcpServers: { ...(entry.mcpServers ?? {}) },
+		bins,
+		skills: [...(entry.skills ?? [])],
+		settings: { ...(entry.settings ?? {}) },
+		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)) {
+		if (plugins[id] === undefined) {
+			plugins[id] = ver;
+			continue;
+		}
+		const { chosen, conflict } = pickVersion(id, plugins[id]!, 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 },
+		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 `claudeup
+ * 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/symlink-manager.ts

@@ -0,0 +1,146 @@
+/**
+ * Profile symlink manager.
+ *
+ * Materialized profiles live at `.claude/_profiles/<name>/` (generated,
+ * gitignored). The active profile is made "live" by symlinking the shared
+ * config files into place:
+ *
+ *   .claude/settings.json  ->  .claude/_profiles/<name>/settings.json
+ *   .claude/skills         ->  .claude/_profiles/<name>/skills
+ *   .mcp.json              ->  .claude/_profiles/<name>/mcp.json
+ *
+ * Switching profiles just repoints these links — no network, no reinstall.
+ * settings.local.json is NEVER linked: it holds personal credentials and must
+ * survive switches untouched.
+ */
+
+import fs from "fs-extra";
+import path from "node:path";
+
+/**
+ * Paths that must be gitignored once a project uses profiles: the generated
+ * build output plus the active-profile symlinks. Only .claude/profiles.json is
+ * the committed source of truth. settings.local.json is intentionally NOT here
+ * (it's already gitignored elsewhere and holds personal credentials).
+ */
+export const PROFILE_GITIGNORE_ENTRIES = [
+	".claude/_profiles/",
+	".claude/settings.json",
+	".claude/skills",
+	".mcp.json",
+];
+
+/** The generated, gitignored directory holding materialized profiles. */
+export function profilesRoot(projectPath?: string): string {
+	const base = projectPath ?? process.cwd();
+	return path.join(base, ".claude", "_profiles");
+}
+
+/** The materialized directory for one profile. */
+export function profileDir(name: string, projectPath?: string): string {
+	return path.join(profilesRoot(projectPath), name);
+}
+
+/** The set of links an active profile owns, as [linkPath, targetPath] pairs. */
+function linkTargets(
+	name: string,
+	projectPath?: string,
+): Array<{ link: string; target: string }> {
+	const base = projectPath ?? process.cwd();
+	const dir = profileDir(name, projectPath);
+	return [
+		{
+			link: path.join(base, ".claude", "settings.json"),
+			target: path.join(dir, "settings.json"),
+		},
+		{
+			link: path.join(base, ".claude", "skills"),
+			target: path.join(dir, "skills"),
+		},
+		{
+			link: path.join(base, ".mcp.json"),
+			target: path.join(dir, "mcp.json"),
+		},
+	];
+}
+
+/**
+ * Point `link` at `target` with a relative symlink. Any existing file, dir, or
+ * link at `link` is removed first. The target need not exist yet (dangling
+ * links are tolerated so a profile can be activated before every artifact is
+ * materialized), but its parent is created.
+ */
+async function relink(link: string, target: string): Promise<void> {
+	await fs.ensureDir(path.dirname(link));
+	await fs.remove(link);
+	const rel = path.relative(path.dirname(link), target);
+	await fs.symlink(rel, link);
+}
+
+/**
+ * Activate a profile: repoint every shared-config symlink into its
+ * materialized directory. Only links whose target exists in the profile dir
+ * are created (e.g. a profile with no skills/ dir gets no skills symlink).
+ */
+export async function activateProfile(
+	name: string,
+	projectPath?: string,
+): Promise<void> {
+	const dir = profileDir(name, projectPath);
+	if (!(await fs.pathExists(dir))) {
+		throw new Error(
+			`Profile "${name}" is not materialized (${dir} missing). Run \`claudeup install ${name}\`.`,
+		);
+	}
+	for (const { link, target } of linkTargets(name, projectPath)) {
+		if (await fs.pathExists(target)) {
+			await relink(link, target);
+		} else {
+			// Profile doesn't provide this artifact — remove a stale link only if
+			// it currently points into a profile dir (don't clobber a real file).
+			if (await isProfileLink(link, projectPath)) {
+				await fs.remove(link);
+			}
+		}
+	}
+}
+
+/** Is `link` a symlink pointing into `.claude/_profiles/`? */
+async function isProfileLink(
+	link: string,
+	projectPath?: string,
+): Promise<boolean> {
+	try {
+		const stat = await fs.lstat(link);
+		if (!stat.isSymbolicLink()) return false;
+		const resolved = path.resolve(
+			path.dirname(link),
+			await fs.readlink(link),
+		);
+		return resolved.startsWith(profilesRoot(projectPath) + path.sep);
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * The name of the currently active profile, derived from where
+ * .claude/settings.json points. Returns null if it isn't a profile symlink.
+ */
+export async function activeProfile(
+	projectPath?: string,
+): Promise<string | null> {
+	const base = projectPath ?? process.cwd();
+	const link = path.join(base, ".claude", "settings.json");
+	try {
+		const stat = await fs.lstat(link);
+		if (!stat.isSymbolicLink()) return null;
+		const resolved = path.resolve(path.dirname(link), await fs.readlink(link));
+		const root = profilesRoot(projectPath) + path.sep;
+		if (!resolved.startsWith(root)) return null;
+		// resolved = <root>/<name>/settings.json → take the first segment.
+		return resolved.slice(root.length).split(path.sep)[0] ?? null;
+	} catch {
+		return null;
+	}
+}