claudeup 4.19.0 → 4.23.0

package/src/cli/doctor.ts

@@ -0,0 +1,132 @@
+/**
+ * `claudeup doctor [--fix]`
+ *
+ * Diagnoses (and with --fix, repairs) project health:
+ *   1. Binary dependencies — every requires.bin / cliTools binary on PATH.
+ *      This is the check that would have caught a dead `tmux-mcp`.
+ *   2. Profile symlink integrity — the active profile's links resolve.
+ *   3. Convention compliance — .gitignore + CLAUDE.md blocks (ported engine).
+ */
+
+import fs from "fs-extra";
+import path from "node:path";
+import { readManifest } from "../services/manifest.js";
+import { resolveAllProfiles } from "../services/resolver.js";
+import { checkBinaries, missingBinaries } from "../services/doctor-bins.js";
+import {
+	activeProfile,
+	profileDir,
+} from "../services/symlink-manager.js";
+import { checkProject, fixDoctorIssues } from "../services/doctor.js";
+
+export async function runDoctorCommand(args: string[]): Promise<number> {
+	const fix = args.includes("--fix");
+	const projectPath = process.cwd();
+	let problems = 0;
+
+	// 1. Binary dependencies.
+	const manifest = await readManifest(projectPath);
+	let pluginIds: string[] = [];
+	if (Object.keys(manifest.profiles).length > 0) {
+		const closure = await resolveAllProfiles(manifest);
+		pluginIds = Object.keys(closure.plugins);
+		if (closure.bins.length > 0) {
+			const results = await checkBinaries(closure.bins);
+			const missing = missingBinaries(results);
+			if (missing.length > 0) {
+				console.log("Binary dependencies:");
+				for (const m of missing) {
+					console.log(
+						`  ✗ ${m.name} — run: ${m.installCommand}  (needed by ${m.sources.join(", ")})`,
+					);
+					problems++;
+				}
+			} else {
+				console.log(`✓ All ${closure.bins.length} binary dependencies present.`);
+			}
+		}
+	}
+
+	// 2. Profile symlink integrity.
+	const active = await activeProfile(projectPath);
+	if (active) {
+		const dangling = await danglingLinks(active, projectPath);
+		if (dangling.length > 0) {
+			console.log(`Profile "${active}" has broken symlinks:`);
+			for (const l of dangling) console.log(`  ✗ ${l}`);
+			console.log(`  Fix: claudeup install ${active}`);
+			problems += dangling.length;
+		} else {
+			console.log(`✓ Active profile "${active}" symlinks resolve.`);
+		}
+	}
+
+	// 3. Convention compliance — scoped to THIS project only (the ported engine
+	// can scan every registered project; that's noisy for a project command).
+	if (pluginIds.length > 0) {
+		try {
+			const project = await checkProject(projectPath, pluginIds);
+			const actionable = project.checks.filter((c) => c.status !== "pass");
+			if (actionable.length > 0) {
+				console.log("\nConventions:");
+				for (const check of actionable) {
+					console.log(`  ${check.status === "fail" ? "✗" : "•"} ${check.message}`);
+				}
+				const fixable = actionable.filter((c) => c.fixable).length;
+				const failures = actionable.filter((c) => c.status === "fail").length;
+				if (fix && fixable > 0) {
+					const { fixed, failed } = await fixDoctorIssues({
+						projects: [project],
+						summary: {
+							totalProjects: 1,
+							totalChecks: project.checks.length,
+							passed: 0,
+							warnings: 0,
+							failures,
+							fixable,
+						},
+					});
+					console.log(`\nFixed ${fixed}, failed ${failed}.`);
+				} else if (fixable > 0) {
+					console.log(`\n${fixable} fixable — re-run with --fix.`);
+					problems += failures;
+				}
+			}
+		} catch {
+			// Convention doctor is best-effort; never fail the whole command on it.
+		}
+	}
+
+	if (problems === 0) console.log("\n✓ No problems found.");
+	return problems > 0 && !fix ? 1 : 0;
+}
+
+/** Which of the active profile's expected symlinks are missing or dangling. */
+async function danglingLinks(
+	name: string,
+	projectPath: string,
+): Promise<string[]> {
+	const dir = profileDir(name, projectPath);
+	const checks: Array<{ link: string; target: string }> = [
+		{
+			link: path.join(projectPath, ".claude", "settings.json"),
+			target: path.join(dir, "settings.json"),
+		},
+		{
+			link: path.join(projectPath, ".mcp.json"),
+			target: path.join(dir, "mcp.json"),
+		},
+	];
+	const broken: string[] = [];
+	for (const { link, target } of checks) {
+		try {
+			const stat = await fs.lstat(link);
+			if (stat.isSymbolicLink() && !(await fs.pathExists(target))) {
+				broken.push(path.relative(projectPath, link));
+			}
+		} catch {
+			// link absent — not "broken", the profile may not provide it.
+		}
+	}
+	return broken;
+}

package/src/cli/install.ts

