magus-cli 0.0.0-placeholder → 7.0.0

package/src/services/profile-adopt.ts

@@ -0,0 +1,206 @@
+/**
+ * Adopt a project into profile management.
+ *
+ * `install` and `update` both speak the language of `.claude/profiles.json`,
+ * and most repos do not have one. The answer is to write one from what the
+ * project already has — enabled plugins, MCP servers, settings — rather than
+ * to run a second, manifest-free code path beside it. One command shape, one
+ * source of truth, and the generated file is a reviewable diff the user can
+ * commit and hand to the rest of the team.
+ *
+ * Plugins are adopted as "latest", never as the version that happens to be
+ * installed today. Pinning what a machine drifted to would turn one developer's
+ * accident into the team's contract.
+ */
+
+import type {
+	McpServerConfig,
+	ProfileManifest,
+	ProfileManifestEntry,
+} from "../types/index.js";
+import {
+	getEnabledPlugins,
+	getGlobalEnabledPlugins,
+	readMcpConfig,
+	readSettings,
+} from "./claude-settings.js";
+import { emptyManifest } from "./manifest.js";
+import { withDerivedMarketplaces } from "./resolver.js";
+
+/** The profile id used when adopting a project that has no manifest. */
+export const ADOPTED_PROFILE_ID = "default";
+
+export interface AdoptInput {
+	/** Union of enabled plugins across every scope: id -> enabled. */
+	enabledPlugins: Record<string, boolean>;
+	/** Project `.claude/settings.json`, verbatim. */
+	settings: Record<string, unknown>;
+	/** Project `.mcp.json` servers. */
+	mcpServers: Record<string, McpServerConfig>;
+	/** Display name for the generated profile. */
+	name?: string;
+	/** Injectable clock so the output is deterministic in tests. */
+	now?: string;
+}
+
+/**
+ * Build a manifest entry from captured project state. Pure.
+ *
+ * `enabledPlugins` is dropped from `settings` deliberately: it is expressed as
+ * the entry's `plugins` map, and materialization regenerates it. Carrying both
+ * would let them disagree.
+ */
+/**
+ * Settings keys that describe THIS MACHINE, not the project, and must never be
+ * copied into a manifest meant to be committed.
+ *
+ * - `enabledPlugins` is expressed as the entry's `plugins` map and regenerated
+ *   by materialization; carrying both lets them disagree.
+ * - `installedPluginVersions` is magus's private record of what this machine
+ *   has on disk. Committing it publishes one developer's install state as if it
+ *   were the team's contract, and it goes stale the moment anyone updates.
+ */
+const MACHINE_ONLY_SETTINGS_KEYS = [
+	"enabledPlugins",
+	"installedPluginVersions",
+] as const;
+
+/**
+ * Settings values that mention an absolute path under the user's home
+ * directory. Not stripped — a `permissions.additionalDirectories` list is often
+ * genuinely wanted — but surfaced so the user reviews them before committing.
+ */
+export function findMachineSpecificPaths(
+	settings: Record<string, unknown>,
+	home: string = process.env.HOME ?? "",
+): string[] {
+	if (!home) return [];
+	const hits: string[] = [];
+	const walk = (value: unknown, path: string): void => {
+		if (typeof value === "string") {
+			if (value.includes(home)) hits.push(`${path} = ${value}`);
+			return;
+		}
+		if (Array.isArray(value)) {
+			value.forEach((v, i) => walk(v, `${path}[${i}]`));
+			return;
+		}
+		if (value && typeof value === "object") {
+			for (const [k, v] of Object.entries(value)) walk(v, `${path}.${k}`);
+		}
+	};
+	for (const [k, v] of Object.entries(settings)) walk(v, k);
+	return hits;
+}
+
+export function buildAdoptedProfile(input: AdoptInput): ProfileManifestEntry {
+	const plugins: Record<string, string> = {};
+	for (const [id, enabled] of Object.entries(input.enabledPlugins)) {
+		// A plugin id must name its marketplace; anything else cannot be resolved
+		// or reinstalled on another machine, so it has no place in a team manifest.
+		if (enabled && id.includes("@")) plugins[id] = "latest";
+	}
+
+	const settings = { ...input.settings };
+	for (const key of MACHINE_ONLY_SETTINGS_KEYS) delete settings[key];
+
+	const entry: ProfileManifestEntry = {
+		name: input.name ?? "Default",
+		marketplaces: withDerivedMarketplaces(undefined, plugins),
+		plugins,
+		createdAt: input.now ?? new Date().toISOString(),
+	};
+	if (Object.keys(input.mcpServers).length > 0) {
+		entry.mcpServers = input.mcpServers;
+	}
+	if (Object.keys(settings).length > 0) entry.settings = settings;
+	return entry;
+}
+
+export interface AdoptResult {
+	manifest: ProfileManifest;
+	profileId: string;
+	entry: ProfileManifestEntry;
+	counts: { plugins: number; mcpServers: number; settingsKeys: number };
+	/** Which settings file the plugin list came from. */
+	source: AdoptSource;
+	/** Enabled plugin ids skipped because they name no marketplace. */
+	skipped: string[];
+	/** Carried-over settings values naming an absolute path under $HOME. */
+	machinePaths: string[];
+}
+
+/** Which settings file the adopted plugin list came from. */
+export type AdoptSource = "project" | "user";
+
+/**
+ * Find the plugins to adopt, preferring PROJECT scope.
+ *
+ * The generated manifest is meant to be committed, so its plugin list must
+ * describe the repo, not the machine. `.claude/settings.json` is exactly that:
+ * the repo's own committed choice. User scope (`~/.claude/settings.json`) is
+ * one developer's global set and local scope is gitignored personal state —
+ * adopting either silently would publish a personal setup as the team's
+ * contract.
+ *
+ * User scope is still offered as a fallback, because a developer who enables
+ * everything globally would otherwise have nothing to adopt. The caller is told
+ * which source was used and says so, so the choice is never invisible.
+ */
+async function collectEnabledPlugins(
+	projectPath: string,
+): Promise<{ plugins: Record<string, boolean>; source: AdoptSource }> {
+	const project = await getEnabledPlugins(projectPath).catch(() => ({}));
+	if (Object.values(project).some(Boolean)) {
+		return { plugins: project, source: "project" };
+	}
+	const user = await getGlobalEnabledPlugins().catch(() => ({}));
+	return { plugins: user, source: "user" };
+}
+
+/**
+ * Read this project's current state and produce the manifest that describes it.
+ * Does not write — the caller confirms first.
+ */
+export async function adoptCurrentProject(
+	projectPath: string,
+	name?: string,
+): Promise<AdoptResult> {
+	const { plugins: enabledPlugins, source } =
+		await collectEnabledPlugins(projectPath);
+	const settings = (await readSettings(projectPath)) as unknown as Record<
+		string,
+		unknown
+	>;
+	const mcp = await readMcpConfig(projectPath);
+
+	const entry = buildAdoptedProfile({
+		enabledPlugins,
+		settings,
+		mcpServers: mcp.mcpServers ?? {},
+		name,
+	});
+
+	const manifest = emptyManifest();
+	manifest.profiles[ADOPTED_PROFILE_ID] = entry;
+
+	const skipped = Object.entries(enabledPlugins)
+		.filter(([id, on]) => on && !id.includes("@"))
+		.map(([id]) => id);
+
+	return {
+		manifest,
+		profileId: ADOPTED_PROFILE_ID,
+		entry,
+		source,
+		counts: {
+			plugins: Object.keys(entry.plugins ?? {}).length,
+			mcpServers: Object.keys(entry.mcpServers ?? {}).length,
+			settingsKeys: Object.keys(entry.settings ?? {}).length,
+		},
+		skipped,
+		machinePaths: findMachineSpecificPaths(
+			(entry.settings ?? {}) as Record<string, unknown>,
+		),
+	};
+}

