magus-cli 0.0.0-placeholder → 7.1.0

package/src/cli/profile.ts

@@ -0,0 +1,197 @@
+/**
+ * `magus 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 fs from "fs-extra";
+import { ensureGitignoreEntries } from "../services/conventions-manager.js";
+import { checkBinaries, missingBinaries } from "../services/doctor-bins.js";
+import { summarizeClosure } from "../services/install-plan.js";
+import { getManifestPath, readManifest } from "../services/manifest.js";
+import { syncProfile } from "../services/profile-sync.js";
+import { resolveProfile } from "../services/resolver.js";
+import {
+	PROFILE_GITIGNORE_ENTRIES,
+	activateProfile,
+	activeProfile,
+	profileDir,
+} from "../services/symlink-manager.js";
+import { ensureManifest } from "./bootstrap.js";
+
+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 "init":
+			return initProfile(
+				args.includes("--yes") || args.includes("-y"),
+				projectPath,
+			);
+		case "sync":
+			return syncActiveProfile(rest[0], projectPath);
+		default:
+			console.error(
+				`Unknown profile command "${sub}". Use: list | show <name> | switch <name> | init | sync`,
+			);
+			return 1;
+	}
+}
+
+/**
+ * `profile init` — write a manifest describing this project as it stands.
+ *
+ * The same adoption `install`/`update` offer, available on its own so a repo
+ * can be brought under profile management without installing anything.
+ */
+export async function initProfile(
+	yes: boolean,
+	projectPath: string,
+): Promise<number> {
+	const existing = await readManifest(projectPath);
+	if (Object.keys(existing.profiles).length > 0) {
+		console.error(
+			`${getManifestPath(projectPath)} already defines: ${Object.keys(existing.profiles).join(", ")}`,
+		);
+		console.error("Use `magus profile sync` to promote local edits into it.");
+		return 1;
+	}
+	// `profile init` exists to create the manifest, so it is the one caller that
+	// may do so unattended.
+	return (await ensureManifest(projectPath, { allowAdopt: yes })) ? 0 : 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: magus profile show <name>");
+		return 1;
+	}
+	const manifest = await readManifest(projectPath);
+	const entry = manifest.profiles[name];
+	if (!entry) {
+		console.error(
+			`Profile "${name}" not found. Available: ${Object.keys(manifest.profiles).join(", ")}`,
+		);
+		return 1;
+	}
+	const closure = await resolveProfile(manifest, name);
+	console.log(`Profile: ${name} (${entry.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: magus 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: magus 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,
+		"# magus: 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 \`magus 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: magus 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;
+	}
+}

package/src/cli/prompt.ts

@@ -0,0 +1,32 @@
+/**
+ * Terminal prompting shared by the non-interactive commands.
+ *
+ * These lived inside cli/install.ts until `update` and the adopt flow needed
+ * the same three. One copy, so a fix to (say) the Y/n default reaches every
+ * command at once.
+ */
+
+import { createInterface } from "node:readline/promises";
+
+/** Y/n prompt. Empty input means yes. */
+export 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();
+	}
+}
+
+/** Free-text prompt, trimmed. */
+export 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();
+	}
+}

package/src/cli/router.ts

@@ -0,0 +1,264 @@
+/**
+ * magus subcommand router.
+ *
+ * Parses argv and dispatches to a command handler. Commands run to completion
+ * and return an exit code; bare invocation (or an unknown token) falls through
+ * to the interactive TUI, preserving magus's historical behavior.
+ */
+
+import type { ThemeMode } from "@opentui/core";
+import { checkForUpdates } from "../services/version-check.js";
+import { type ThemeEnv, parseThemeWord } from "../ui/theme-resolve.js";
+import { runDoctorCommand } from "./doctor.js";
+import { runInstallCommand } from "./install.js";
+import { runModelsCommand } from "./models.js";
+import { runProfileCommand } from "./profile.js";
+import { runUpdateCommand } from "./update.js";
+import { runUpgradeCommand } from "./upgrade.js";
+
+export interface RouteOutcome {
+	/** A subcommand (or top-level flag) handled the invocation. */
+	handled: boolean;
+	/** Exit code to use when `handled` is true. */
+	exitCode?: number;
+	/** No subcommand matched — the caller should launch the TUI. */
+	launchTui: boolean;
+	/** From --theme, validated. Only meaningful when launchTui is true. */
+	theme?: ThemeMode;
+}
+
+export type ThemeFlagParse =
+	| { ok: true; theme?: ThemeMode; rest: string[] }
+	| { ok: false; message: string };
+
+/**
+ * Pull `--theme light|dark` (or `--theme=…`) out of argv.
+ *
+ * Exact words only, the same rule every other theme source follows — so
+ * `--theme Dark` errors instead of silently differing from `TERM_THEME=Dark`.
+ * A flag is typed on purpose, so a bad value is an error rather than the "no
+ * opinion" an inherited variable gets. `--theme` as the last token, or followed
+ * by another `--flag`, is the same error.
+ */
+export function parseThemeFlag(argv: string[]): ThemeFlagParse {
+	const rest: string[] = [];
+	let theme: ThemeMode | undefined;
+
+	const invalid = (got: string | undefined): ThemeFlagParse => ({
+		ok: false,
+		message:
+			got === undefined
+				? 'magus: --theme must be "light" or "dark" (no value given)'
+				: `magus: --theme must be "light" or "dark" (got "${got}")`,
+	});
+
+	for (let i = 0; i < argv.length; i += 1) {
+		const token = argv[i] as string;
+		let value: string | undefined;
+
+		if (token === "--theme") {
+			const next = argv[i + 1];
+			if (next === undefined || next.startsWith("--"))
+				return invalid(undefined);
+			value = next;
+			i += 1;
+		} else if (token.startsWith("--theme=")) {
+			value = token.slice("--theme=".length);
+		} else {
+			rest.push(token);
+			continue;
+		}
+
+		const parsed = parseThemeWord(value);
+		if (parsed === null) return invalid(value);
+		theme = parsed;
+	}
+
+	return theme === undefined ? { ok: true, rest } : { ok: true, theme, rest };
+}
+
+const HANDLED = (exitCode: number): RouteOutcome => ({
+	handled: true,
+	exitCode,
+	launchTui: false,
+});
+const LAUNCH_TUI: RouteOutcome = { handled: false, launchTui: true };
+
+/**
+ * Every name the switch below handles.
+ *
+ * Declared once so the theme resolution and the dispatch cannot disagree about
+ * what counts as a subcommand — a name in one and not the other would print an
+ * unthemed report, which is the bug this set exists to prevent.
+ */
+const SUBCOMMANDS = new Set([
+	"update",
+	"upgrade",
+	"install",
+	"profile",
+	"models",
+	"doctor",
+]);
+
+export async function route(
+	argv: string[],
+	version: string,
+	/**
+	 * The theme environment, snapshotted by main.tsx BEFORE it loads a project's
+	 * .env. Optional only so a test may call `route` without one; production
+	 * always passes it, and omitting it falls back to "no opinion" (dark) rather
+	 * than reading a process.env that a project may by then have written into.
+	 */
+	themeEnv?: ThemeEnv,
+): Promise<RouteOutcome> {
+	// Top-level flags take precedence over any command token.
+	if (argv.includes("--version") || argv.includes("-v")) {
+		console.log(`magus v${version}`);
+		const result = await checkForUpdates();
+		if (result.updateAvailable) {
+			console.log(`\nUpdate available: v${result.latestVersion}`);
+			console.log("Run: magus upgrade");
+		}
+		return HANDLED(0);
+	}
+
+	if (argv.includes("--help") || argv.includes("-h")) {
+		printHelp(version);
+		return HANDLED(0);
+	}
+
+	const themeFlag = parseThemeFlag(argv);
+	if (!themeFlag.ok) {
+		console.error(themeFlag.message);
+		return HANDLED(1);
+	}
+
+	// Dispatch on argv with the theme tokens removed, so `--theme dark update`
+	// still runs `update`.
+	const [command, ...rest] = themeFlag.rest;
+
+	// Every subcommand paints, and until now only the TUI ever asked which page it
+	// was painting on: `setThemeMode` was called in tui.tsx alone, so `magus
+	// update` kept the "dark" default and printed dark-page fills on a cream
+	// terminal. That is why the report read harsh next to the Models screen.
+	//
+	// No probe here. There is no renderer to ask, and a report must not block on a
+	// terminal reply — so this resolves from the flag, MAGUS_THEME, TERM_THEME
+	// and COLORFGBG, and still falls back to dark when nothing answers, exactly as
+	// before. The TUI keeps its own probing resolution in tui.tsx.
+	//
+	// `themeEnv` is HANDED IN, never re-snapshotted here. main.tsx takes it as
+	// its very first act, before `loadProjectDotenv()` merges a project's .env
+	// into process.env — so the theme comes from the environment magus was
+	// started with and never from the project being inspected. Calling
+	// `snapshotThemeEnv()` at this point would run after that merge and quietly
+	// hand a checked-out repo control of the palette.
+	if (command !== undefined && SUBCOMMANDS.has(command)) {
+		const [{ resolveTheme }, { setThemeMode }] = await Promise.all([
+			import("../ui/theme-resolve.js"),
+			import("../ui/theme-mode.js"),
+		]);
+		const { mode } = await resolveTheme({
+			flag: themeFlag.theme,
+			env: themeEnv ?? {},
+			// A report is not an interactive session: it may be piped, redirected
+			// or read by CI. `isInteractive: false` is what stops the probe being
+			// consulted at all, and the null probe satisfies the signature without
+			// ever writing an OSC query into someone's scrollback.
+			isInteractive: false,
+			probe: async () => null,
+		});
+		setThemeMode(mode);
+	}
+
+	switch (command) {
+		case "update":
+			return HANDLED(await runUpdateCommand(rest));
+		case "upgrade":
+			return HANDLED(await runUpgradeCommand());
+		case "install":
+			return HANDLED(await runInstallCommand(rest));
+		case "profile":
+			return HANDLED(await runProfileCommand(rest));
+		case "models":
+			return HANDLED(await runModelsCommand(rest));
+		case "doctor":
+			return HANDLED(await runDoctorCommand(rest));
+		default:
+			// Bare `magus` or an unrecognized token → interactive TUI.
+			return themeFlag.theme === undefined
+				? LAUNCH_TUI
+				: { ...LAUNCH_TUI, theme: themeFlag.theme };
+	}
+}
+
+function printHelp(version: string): void {
+	console.log(`magus v${version}
+
+TUI tool for managing Claude Code plugins, MCPs, and configuration.
+
+Usage: magus                    Open the interactive TUI
+       magus <command> [args]
+
+Options:
+  -v, --version  Show version and check for updates
+  -h, --help     Show this help message
+  --no-refresh   Skip auto-refresh of marketplaces on startup
+  --theme light|dark   Force the palette. Otherwise: MAGUS_THEME, then
+                       TERM_THEME, then a 250 ms terminal query, then COLORFGBG,
+                       then dark. Only the exact words "light"/"dark" count.
+
+Dependency management — keep this project's plugins, CLI tools and skills
+installed and current. The manifest is .claude/profiles.json, committed; a repo
+without one is offered adoption on first run. See docs/team-configuration.md.
+  install [profile]  Install the profile's plugins, binaries, skills and env at
+                     the manifest's PINNED versions, then activate it.
+                     No argument installs every profile.
+    --check          Report drift only, write nothing (exits 1 in strict mode)
+    --yes, -y        Skip the confirmation prompt
+    --force          Discard unsynced local edits instead of refusing
+  update [profile]   Keep the ACTIVE profile current: install whatever it
+                     declares but this machine lacks, and advance anything
+                     behind the version its marketplace publishes. Only the
+                     newest version is installable, so a pin naming an older
+                     one is reported, not chased.
+                     APPLIES WITHOUT ASKING. It can only move forward — there
+                     is no downgrade and no delete — so the plan is printed as
+                     it runs rather than gated behind a prompt. This includes
+                     running a profile's CLI-tool installers (brew, bun).
+    --dry-run        Show the plan and stop. Writes nothing, exits 0.
+    --check          Report only, write nothing. Exits 1 if anything is
+                     missing or known to be behind — the CI gate.
+  profile list       Show every profile; ● marks the active one
+  profile show <n>   Print a profile's fully resolved closure
+  profile switch <n> Repoint the active profile — offline, no reinstall
+  profile init       Write .claude/profiles.json from this project's setup
+  profile sync       Promote local edits back into .claude/profiles.json
+  doctor             Check binary deps, profile symlinks, and conventions
+    --fix            Apply the repairs it can make itself
+
+Per-subagent model routing — give each subagent its own model and effort. The
+routing lives on the active profile (committed in .claude/profiles.json) and is
+applied by a PreToolUse hook magus registers at user scope.
+  models list        Show the built-in presets; ● marks the active one
+  models use <p>     Apply a preset, record it on the active profile, and
+                     register the hook
+  models status      What is routed now, plus any drift from the config
+  models off         Stop routing; subagents inherit the session model again
+
+Other commands:
+  upgrade            Update magus ITSELF to the latest version
+
+Navigation (TUI):
+  [1] Plugins    [4] Settings   [7] Git State
+  [2] Skills     [5] Profiles   [8] Alias
+  [3] MCP        [6] CLI Tools
+
+Keys:
+  ↑/↓ or j/k     Navigate
+  Enter          Select / Toggle
+  r              Refresh current screen
+  ?              Show help
+  q / Escape     Back / Quit
+`);
+}