@@ -0,0 +1,360 @@
+/**
+ * `claudeup 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 { createInterface } from "node:readline/promises";
+import type {
+	ProfileSkillRef,
+	ResolvedBin,
+	ResolvedClosure,
+	SkillInfo,
+} from "../types/index.js";
+import { readManifest, validateManifest } from "../services/manifest.js";
+import { resolveAllProfiles, resolveProfile } from "../services/resolver.js";
+import {
+	computeEnvStatus,
+	computeVersionDrift,
+	summarizeClosure,
+} from "../services/install-plan.js";
+import {
+	binInstallCommand,
+	detectToolchains,
+	TOOLCHAIN_BOOTSTRAP,
+} from "../services/toolchain.js";
+import { materializeProfile } from "../services/profile-materializer.js";
+import {
+	activateProfile,
+	activeProfile,
+	PROFILE_GITIGNORE_ENTRIES,
+} from "../services/symlink-manager.js";
+import { ensureGitignoreEntries } from "../services/conventions-manager.js";
+import { detectProfileDrift } from "../services/profile-sync.js";
+import { resolveExecutable } from "../utils/command-utils.js";
+import {
+	addMarketplace,
+	installPlugin,
+	isClaudeAvailable,
+} from "../services/claude-cli.js";
+import {
+	isMarketplaceRegistered,
+	readInstalledPluginsRegistry,
+	readLocalSettings,
+	writeLocalSettings,
+} from "../services/claude-settings.js";
+import { installSkill } from "../services/skills-manager.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("-")),
+	};
+}
+
+async function confirm(question: string): Promise<boolean> {
+	const rl = createInterface({ input: process.stdin, output: process.stdout });
+	try {
+		const answer = (await rl.question(`${question} [Y/n] `)).trim().toLowerCase();
+		return answer === "" || answer === "y" || answer === "yes";
+	} finally {
+		rl.close();
+	}
+}
+
+async function promptValue(question: string): Promise<string> {
+	const rl = createInterface({ input: process.stdin, output: process.stdout });
+	try {
+		return (await rl.question(question)).trim();
+	} finally {
+		rl.close();
+	}
+}
+
+/** Run a shell command, streaming output; resolve true on exit 0. */
+async function runShell(command: string): Promise<boolean> {
+	const { spawn } = await import("node:child_process");
+	return new Promise((resolve) => {
+		const child = spawn(command, { stdio: "inherit", shell: true });
+		child.on("exit", (code) => resolve(code === 0));
+		child.on("error", () => resolve(false));
+	});
+}
+
+// ── --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> {
+	const toolchains = await detectToolchains(closure.bins);
+	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}…`);
+			if (!(await runShell(bootstrap))) {
+				console.warn(`⚠ Failed to install ${tc.name}. Continuing.`);
+			}
+		}
+	}
+}
+
+async function registerMarketplaces(closure: ResolvedClosure): Promise<void> {
+	for (const [name, ref] of Object.entries(closure.marketplaces)) {
+		try {
+			if (await isMarketplaceRegistered(name)) continue;
+			const source = ref.source === "github" ? ref.repo : ref.path;
+			if (!source) continue;
+			console.log(`+ marketplace ${name} (${source})`);
+			await addMarketplace(source);
+		} catch (e) {
+			console.warn(`⚠ marketplace ${name}: ${(e as Error).message}`);
+		}
+	}
+}
+
+async function installPlugins(closure: ResolvedClosure): Promise<void> {
+	for (const pluginId of Object.keys(closure.plugins)) {
+		try {
+			console.log(`+ plugin ${pluginId}`);
+			await installPlugin(pluginId, "user");
+		} 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);
+		console.log(`+ ${bin.name}  (${cmd})`);
+		if (!(await runShell(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);
+
+	const manifest = await readManifest(projectPath);
+	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 \`claudeup 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 registerMarketplaces(closure);
+	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).
+	const toMaterialize = flags.profile ? [flags.profile] : profileIds;
+	for (const id of toMaterialize) {
+		const profileClosure = await resolveProfile(manifest, id);
+		await materializeProfile(id, profileClosure, projectPath);
+	}
+
+	// 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,
+		"# claudeup: 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];
+}

package/src/cli/profile.ts

@@ -0,0 +1,166 @@
+/**
+ * `claudeup profile <list|show|switch|sync> [name]`
+ *
+ * Inspect and switch between team profiles materialized under
+ * `.claude/_profiles/`. Switching is cheap and offline — it just repoints the
+ * shared-config symlinks. `sync` (Phase 5) promotes local drift back into the
+ * committed manifest.
+ */
+
+import path from "node:path";
+import { readManifest } from "../services/manifest.js";
+import { resolveProfile } from "../services/resolver.js";
+import { summarizeClosure } from "../services/install-plan.js";
+import {
+	activateProfile,
+	activeProfile,
+	profileDir,
+	PROFILE_GITIGNORE_ENTRIES,
+} from "../services/symlink-manager.js";
+import { ensureGitignoreEntries } from "../services/conventions-manager.js";
+import { syncProfile } from "../services/profile-sync.js";
+import { checkBinaries, missingBinaries } from "../services/doctor-bins.js";
+import fs from "fs-extra";
+
+export async function runProfileCommand(args: string[]): Promise<number> {
+	const [sub, ...rest] = args;
+	const projectPath = process.cwd();
+
+	switch (sub) {
+		case undefined:
+		case "list":
+			return listProfiles(projectPath);
+		case "show":
+			return showProfile(rest[0], projectPath);
+		case "switch":
+			return switchProfile(rest[0], projectPath);
+		case "sync":
+			return syncActiveProfile(rest[0], projectPath);
+		default:
+			console.error(
+				`Unknown profile command "${sub}". Use: list | show <name> | switch <name> | sync`,
+			);
+			return 1;
+	}
+}
+
+export async function listProfiles(projectPath: string): Promise<number> {
+	const manifest = await readManifest(projectPath);
+	const ids = Object.keys(manifest.profiles);
+	if (ids.length === 0) {
+		console.log("No profiles defined in .claude/profiles.json.");
+		return 0;
+	}
+	const active = await activeProfile(projectPath);
+	console.log("Profiles:");
+	for (const id of ids) {
+		const entry = manifest.profiles[id]!;
+		const marker = id === active ? "●" : " ";
+		const materialized = (await fs.pathExists(profileDir(id, projectPath)))
+			? ""
+			: "  (not installed)";
+		console.log(`  ${marker} ${id} — ${entry.name}${materialized}`);
+	}
+	if (active) console.log(`\nActive: ${active}`);
+	return 0;
+}
+
+export async function showProfile(
+	name: string | undefined,
+	projectPath: string,
+): Promise<number> {
+	if (!name) {
+		console.error("Usage: claudeup profile show <name>");
+		return 1;
+	}
+	const manifest = await readManifest(projectPath);
+	if (!manifest.profiles[name]) {
+		console.error(
+			`Profile "${name}" not found. Available: ${Object.keys(manifest.profiles).join(", ")}`,
+		);
+		return 1;
+	}
+	const closure = await resolveProfile(manifest, name);
+	console.log(`Profile: ${name} (${manifest.profiles[name]!.name})`);
+	for (const line of summarizeClosure(closure)) console.log(`  ${line}`);
+	return 0;
+}
+
+export async function switchProfile(
+	name: string | undefined,
+	projectPath: string,
+): Promise<number> {
+	if (!name) {
+		console.error("Usage: claudeup profile switch <name>");
+		return 1;
+	}
+	const manifest = await readManifest(projectPath);
+	if (!manifest.profiles[name]) {
+		console.error(
+			`Profile "${name}" not found. Available: ${Object.keys(manifest.profiles).join(", ")}`,
+		);
+		return 1;
+	}
+	if (!(await fs.pathExists(profileDir(name, projectPath)))) {
+		console.error(
+			`Profile "${name}" isn't installed yet. Run: claudeup install ${name}`,
+		);
+		return 1;
+	}
+
+	// In profile mode the source of truth is .claude/profiles.json; the
+	// generated dir AND the per-developer symlinks must stay out of git so
+	// switching profiles causes no churn.
+	await ensureGitignoreEntries(
+		path.join(projectPath, ".gitignore"),
+		PROFILE_GITIGNORE_ENTRIES,
+		"# claudeup: generated profile build output + active-profile symlinks",
+	);
+
+	await activateProfile(name, projectPath);
+	console.log(`✓ Switched to profile: ${name}`);
+
+	// Verify the profile's binary deps are actually usable — the switch itself
+	// succeeds (symlinks are valid), but warn so "switched" isn't misleading.
+	try {
+		const closure = await resolveProfile(manifest, name);
+		const missing = missingBinaries(await checkBinaries(closure.bins));
+		if (missing.length > 0) {
+			console.log(
+				`\n⚠ ${missing.length} binary dependenc${missing.length === 1 ? "y is" : "ies are"} missing:`,
+			);
+			for (const m of missing) console.log(`  ✗ ${m.name} — run: ${m.installCommand}`);
+			console.log(`Run \`claudeup install ${name}\` to install them.`);
+		}
+	} catch {
+		// Verification is best-effort — never fail a valid switch on it.
+	}
+	return 0;
+}
+
+export async function syncActiveProfile(
+	nameArg: string | undefined,
+	projectPath: string,
+): Promise<number> {
+	const name = nameArg ?? (await activeProfile(projectPath));
+	if (!name) {
+		console.error(
+			"No active profile to sync. Pass a name: claudeup profile sync <name>",
+		);
+		return 1;
+	}
+	try {
+		const { changes, wrote } = await syncProfile(name, projectPath);
+		if (!wrote) {
+			console.log(`Profile "${name}" is already in sync with the manifest.`);
+			return 0;
+		}
+		console.log(`Synced "${name}" → .claude/profiles.json:`);
+		for (const c of changes) console.log(`  ${c.kind}: ${c.detail}`);
+		console.log("\nReview the diff and commit .claude/profiles.json.");
+		return 0;
+	} catch (e) {
+		console.error((e as Error).message);
+		return 1;
+	}
+}