package/src/services/profile-materializer.ts

@@ -0,0 +1,133 @@
+/**
+ * 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>/models.json    — per-subagent model routing, when the
+ *                                     profile declares any; REMOVED when it
+ *                                     does not
+ *   _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 path from "node:path";
+import fs from "fs-extra";
+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).
+ *
+ * `allPluginIds` is the manifest-wide union of plugins across every profile.
+ * Plugins in the union that this profile does NOT want are written as an
+ * explicit `false`, which is what makes `profile switch` exclusive rather than
+ * additive. Claude Code resolves enabledPlugins **per plugin id**, walking from
+ * the highest-precedence scope down and taking the first scope that mentions
+ * the id — an id a scope omits falls through to the next one. Since
+ * `magus install` installs the union at user scope, every non-member would
+ * otherwise inherit that user-scope `true` and stay enabled while a profile
+ * that excludes it is active. Omitting the union (the default) preserves the
+ * old additive behavior for callers that have no cross-profile view.
+ */
+export function buildProfileSettings(
+	closure: ResolvedClosure,
+	allPluginIds: readonly string[] = [],
+): Record<string, unknown> {
+	const enabledPlugins: Record<string, boolean> = {};
+	for (const pluginId of allPluginIds) {
+		enabledPlugins[pluginId] = false;
+	}
+	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 } };
+}
+
+/**
+ * Seed a profile's skills/ dir from the project's pre-existing `.claude/skills/`.
+ *
+ * Activating a profile replaces `.claude/skills` with a symlink into the profile
+ * dir, and replacing means `fs.remove` first. A project that committed its own
+ * skills before adopting profiles would lose them at that moment. So the first
+ * time a profile's skills/ dir is created, any real (non-symlink) project skills
+ * are copied in — every profile inherits what the project already had, and the
+ * link swap destroys nothing.
+ *
+ * Only runs when the profile's skills/ dir does not exist yet, so it never
+ * fights a later `skills-manager` install or re-adds a skill the user removed.
+ */
+async function seedSkillsFromProject(
+	skillsDir: string,
+	projectPath?: string,
+): Promise<void> {
+	if (await fs.pathExists(skillsDir)) return;
+
+	const projectSkills = path.join(
+		projectPath ?? process.cwd(),
+		".claude",
+		"skills",
+	);
+	try {
+		// lstat, not pathExists: an existing profile symlink is not a source.
+		const stat = await fs.lstat(projectSkills);
+		if (!stat.isDirectory() || stat.isSymbolicLink()) return;
+		if ((await fs.readdir(projectSkills)).length === 0) return;
+		await fs.copy(projectSkills, skillsDir, { dereference: true });
+	} catch {
+		// No project skills dir (or unreadable) — nothing to carry over.
+	}
+}
+
+/**
+ * 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,
+	allPluginIds: readonly string[] = [],
+): Promise<string> {
+	const dir = profileDir(name, projectPath);
+	await fs.ensureDir(dir);
+	await fs.writeJson(
+		path.join(dir, "settings.json"),
+		buildProfileSettings(closure, allPluginIds),
+		{ spaces: 2 },
+	);
+	await fs.writeJson(path.join(dir, "mcp.json"), buildProfileMcp(closure), {
+		spaces: 2,
+	});
+
+	// models.json is the one artifact that is REMOVED when the closure lacks it.
+	// Every other file here is unconditional, so "overwrite" is enough; routing
+	// is optional, and a profile that dropped it would otherwise keep routing
+	// from a file nothing writes any more — `magus models off` could not turn
+	// routing off, because the hook walks up to the nearest models.json and this
+	// one would still be there (and still linked).
+	const modelsPath = path.join(dir, "models.json");
+	if (closure.models) {
+		await fs.writeJson(modelsPath, closure.models, { spaces: 2 });
+	} else {
+		await fs.remove(modelsPath);
+	}
+
+	const skillsDir = path.join(dir, "skills");
+	await seedSkillsFromProject(skillsDir, projectPath);
+	await fs.ensureDir(skillsDir);
+	return dir;
+}

package/src/services/profile-sync.ts

@@ -0,0 +1,158 @@
+/**
+ * `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 path from "node:path";
+import fs from "fs-extra";
+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 {
+			// biome-ignore lint/performance/noDelete: the manifest entry is serialised to profiles.json and diffed with JSON.stringify/toStrictEqual; the key must be absent, not undefined
+			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 {
+			// biome-ignore lint/performance/noDelete: the manifest entry is serialised to profiles.json and diffed with JSON.stringify/toStrictEqual; the key must be absent, not undefined
+			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 };
+}